Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Added DescribeDomains documentation to access-basics.md #25

Merged
merged 2 commits into from
Jun 7, 2024
Merged

Added DescribeDomains documentation to access-basics.md #25

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
894e246
Added DescribeDomains documentation to access-basics.md
May 23, 2024
11c0706
Fixed DescribeDomains example URLs
Jun 5, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
51 changes: 44 additions & 7 deletions docs/access-basics.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -52,14 +52,14 @@ The above elements may be found in examples of both RESTful and KVP access patte
- *Example* - [https://gibs.earthdata.nasa.gov/wmts/epsg4326/best/wmts.cgi?Service=WMTS&Request=GetTile&Version=1.0.0 &layer=MODIS_Terra_CorrectedReflectance_TrueColor&tilematrixset=250m&TileMatrix=6&TileCol=36&TileRow=13&style=default&TIME=2012-07-09&Format=image%2Fjpeg](https://gibs.earthdata.nasa.gov/wmts/epsg4326/best/wmts.cgi?Service=WMTS&Request=GetTile&Version=1.0.0&layer=MODIS_Terra_CorrectedReflectance_TrueColor&tilematrixset=250m&TileMatrix=6&TileCol=36&TileRow=13&TIME=2012-07-09&style=default&Format=image%2Fjpeg){:target="_blank"}

#### Service Endpoints
The following table contains the root service endpoint for each GIBS-supported map projection along with sample requests for the WMTS GetCapabilities and GetTile requests via both RESTful and KVP access methods.
The following table contains the root service endpoint for each GIBS-supported map projection along with sample requests for the WMTS GetCapabilities, GetTile, and DescribeDomains requests via both RESTful and KVP access methods. See [Time Dimension](#time-dimension) for additional details on DescribeDomains.

| Projection | Endpoint Root | GetCapabilities | GetTile |
| ---------------------- | --------------- | --------------- | --------------- |
| Geographic (EPSG:4326) | **REST:** https://gibs.earthdata.nasa.gov/wmts/epsg4326/best/ <br/> **KVP:** https://gibs.earthdata.nasa.gov/wmts/epsg4326/best/wmts.cgi? | [REST](https://gibs.earthdata.nasa.gov/wmts/epsg4326/best/1.0.0/WMTSCapabilities.xml){:target="_blank"} / [KVP](https://gibs.earthdata.nasa.gov/wmts/epsg4326/best/wmts.cgi?SERVICE=WMTS&request=GetCapabilities){:target="_blank"} | [REST](https://gibs.earthdata.nasa.gov/wmts/epsg4326/best/Landsat_WELD_CorrectedReflectance_Bands157_Global_Annual/default/1999-01-03/31.25m/3/2/3.jpg){:target="_blank"} / [KVP](https://gibs.earthdata.nasa.gov/wmts/epsg4326/best/wmts.cgi?TIME=default&layer=Landsat_WELD_CorrectedReflectance_Bands157_Global_Annual&style=default&tilematrixset=31.25m&Service=WMTS&Request=GetTile&Version=1.0.0&Format=image%2Fjpeg&TileMatrix=3&TileCol=3&TileRow=2&TIME=1999-01-03){:target="_blank"} |
| NSIDC Sea Ice Polar Stereographic North (EPSG:3413) | **REST:** https://gibs.earthdata.nasa.gov/wmts/epsg3413/best/ <br/>**KVP:** https://gibs.earthdata.nasa.gov/wmts/epsg3413/best/wmts.cgi? | [REST](https://gibs.earthdata.nasa.gov/wmts/epsg3413/best/1.0.0/WMTSCapabilities.xml){:target="_blank"} / [KVP](https://gibs.earthdata.nasa.gov/wmts/epsg3413/best/wmts.cgi?SERVICE=WMTS&request=GetCapabilities){:target="_blank"} | [REST](https://gibs.earthdata.nasa.gov/wmts/epsg3413/best/Landsat_WELD_CorrectedReflectance_Bands157_Global_Annual/default/1999-01-03/31.25m/4/8/9.jpg){:target="_blank"} / [KVP](https://gitc.earthdata.nasa.gov/wmts/epsg3413/best/wmts.cgi?TIME=default&layer=Landsat_WELD_CorrectedReflectance_Bands157_Global_Annual&style=default&tilematrixset=31.25m&Service=WMTS&Request=GetTile&Version=1.0.0&Format=image%2Fjpeg&TileMatrix=4&TileCol=9&TileRow=8&TIME=1999-01-03){:target="_blank"} |
| Antarctic Polar Stereographic / WGS 84 (EPSG:3031) | **REST:** https://gibs.earthdata.nasa.gov/wmts/epsg3031/best/ <br/>**KVP:** https://gibs.earthdata.nasa.gov/wmts/epsg3031/best/wmts.cgi? | [REST](https://gibs.earthdata.nasa.gov/wmts/epsg3031/best/1.0.0/WMTSCapabilities.xml){:target="_blank"} / [KVP](https://gibs.earthdata.nasa.gov/wmts/epsg3031/best/wmts.cgi?SERVICE=WMTS&request=GetCapabilities){:target="_blank"} | [REST](https://gibs.earthdata.nasa.gov/wmts/epsg3031/best/MODIS_Terra_Brightness_Temp_Band31_Day/default/2019-09-24/1km/2/1/1.png){:target="_blank"} / [KVP](https://gibs.earthdata.nasa.gov/wmts/epsg3031/best/wmts.cgi?TIME=default&layer=MODIS_Terra_Brightness_Temp_Band31_Day&style=default&tilematrixset=1km&Service=WMTS&Request=GetTile&Version=1.0.0&Format=image%2Fpng&TileMatrix=2&TileCol=1&TileRow=1&TIME=2019-09-24){:target="_blank"} |
| Web Mercator - (EPSG:3857) | **REST:** https://gibs.earthdata.nasa.gov/wmts/epsg3857/best/ <br/>**KVP:** https://gibs.earthdata.nasa.gov/wmts/epsg3857/best/wmts.cgi? | [REST](https://gibs.earthdata.nasa.gov/wmts/epsg3857/best/1.0.0/WMTSCapabilities.xml){:target="_blank"} / [KVP](https://gibs.earthdata.nasa.gov/wmts/epsg3857/best/wmts.cgi?SERVICE=WMTS&request=GetCapabilities){:target="_blank"} | [REST](https://gibs.earthdata.nasa.gov/wmts/epsg3857/best/Landsat_WELD_CorrectedReflectance_Bands157_Global_Annual/default/1999-01-02/GoogleMapsCompatible_Level12/4/2/3.jpg){:target="_blank"} / [KVP](https://gibs.earthdata.nasa.gov/wmts/epsg3857/best/wmts.cgi?TIME=default&layer=Landsat_WELD_CorrectedReflectance_Bands157_Global_Annual&style=default&tilematrixset=GoogleMapsCompatible_Level12&Service=WMTS&Request=GetTile&Version=1.0.0&Format=image%2Fjpeg&TileMatrix=4&TileCol=3&TileRow=2&TIME=1999-01-02){:target="_blank"} |
| Projection | Endpoint Root | GetCapabilities | GetTile | DescribeDomains |
| ---------------------- | --------------- | --------------- | --------------- | --------------- |
| Geographic (EPSG:4326) | **REST:** https://gibs.earthdata.nasa.gov/wmts/epsg4326/best/ <br/> **KVP:** https://gibs.earthdata.nasa.gov/wmts/epsg4326/best/wmts.cgi? | [REST](https://gibs.earthdata.nasa.gov/wmts/epsg4326/best/1.0.0/WMTSCapabilities.xml){:target="_blank"} / [KVP](https://gibs.earthdata.nasa.gov/wmts/epsg4326/best/wmts.cgi?SERVICE=WMTS&request=GetCapabilities){:target="_blank"} | [REST](https://gibs.earthdata.nasa.gov/wmts/epsg4326/best/Landsat_WELD_CorrectedReflectance_Bands157_Global_Annual/default/1999-01-03/31.25m/3/2/3.jpg){:target="_blank"} / [KVP](https://gibs.earthdata.nasa.gov/wmts/epsg4326/best/wmts.cgi?TIME=default&layer=Landsat_WELD_CorrectedReflectance_Bands157_Global_Annual&style=default&tilematrixset=31.25m&Service=WMTS&Request=GetTile&Version=1.0.0&Format=image%2Fjpeg&TileMatrix=3&TileCol=3&TileRow=2&TIME=1999-01-03){:target="_blank"} | [REST](https://gibs.earthdata.nasa.gov/wmts/epsg4326/best/1.0.0/Landsat_WELD_CorrectedReflectance_Bands157_Global_Annual/default/31.25m/all/all.xml){:target="_blank"} / [KVP](https://gibs.earthdata.nasa.gov/wmts/epsg4326/best/wmts.cgi?&layer=Landsat_WELD_CorrectedReflectance_Bands157_Global_Annual&tilematrixset=31.25m&Service=WMTS&Request=DescribeDomains&Version=1.0.0){:target="_blank"} |
| NSIDC Sea Ice Polar Stereographic North (EPSG:3413) | **REST:** https://gibs.earthdata.nasa.gov/wmts/epsg3413/best/ <br/>**KVP:** https://gibs.earthdata.nasa.gov/wmts/epsg3413/best/wmts.cgi? | [REST](https://gibs.earthdata.nasa.gov/wmts/epsg3413/best/1.0.0/WMTSCapabilities.xml){:target="_blank"} / [KVP](https://gibs.earthdata.nasa.gov/wmts/epsg3413/best/wmts.cgi?SERVICE=WMTS&request=GetCapabilities){:target="_blank"} | [REST](https://gibs.earthdata.nasa.gov/wmts/epsg3413/best/Landsat_WELD_CorrectedReflectance_Bands157_Global_Annual/default/1999-01-03/31.25m/4/8/9.jpg){:target="_blank"} / [KVP](https://gitc.earthdata.nasa.gov/wmts/epsg3413/best/wmts.cgi?TIME=default&layer=Landsat_WELD_CorrectedReflectance_Bands157_Global_Annual&style=default&tilematrixset=31.25m&Service=WMTS&Request=GetTile&Version=1.0.0&Format=image%2Fjpeg&TileMatrix=4&TileCol=9&TileRow=8&TIME=1999-01-03){:target="_blank"} | [REST](https://gibs.earthdata.nasa.gov/wmts/epsg3413/best/1.0.0/Landsat_WELD_CorrectedReflectance_Bands157_Global_Annual/default/31.25m/all/all.xml){:target="_blank"} / [KVP](https://gibs.earthdata.nasa.gov/wmts/epsg3413/best/wmts.cgi?&layer=Landsat_WELD_CorrectedReflectance_Bands157_Global_Annual&tilematrixset=31.25m&Service=WMTS&Request=DescribeDomains&Version=1.0.0){:target="_blank"} |
| Antarctic Polar Stereographic / WGS 84 (EPSG:3031) | **REST:** https://gibs.earthdata.nasa.gov/wmts/epsg3031/best/ <br/>**KVP:** https://gibs.earthdata.nasa.gov/wmts/epsg3031/best/wmts.cgi? | [REST](https://gibs.earthdata.nasa.gov/wmts/epsg3031/best/1.0.0/WMTSCapabilities.xml){:target="_blank"} / [KVP](https://gibs.earthdata.nasa.gov/wmts/epsg3031/best/wmts.cgi?SERVICE=WMTS&request=GetCapabilities){:target="_blank"} | [REST](https://gibs.earthdata.nasa.gov/wmts/epsg3031/best/MODIS_Terra_Brightness_Temp_Band31_Day/default/2019-09-24/1km/2/1/1.png){:target="_blank"} / [KVP](https://gibs.earthdata.nasa.gov/wmts/epsg3031/best/wmts.cgi?TIME=default&layer=MODIS_Terra_Brightness_Temp_Band31_Day&style=default&tilematrixset=1km&Service=WMTS&Request=GetTile&Version=1.0.0&Format=image%2Fpng&TileMatrix=2&TileCol=1&TileRow=1&TIME=2019-09-24){:target="_blank"} | [REST](https://gibs.earthdata.nasa.gov/wmts/epsg3031/best/1.0.0/MODIS_Terra_Brightness_Temp_Band31_Day/default/1km/all/all.xml){:target="_blank"} / [KVP](https://gibs.earthdata.nasa.gov/wmts/epsg3031/best/wmts.cgi?layer=MODIS_Terra_Brightness_Temp_Band31_Day&style=default&tilematrixset=1km&Service=WMTS&Request=DescribeDomains&Version=1.0.0){:target="_blank"} |
| Web Mercator - (EPSG:3857) | **REST:** https://gibs.earthdata.nasa.gov/wmts/epsg3857/best/ <br/>**KVP:** https://gibs.earthdata.nasa.gov/wmts/epsg3857/best/wmts.cgi? | [REST](https://gibs.earthdata.nasa.gov/wmts/epsg3857/best/1.0.0/WMTSCapabilities.xml){:target="_blank"} / [KVP](https://gibs.earthdata.nasa.gov/wmts/epsg3857/best/wmts.cgi?SERVICE=WMTS&request=GetCapabilities){:target="_blank"} | [REST](https://gibs.earthdata.nasa.gov/wmts/epsg3857/best/Landsat_WELD_CorrectedReflectance_Bands157_Global_Annual/default/1999-01-02/GoogleMapsCompatible_Level12/4/2/3.jpg){:target="_blank"} / [KVP](https://gibs.earthdata.nasa.gov/wmts/epsg3857/best/wmts.cgi?TIME=default&layer=Landsat_WELD_CorrectedReflectance_Bands157_Global_Annual&style=default&tilematrixset=GoogleMapsCompatible_Level12&Service=WMTS&Request=GetTile&Version=1.0.0&Format=image%2Fjpeg&TileMatrix=4&TileCol=3&TileRow=2&TIME=1999-01-02){:target="_blank"} | [REST](https://gibs.earthdata.nasa.gov/wmts/epsg3857/best/1.0.0/Landsat_WELD_CorrectedReflectance_Bands157_Global_Annual/default/31.25m/all/all.xml){:target="_blank"} / [KVP](https://gibs.earthdata.nasa.gov/wmts/epsg3857/best/wmts.cgi?&layer=Landsat_WELD_CorrectedReflectance_Bands157_Global_Annual&tilematrixset=31.25m&Service=WMTS&Request=DescribeDomains&Version=1.0.0){:target="_blank"} |

#### Example Clients
The following clients support the GIBS WMTS visualization services:
Expand Down Expand Up @@ -193,6 +193,43 @@ Visualizations that represent "subdaily" (e.g. period < 1 day) require that the

If the `time` dimension is omitted in the WMTS request, GIBS will return tiles for the default date, as specified in the `<Default>` tag. Note that GIBS' imagery layers all have a value of false in the `<Current>` tag which means that the special current keyword cannot be provided as the time value. However, GIBS does support use of the special `default` value, which results in the same response as though the date were omitted.

**DescribeDomains**

To maintain a manageable size of the GetCapabilities document, the `Dimension` data structure in the WMTS GetCapabilities will display only the latest 100 time periods for each layer. To obtain all time periods for a layer, GIBS WMTS also supports the proposed DescribeDomains request as proposed by the [OGC Testbed-12 WMS/WMTS Enhanced Engineering Report](https://docs.ogc.org/per/16-042r1.html#_compact_domain_inspection).

DescribeDomains requests utilize the following URI/query-string elements.

- *LayerIdentifier* - Unique identifier for a visualization within a specific service endpoint
- *Time* - An optional parameter to only request periods that occur within an inclusive domain bounded by a specified `StartDatetime` and `EndDatetime`.
- For REST requests, this parameter should take the form of `StartDatetime--EndDatetime`.
- For KVP requests, this parameter should take the form of `StartDatetime/EndDatetime`.
- If only one datetime is specified without the delimiter `--` or `/`, or is followed by the delimiter (i.e. `StartDatetime--` or `StartDatetime/`), then the specified datetime will be treated as a `StartDatetime` with an unbounded `EndDatetime`.
- If only one datetime is specified and is preceeded by `--` for REST requests or `/` for KVP requests (i.e. `--EndDatetime` or `/EndDatetime`), then the specified datetime will be treated as an `EndDatetime` with an unbounded `StartDatetime`.
- Not specifying a *Time* parameter or specifying `all` will return all available periods for the layer.
- *BBox* - A parameter to specify the bounding box to be used. All layers have the same extent in GIBS, so this option has no effect on the returned result. Also accepts `all`.
- *TileMatrixSet* - The identifier for the Tile Matrix Set that the visualization utilizes

The above elements may be found in examples of both RESTful and KVP access patterns seen below:

- **REST**
- *Pattern* - https://gibs.earthdata.nasa.gov/wmts/epsg4326/best/{*LayerIdentifier*}/default/{*TileMatrixSet*}/{*BBox*}/{*Time*}.xml
- *Example* - [https://gibs.earthdata.nasa.gov/wmts/epsg4326/best/1.0.0/MODIS_Terra_CorrectedReflectance_TrueColor/default/250m/all/2015-01-26--2022-11-03.xml](https://gibs.earthdata.nasa.gov/wmts/epsg4326/best/1.0.0/MODIS_Terra_CorrectedReflectance_TrueColor/default/250m/all/2015-01-26--2022-11-03.xml){:target="_blank"}
- **KVP**
- *Pattern* - https://gibs.earthdata.nasa.gov/wmts/epsg4326/best/wmts.cgi?SERVICE=WMTS&REQUEST=DescribeDomains&VERSION=1.0.0&LAYER={*LayerIdentifier*}&TILEMATRIXSET={*TileMatrixSet*}&TIME={*Time*}
- *Example* - [https://gibs.earthdata.nasa.gov/wmts/epsg4326/best/wmts.cgi?Service=WMTS&Request=DescribeDomains&Version=1.0.0&layer=MODIS_Terra_CorrectedReflectance_TrueColor&tilematrixset=250m&TIME=2015-01-26/2022-11-03](https://gibs.earthdata.nasa.gov/wmts/epsg4326/best/wmts.cgi?Service=WMTS&Request=DescribeDomains&Version=1.0.0&layer=MODIS_Terra_CorrectedReflectance_TrueColor&tilematrixset=250m&TIME=2015-01-26/2022-11-03){:target="_blank"}

Time information can be found in the DimensionDomain element of the returned XML document:

```xml
<DimensionDomain>
<ows:Identifier>time</ows:Identifier>
<Domain>2018-05-26/2018-11-03/P1D,2019-08-23/2021-09-03/P1D</Domain>
<Size>2</Size>
</DimensionDomain>
```

The `<Domain>` element will contain a comma-separated list of time periods. The `<Size>` element will contain an integer corresponding to the number of time periods in the `<Domain>` element.

<hr style="border:1px solid gray"> </hr>

### OGC Web Map Service (WMS)
Expand Down