How to Use the Tiles API for the xarray backend¶

The /xarray/tiles API is used to generate map tiles via the tiles OGC standard.

This notebook demonstrates how to use the tiles API for the GHRSST Level 4 MUR Global Foundation Sea Surface Temperature Analysis (v4.1) product.

Setup¶

In [1]:

import os
from datetime import datetime, timezone

import earthaccess
import httpx
from folium import Map, TileLayer

titiler_endpoint = os.getenv(
    "TITILER_CMR_ENDPOINT", "https://openveda.cloud/api/titiler-cmr"
)

import os from datetime import datetime, timezone import earthaccess import httpx from folium import Map, TileLayer titiler_endpoint = os.getenv( "TITILER_CMR_ENDPOINT", "https://openveda.cloud/api/titiler-cmr" )

Identify the dataset¶

You can find the MUR SST dataset using the earthaccess.search_datasets function.

In [2]:

datasets = earthaccess.search_datasets(doi="10.5067/GHGMR-4FJ04")
ds = datasets[0]

collection_concept_id = ds["meta"]["concept-id"]
print("Collection Concept-Id: ", collection_concept_id)

print("Abstract: ", ds["umm"]["Abstract"])

datasets = earthaccess.search_datasets(doi="10.5067/GHGMR-4FJ04") ds = datasets[0] collection_concept_id = ds["meta"]["concept-id"] print("Collection Concept-Id: ", collection_concept_id) print("Abstract: ", ds["umm"]["Abstract"])

