Introduction

DSMCoverage Service will return a JSON file containing coverage of Digital Surface Model (DSM) available from the Vexcel library. The output JSON will contain the geometry of the geographic coverage for the query. This service is particularly useful to:

Identify the available layers available over a given location
Identify the specific AOIs available over a given location and the Child AOIs within the AOIs
Compare coverage between sensor types (layers)
See the full extent of an AOI’s coverage

Technical Details

This service operates by process of elimination to identify Digital Surface Model (DSM) coverage; by using no refining parameters it is possible to receive complete coverage across the entire Vexcel library. The layer, aoi, and wkt parameters can be used to narrow a search for specific types or locations of imagery. While this service primarily exists to provide coverage geometry, a handful of metadata attributes are also available to help identify AOIs.

Special considerations

DSM coverage implies Ortho coverage but not the other way around. DSM vs Ortho

Output Specifications:

JSON file format
Metadata:
- AOI name
- Coverage Type
- Min GSD
- Max GSD
- Min Capture Date
- Max Capture Date
- Layer
- AOI Area
- AOI Max Zoom
- AOI Pretty Name
- Child AOI(s)

Base URL

This service responds to requests from the following URL:

https://api.gic.org/metadata/DSMCoverage?token={token}

Parameters

Parameter	Parameter Type	Data Type	Description	Example Format	Notes

Parameter	Parameter Type	Data Type	Description	Example Format	Notes
Mandatory:
`token`	Key Value Pair	String	Token used to authenticate the requests.	`token={token}`	Use the Authenticate Service to receive a token. A token will temporarily be stored in cache and may be omitted on subsequent calls.
Optional:
`layer`	Key Value Pair	String	Desired layers, separated by commas. `bluesky-ultra` Urban data collected with Osprey (7.5cm GSD) `bluesky-ultra-europe` Urban data collected with Osprey in Europe (7.5cm GSD) `bluesky-ultra-japan` Urban data collected with Osprey in Japan (7.5cm GSD) `bluesky-ultra-oceania` Urban data collected with Osprey in Oceania (7.5cm GSD) `bluesky-high` Wide area data collected with Condor (15-20cm GSD) `bluesky-high-europe` Wide area data collected with Condor in Europe (15-20cm GSD)	`layer=bluesky-ultra`
`aoi`	Key Value Pair	String	The identifier of the specific Area of Interest (AOI) containing the DSM.	`aoi=EUEUCON2001` bluesky-ultra: `aoi=us-tx-pearland-2021` bluesky-ultra-europe: `aoi=it-62-rome-2022` bluesky-ultra-japan: `aoi=jp-05-akita-2022` bluesky-ultra-oceania: `aoi=au-qld-sunshinecoast-2019` bluesky-high: `aoi=USUSCON2001` bluesky-high-europe: `aoi=EUEUCON2201`
`ChildAOI`	Key Value Pair	String	The identifier of the specific childAOI. It will return the coverage of the AOI(s) that contain it, and the specified childAOI.	`ChildAOI=n41e13-it-lt-aprilia-2020` bluesky-ultra: `ChildAOI=us-tx-pearland-2021` bluesky-ultra-europe: `ChildAOI=it-62-rome-2022` bluesky-ultra-japan: `ChildAOI=jp-05-akita-2022` bluesky-ultra-oceania: `ChildAOI=au-qld-sunshinecoast-2019` bluesky-high: `ChildAOI=n33w87-us-al-tuscaloosa-2019` bluesky-high-europe: `ChildAOI=n53e14-de-bb-templin-2022`
`wkt`	Key Value Pair	String	The well-known-text (WKT) representation of the requested point or polygon to filter the coverages intersected by this zone.	`wkt=POINT(12.4920256 41.8897457)`
`EPSG`	Key Value Pair	Integer	The EPSG code determines the projection of the provided `wkt` point or polygon.	`EPSG=4326`
`include`	Key Value Pair	String	Fields to be included on the JSON result, separated by comas. `aoi.avg_gsd` - Average GSD of the AOI `aoi.child_aoi.avg_gsd` - Average GSD of the Child AOI	`include=aoi.child_aoi.avg_gsd`
`skip`	Key Value Pair	String	Fields to be skipped on the JSON result, separated by comas. `aoi.aoi` - Skips AOI field inside AOIs `aoi.coverage_type` - Skips Coverage Type Field inside AOIs `aoi.min_gsd`- Skips Min GSD field inside AOIs `aoi.max_gsd`- Skips Max GSD field inside AOIs `aoi.min_capture_date`- Skips Min Capture Date field inside AOIs `aoi.max_capture_date`- Skips Max Capture Date field inside AOIs `aoi.layer`- Skips Layer field inside AOIs `aoi.area`- Skips AOI Area field inside AOIs `aoi.max_zoom` - Skips Max Zoom Level of the DSM tile available inside AOIs `aoi.pretty_name` - Skips Pretty Name inside AOIs `aoi.geometry`- Skips Geometry field inside AOIs `aoi.child_aoi`- Skips all the Child AOIs (and their inner fields) inside AOIs `aoi.child_aoi.name`- Skips Name field inside Child AOIs `aoi.child_aoi.coverage_type`- Skips Coverage Type field inside Child AOIs `aoi.child_aoi.coverage`- Skips Coverage field inside Child AOIs `aoi.child_aoi.min_gsd`- Skips Min GSD field inside Child AOIs `aoi.child_aoi.max_gsd`- Skips Max GSD field inside Child AOIs `aoi.child_aoi.min_date`- Skips Min Date field inside Child AOIs `aoi.child_aoi.max_date`- Skips Max Date field inside Child AOIs `aoi.child_aoi.max_zoom` - Skips Max Zoom Level of the DSM tile available inside Child AOIs `aoi.child_aoi.camera_technology`- Skips Camera Technology field inside Child AOIs `aoi.child_aoi.pretty_name` - Skips Pretty Name field inside Child AOIs `aoi.child_aoi.first_publishing_date` - Skips First Publishing Date field inside Child AOIs `aoi.child_aoi.last_publishing_date` - Skips Last Publishing Date field inside Child AOIs	`skip=aoi.geometry,aoi.child_aoi.coverage`
`format`	Key Value Pair	String	Desired output format of the geospatial polygon within the response text.	`format=wkt`

