Merge pull request #25 from nasa-gibs/GITC-5878-describe-domains

Added DescribeDomains documentation to access-basics.md
nasa-gibs · Jun 7, 2024 · 240327f · 240327f
2 parents b74b701 + 11c0706
commit 240327f
Showing 1 changed file with 44 additions and 7 deletions.
diff --git a/docs/access-basics.md b/docs/access-basics.md
@@ -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:
@@ -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)