Skip to content

Commit 240327f

Browse files
grabermtwgrabermtw
authored
Merge pull request #25 from nasa-gibs/GITC-5878-describe-domains
Added DescribeDomains documentation to access-basics.md
2 parents b74b701 + 11c0706 commit 240327f

File tree

1 file changed

+44
-7
lines changed

1 file changed

+44
-7
lines changed

‎docs/access-basics.md

Lines changed: 44 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -52,14 +52,14 @@ The above elements may be found in examples of both RESTful and KVP access patte
5252
- *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"}
5353

5454
#### Service Endpoints
55-
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.
55+
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.
5656

57-
| Projection | Endpoint Root | GetCapabilities | GetTile |
58-
| ---------------------- | --------------- | --------------- | --------------- |
59-
| 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"} |
60-
| 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"} |
61-
| 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"} |
62-
| 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"} |
57+
| Projection | Endpoint Root | GetCapabilities | GetTile | DescribeDomains |
58+
| ---------------------- | --------------- | --------------- | --------------- | --------------- |
59+
| 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"} |
60+
| 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"} |
61+
| 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"} |
62+
| 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"} |
6363

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

194194
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.
195195

196+
**DescribeDomains**
197+
198+
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).
199+
200+
DescribeDomains requests utilize the following URI/query-string elements.
201+
202+
- *LayerIdentifier* - Unique identifier for a visualization within a specific service endpoint
203+
- *Time* - An optional parameter to only request periods that occur within an inclusive domain bounded by a specified `StartDatetime` and `EndDatetime`.
204+
- For REST requests, this parameter should take the form of `StartDatetime--EndDatetime`.
205+
- For KVP requests, this parameter should take the form of `StartDatetime/EndDatetime`.
206+
- 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`.
207+
- 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`.
208+
- Not specifying a *Time* parameter or specifying `all` will return all available periods for the layer.
209+
- *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`.
210+
- *TileMatrixSet* - The identifier for the Tile Matrix Set that the visualization utilizes
211+
212+
The above elements may be found in examples of both RESTful and KVP access patterns seen below:
213+
214+
- **REST**
215+
- *Pattern* - https://gibs.earthdata.nasa.gov/wmts/epsg4326/best/{*LayerIdentifier*}/default/{*TileMatrixSet*}/{*BBox*}/{*Time*}.xml
216+
- *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"}
217+
- **KVP**
218+
- *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*}
219+
- *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"}
220+
221+
Time information can be found in the DimensionDomain element of the returned XML document:
222+
223+
```xml
224+
<DimensionDomain>
225+
<ows:Identifier>time</ows:Identifier>
226+
<Domain>2018-05-26/2018-11-03/P1D,2019-08-23/2021-09-03/P1D</Domain>
227+
<Size>2</Size>
228+
</DimensionDomain>
229+
```
230+
231+
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.
232+
196233
<hr style="border:1px solid gray"> </hr>
197234

198235
### OGC Web Map Service (WMS)

0 commit comments

Comments
 (0)