Collection Concept-Id:  C1996881146-POCLOUD
Abstract:  A Group for High Resolution Sea Surface Temperature (GHRSST) Level 4 sea surface temperature analysis produced as a retrospective dataset (four day latency) and near-real-time dataset (one day latency) at the JPL Physical Oceanography DAAC using wavelets as basis functions in an optimal interpolation approach on a global 0.01 degree grid. The version 4 Multiscale Ultrahigh Resolution (MUR) L4 analysis is based upon nighttime GHRSST L2P skin and subskin SST observations from several instruments including the NASA Advanced Microwave Scanning Radiometer-EOS (AMSR-E), the JAXA Advanced Microwave Scanning Radiometer 2 on GCOM-W1, the Moderate Resolution Imaging Spectroradiometers (MODIS) on the NASA Aqua and Terra platforms, the US Navy microwave WindSat radiometer, the Advanced Very High Resolution Radiometer (AVHRR) on several NOAA satellites, and in situ SST observations from the NOAA iQuam project. The ice concentration data are from the archives at the EUMETSAT Ocean and Sea Ice Satellite Application Facility (OSI SAF) High Latitude Processing Center and are also used for an improved SST parameterization for the high-latitudes.  The dataset also contains additional variables for some granules including the SST anomaly (variable sst_anomaly) derived from a MUR climatology, and the temporal distance in hours to the nearest IR measurement for each pixel (variable dt_1km_data). Variable dt_1km_data first appears in the time series on October 4, 2015,  while sst_anomaly starts July 23, 2019.  This dataset was originally funded by the NASA MEaSUREs program (http://earthdata.nasa.gov/our-community/community-data-system-programs/measures-projects), and created by a team led by Dr. Toshio M. Chin from JPL. It adheres to the GHRSST Data Processing Specification (GDS) version 2 format specifications. Use the file global metadata "history:" attribute to determine if a granule is near-realtime or retrospective.

Explore the collection using the /compatibility endpoint¶

See How to use the Compatibility API Endpoint for how the compatiliby endpoint can be used to identify variable, datetime and rescale parameters.

Define a query for titiler-cmr¶

To use titiler-cmr's endpoints for a NetCDF dataset like this we need to define a date range for the CMR query and a variable to analyze.

In [3]:

variable = "sea_ice_fraction"
datetime_ = datetime(2024, 10, 10, tzinfo=timezone.utc).isoformat()

variable = "sea_ice_fraction" datetime_ = datetime(2024, 10, 10, tzinfo=timezone.utc).isoformat()

Display tiles in an interactive map¶

The /tilejson.json endpoint will provide a parameterized xyz tile URL that can be added to an interactive map.

In [4]:

r = httpx.get(
    f"{titiler_endpoint}/xarray/WebMercatorQuad/tilejson.json",
    params=(
        ("collection_concept_id", collection_concept_id),
        # Temporal range in form of `start_date/end_date`
        ("temporal", datetime_),
        ("variables", variable),
        # We need to set min/max zoom because we don't want to use lowerzoom level (e.g 0)
        # which will results in useless large scale query
        ("minzoom", 2),
        ("maxzoom", 13),
        ("rescale", "0,1"),
        ("colormap_name", "blues_r"),
    ),
    timeout=None,
).json()

print(r)

r = httpx.get( f"{titiler_endpoint}/xarray/WebMercatorQuad/tilejson.json", params=( ("collection_concept_id", collection_concept_id), # Temporal range in form of `start_date/end_date` ("temporal", datetime_), ("variables", variable), # We need to set min/max zoom because we don't want to use lowerzoom level (e.g 0) # which will results in useless large scale query ("minzoom", 2), ("maxzoom", 13), ("rescale", "0,1"), ("colormap_name", "blues_r"), ), timeout=None, ).json() print(r)

{'tilejson': '3.0.0', 'version': '1.0.0', 'scheme': 'xyz', 'tiles': ['https://openveda.cloud/api/titiler-cmr/xarray/tiles/WebMercatorQuad/{z}/{x}/{y}?collection_concept_id=C1996881146-POCLOUD&temporal=2024-10-10T00%3A00%3A00%2B00%3A00&variables=sea_ice_fraction&rescale=0%2C1&colormap_name=blues_r&tilesize=512'], 'minzoom': 2, 'maxzoom': 13, 'bounds': [-180.0, -90.0, 180.0, 90.0], 'center': [0.0, 0.0, 2]}

In [5]:

bounds = r["bounds"]
m = Map(location=(70, -40), zoom_start=3)

TileLayer(
    tiles=r["tiles"][0],
    opacity=1,
    attr="NASA",
).add_to(m)
m

bounds = r["bounds"] m = Map(location=(70, -40), zoom_start=3) TileLayer( tiles=r["tiles"][0], opacity=1, attr="NASA", ).add_to(m) m

Out[5]:

Make this Notebook Trusted to load map: File -> Trust Notebook

Use the expression parameter to combine multiple variables¶

The xarray tiling endpoints can accept a list of variables to use when creating the output images. When combined with the expression parameter this is very powerful!

The following example shows how to create an RGB composite image using the HHHH and HVHV variables from a NISAR GCOV granule.

In [6]:

r = httpx.get(
    f"{titiler_endpoint}/xarray/WebMercatorQuad/tilejson.json",
    params=(
        ("collection_concept_id", "C3622214170-ASF"),
        (
            "granule_ur",
            "NISAR_L2_PR_GCOV_009_026_A_015_4005_DHDH_A_20251229T234707_20251229T234741_X05009_N_F_J_001",
        ),
        ("group", "/science/LSAR/GCOV/grids/frequencyA"),
        ("variables", "HHHH"),  # b1
        ("variables", "HVHV"),  # b2
        ("expression", "10 * log10(b1); 10 * log10(b2); 10 * log10(b1)"),
        ("rescale", "-20, 0"),
        ("rescale", "-30, -5"),
        ("rescale", "-15, 0"),
    ),
    timeout=None,
).json()

m = Map(location=(r["center"][1], r["center"][0]), zoom_start=9)

TileLayer(
    tiles=r["tiles"][0],
    opacity=1,
    attr="NASA/ISRO",
).add_to(m)
m

r = httpx.get( f"{titiler_endpoint}/xarray/WebMercatorQuad/tilejson.json", params=( ("collection_concept_id", "C3622214170-ASF"), ( "granule_ur", "NISAR_L2_PR_GCOV_009_026_A_015_4005_DHDH_A_20251229T234707_20251229T234741_X05009_N_F_J_001", ), ("group", "/science/LSAR/GCOV/grids/frequencyA"), ("variables", "HHHH"), # b1 ("variables", "HVHV"), # b2 ("expression", "10 * log10(b1); 10 * log10(b2); 10 * log10(b1)"), ("rescale", "-20, 0"), ("rescale", "-30, -5"), ("rescale", "-15, 0"), ), timeout=None, ).json() m = Map(location=(r["center"][1], r["center"][0]), zoom_start=9) TileLayer( tiles=r["tiles"][0], opacity=1, attr="NASA/ISRO", ).add_to(m) m

Out[6]:

Make this Notebook Trusted to load map: File -> Trust Notebook

In [ ]: