How to use the Compatibility API¶
The /compatibility endpoint displays information about the collection and returns some details about a sample granule. The output is helpful for understanding the structure of the collection and the granules so that you can craft the right set of parameters for visualization or statistics requests.
This notebook demonstrates how to use the compatibility endpoint for th GHRSST Level 4 MUR Global Foundation Sea Surface Temperature Analysis (v4.1) dataset.
Setup¶
In [1]:
Copied!
import json
import earthaccess
import httpx
titiler_endpoint = "https://staging.openveda.cloud/api/titiler-cmr" # staging endpoint
import json
import earthaccess
import httpx
titiler_endpoint = "https://staging.openveda.cloud/api/titiler-cmr" # staging endpoint
Identify the dataset¶
You can find the MUR SST dataset using the earthaccess.search_datasets function.
In [2]:
Copied!
datasets = earthaccess.search_datasets(doi="10.5067/GHGMR-4FJ04")
ds = datasets[0]
concept_id = ds["meta"]["concept-id"]
print("Concept-Id: ", concept_id)
print("Abstract: ", ds["umm"]["Abstract"])
datasets = earthaccess.search_datasets(doi="10.5067/GHGMR-4FJ04")
ds = datasets[0]
concept_id = ds["meta"]["concept-id"]
print("Concept-Id: ", concept_id)
print("Abstract: ", ds["umm"]["Abstract"])
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¶
In [3]:
Copied!
compatibility_response = httpx.get(
f"{titiler_endpoint}/compatibility",
params={"concept_id": concept_id},
timeout=None,
).json()
print(json.dumps(compatibility_response, indent=2))
compatibility_response = httpx.get(
f"{titiler_endpoint}/compatibility",
params={"concept_id": concept_id},
timeout=None,
).json()
print(json.dumps(compatibility_response, indent=2))
{
"concept_id": "C1996881146-POCLOUD",
"backend": "xarray",
"datetime": [
{
"RangeDateTimes": [
{
"BeginningDateTime": "2002-05-31T21:00:00.000Z"
}
]
}
],
"variables": {
"analysed_sst": {
"shape": [
1,
17999,
36000
],
"dtype": "float64",
"min": 271.34999999999997,
"max": 305.775,
"mean": 286.0979589995505,
"p01": 271.34999999999997,
"p05": 271.34999999999997,
"p95": 302.53844999999995,
"p99": 303.49899999999997
},
"analysis_error": {
"shape": [
1,
17999,
36000
],
"dtype": "float64",
"min": 0.35000000000000003,
"max": 0.42,
"mean": 0.3777938704055034,
"p01": 0.35000000000000003,
"p05": 0.35000000000000003,
"p95": 0.4,
"p99": 0.41000000000000003
},
"mask": {
"shape": [
1,
17999,
36000
],
"dtype": "float32",
"min": 1.0,
"max": 13.0,
"mean": 2.8844234943389893,
"p01": 1.0,
"p05": 1.0,
"p95": 9.0,
"p99": 9.0
},
"sea_ice_fraction": {
"shape": [
1,
17999,
36000
],
"dtype": "float64",
"min": 0.0,
"max": 1.0,
"mean": 0.46007744553963387,
"p01": 0.0,
"p05": 0.0,
"p95": 1.0,
"p99": 1.0
}
},
"dimensions": {
"time": 1,
"lat": 17999,
"lon": 36000
},
"coordinates": {
"time": {
"size": 1,
"dtype": "datetime64[ns]"
},
"lat": {
"size": 17999,
"dtype": "float32",
"min": -89.98999786376953,
"max": 89.98999786376953
},
"lon": {
"size": 36000,
"dtype": "float32",
"min": -179.99000549316406,
"max": 180.0
}
},
"example_assets": "s3://podaac-ops-cumulus-protected/MUR-JPL-L4-GLOB-v4.1/20020601090000-JPL-L4_GHRSST-SSTfnd-MUR-GLOB-v02.0-fv04.1.nc"
}
The details from the sample granule show that it is a NetCDF file with four variables (analysed_sst, analysis_error, mask, and sea_ice_fraction) and each contains an array with a single time coordinate. The datetime key shows the reported temporal range from CMR which indicates that the dataset has granules from 2002-05-31 to present. For each variable several summary statistics are available to help you craft min/max values for the rescale parameter.
This information is handy for generating tiles via the tiles API, which you can learn more about in the Tiles API Documentation.