Examples

Texas City, TX - Demonstrating AOI, epsg, skip and include:
https://api.gic.org/metadata/DSMCoverage?aoi=us-tx-pearland-2021&epsg=32615&skip=aoi.min_gsd,aoi.aoi&include=aoi.child_aoi.avg_gsd&token={token}

Sample Pretty JSON Response (truncated):

{
    type: "FeatureCollection",
    features: [
        {
            type: "Feature",
            properties: {
                  Coverage Type: "dsm",
                  Max GSD: 0.079931065,
                  Min Capture date: "2021-01-17 04:11:38",
                  Max Capture date: "2021-01-31 07:35:34",
                  layer: "bluesky-ultra",
                  AOI Area: 2209.8618,
                  AOI Max Zoom: 21,
                  AOI Pretty Name: ""

Coverage Geometry Visualized in QGIS:

________________________________________________________________________________________

Roma, Italy - Demonstrating wkt and format:
https://api.gic.org/metadata/DSMCoverage?wkt=POINT(12.4920256 41.8897457)&format=wkt&token={token}

Sample JSON response (truncated):

{"type":"FeatureCollection","features":[{"type":"Feature","properties":{"AOI":"it-62-rome-2022","Coverage Type":"dsm","Min GSD":0.032385413,"Max GSD":0.07353346,"Min Capture date":"2022-03-21 09:08:41","Max Capture date":"2022-06-06 11:12:37","layer":"bluesky-ultra-europe","AOI Area":1804.0221,"AOI Max Zoom":21,"AOI Pretty Name":""},"geometry":"MULTIPOLYGON (((12.160364616166968 41.878107262767756, 12.161974207192912 41.8781455525093, 12.165352080320007 41.879275259677755, 12.16774907381479 41.8831808114066, 12.167691671197385 41.8864919093573, 12.170813986502125 41.88660639392092, 12.174077722362817 41.89004054472892,
.
.
.

Coverage Geometry Visualized in QGIS:

External Resources

wkt generator and visualizer:
https://arthur-e.github.io/Wicket/sandbox-gmaps3.html

Vexcel API Documentation

DSMCoverage Service - v1.4