Template (Using the raster API)

This notebook is intended to act as a template for the example notebooks that use the raster API. These green cells should all be deleted and in several sections only one of the provided cells should be included in the notebook.

Update the link in the following section.

Run this notebook

You can launch this notbook using mybinder, by clicking the button below.

Fill in the text in italics in the following cells

Approach

1. list a few steps that outline the approach
2. you will be taking in this notebook

# include all your imports in this cell
import folium
import requests

About the data

Optional description of the dataset.

Declare your collection of interest

You can discover available collections the following ways:

• Programmatically: see example in the list-collections.ipynb notebook
• JSON API: https://openveda.cloud/api/stac/collections
• STAC Browser: http://openveda.cloud

STAC_API_URL = "https://openveda.cloud/api/stac"
RASTER_API_URL = "https://openveda.cloud/api/raster"

collection_id = 

Next step is to get STAC objects from the STAC API. In some notebooks we get the collection and use all the items, and in others we search for specific items.

Fetch STAC collection

We will use requests to fetch all the metadata about the collection of interest from STAC.

collection = requests.get(f"{STAC_API_URL}/collections/{collection_id}").json()
collection

Fetch STAC item for a particular time

We can use the search API to find the item that matches exactly our time of interest.

response = requests.post(
    f"{STAC_API_URL}/search",
    json={
        "collections": [collection_id],
        "query": {"datetime": {"eq": "2021-01-01T00:00:00"}},
        "limit": 100,
    },
).json()
items = response["features"]

The next step is often to define an Area of Interest. Note that it is preferred to get large geojson objects directly from their source rather than storing them in this repository or inlining them in the notebook. Here is an example of what that might look like.

Define an AOI

We can fetch GeoJSON for metropolitan France and Corsica (excluding overseas territories) from an authoritative online source (https://gadm.org/download_country.html).

response = requests.get(
    "https://geodata.ucdavis.edu/gadm/gadm4.1/json/gadm41_FRA_0.json"
)

# If anything goes wrong with this request output error contents
assert response.ok, response.text

result = response.json()
print(f"There are {len(result['features'])} features in this collection")

That is the geojson for a feature collection, but since there is only one feature in it we can grab just that.

aoi = result["features"][0]

Let’s take a look at this AOI on a map

m = folium.Map(
    location=[40, 0],
    zoom_start=2,
)

folium.GeoJson(aoi, name="AOI").add_to(m)
m

With the STAC object and optionally the AOI in hand, the next step is to do some analysis. The sections in the rest of the notebooks are totally up to you! Here is one idea though :)

Use the STAC Item to get tiles with the RASTER API

We pass the item_id, collection id, and rescale_values in to the RASTER API /collections/{collection_id}/items/{item_id}/tilejson.json endpoint and get back a tile. See the tips below for choosing visualization parameters for your tiles.

Colormap Tip:
Find the list of available colormaps at {RASTER_API}/colorMaps (openveda.cloud/api/raster/colorMaps) and get colormap metadata and/or legend image at {RASTER_API}/colorMaps/{colorMapName} (See docs at openveda.cloud/api/raster/docs#/ColorMaps/getColorMap)

Tiling schemes Tip:
Find the list of available tile matrix set ids at {RASTER_API}/tileMatrixSets (openveda.cloud/api/raster/tileMatrixSets) and get tiling scheme metadata at {RASTER_API}/colorMaps/{colorMapName} (See docs at openveda.cloud/api/raster/docs#/tileMatrixSets/tileMatrixSetId)

Raster rescale range tip:
Get the statistics for item assets at {RASTER_API}/collections/{collection_id/items/{item_id}/statistics ()

# Start with the first item returned
item = items[0]

# Here is a default tile matrix id
tile_matrix_set_id = "WebMercatorQuad"

# Adjust these values to find the ideal range for the range of data you will be visualizing
rescale_min = 0
rescale_max = 1

# Set the asset key you want to visualize (many STAC Items in the VEDA catalog have a cog_default assets)
asset_key = "cog_default"

# Choose a colormap
colormap_name = "viridis"

# Use stac item url with to get tilejson from raster api
url = f"{RASTER_API_URL}/collections/{collection_id}/items/{item['id']}/{tile_matrix_set_id}/tilejson.json"

tiles = requests.get(
    url,
    params = {
        "assets": asset_key,
        "colormap_name": colormap_name,
        "rescale": f"{rescale_min},{rescale_max}"
    }
).json()
tiles

With that tile url in hand we can create a simple visualization using folium.

folium.Map(
    tiles=tiles["tiles"][0],
    attr="VEDA",
)