Streaming Imagery - WMTS
Overview
The Web Map Tile Service (WMTS) returns image tiles divided on a pre-defined grid matrix. These tile matrix sets are available in Geographic (EPSG:4326) and Web Mercator (EPSG:3857 and EPSG:900913) systems in standard and 2X (Retina) resolutions. See the list of supported tile matrix sets.
Each tile within the set is identified by a numeric row and column value. The zoom level the tile column and tile row apply to must also be specified. Zoom levels 0 (lowest) to 21 (highest, fully zoomed in) are supported.
Other than returning tiles, the WMTS service functions similarly to the WMS service to render the Maxar:Imagery layer and the displayed contents can be modified with the same CQL Filter syntax.
Authentication
All OGC services accept an API key or a bearer token for authentication.
Bearer tokens
Oauth bearer tokens can also be used to authenticate API requests. Bearer tokens have a brief duration and must be refreshed frequently.
To authenticate with a bearer token, use the Authorization header:
Authorization: Bearer <Oauth2 token>
Learn about OAuth2 bearer tokens
API keys
API keys can be passed using query parameters or in a custom header. No Authorization header is needed when using API keys.
To use the query parameter method, include this query parameter in your request:
maxar_api_key=<your API key>
The custom header takes the form of:
maxar-api-key: <your API key>
API keys expire 180 days from creation by default. A custom expiration date can be set but cannot exceed 180 days.
Learn about API keys
Services
| Name | Description | Request URL |
|---|---|---|
| Get Capabilities | Describes the Get Tile service and layers. | https://api.maxar.com/streaming/v1/ogc/wmts?service=WMTS&request=GetCapabilities |
| GetTile | Returns a map tile | https://api.maxar.com/streaming/v1/ogc/wmts?service=WMTS&request=GetTile |
WMTS Get Capabilities
Returns a list of services and operations supported by WMTS.
Request URL
https://api.maxar.com/streaming/v1/ogc/gwc/service/wmts?service=WMTS&request=GetCapabilities&version=1.0.0
Query parameters
| Name | Required/Optional | Description | Value |
|---|---|---|---|
service | required | The requested OGC service. | WMTS |
request | required | The name of the request type | GetCapabilities |
version | optional | WMTS version number, defaults to 1.0.0 | 1.0.0 |
Response
Successful status code: 200 OK
Response output format: XML
Exceptions may also return a 200 OK, with an error in the response body.
The response body is returned in XML format and describes the supported services and imagery layers.
WMTS Get Tile
Returns a map tile based on the input query parameters.
The imagery layer Maxar:Imagery includes all imagery, including the Daily Take imagery layer and the Vivid basemap layers. To restrict WMTS results to Daily Take imagery, use the cql filter clause productName=DAILY_TAKE'.
WMTS GetTile request parameters are explained in this section. You can also make a WMTS Get Capabilities request to see the details of the WMTS service.
Request URL
Example:
https://api.maxar.com/streaming/v1/ogc/gwc/service/wmts?service=WMTS&request=GetTile&version=1.0.0&layer=Maxar:Imagery&styles=raster&tileMatrixSet=EPSG:3857&tileMatrix=EPSG:3857:13&tileCol=1709&tileRow=3100&format=image/jpeg
Query parameters
| Name | Required/Optional | Description | Value |
|---|---|---|---|
| service | required | The name of the OGC service. | WMTS |
| request | required | The name of the WMTS request type. | GetTile |
| version | optional | WMTS version number, defaults to 1.0.0 | 1.0.0 |
| layer | required | The name of the imagery layer to query. | Use Maxar:Imagery |
| tileMatrixSet | required | A pre-defined set of tiles for the spatial reference system.Supported tile matrix sets | Example: EPSG:3857 |
| tileMatrix | required | The tile matrix set and and zoom level, from 0 (lowest) to 21 (highest). | Example:EPSG:3857:13 |
| tileCol | required | The column index of a tile matrix. | Example:1709 |
| tileRow | required | The row index of a tile matrix. | Example:3100 |
| format | optional | The output file format of the response. See Supported Output Formats. | Example:image/jpeg |
| styles | optional | Renders the layers in the selected style.For the Maxar:Imagery layer, the style is "raster". | raster |
| cql_filter | optional | Filter by feature metadata attributes. | See CQL filters |
| shoreline_masking | optional | Applies a shoreline mask when set to true. | shoreline_masking=true |
Shoreline masking
The shoreline_masking parameter applies a shoreline mask to the returned image.
This example applies a shoreline mask to a Daily Take image. To fill out the pixels of the masked area, include the cql filter clause productName='BASE_MOSAIC.
https://api.maxar.com/streaming/v1/ogc/wmts?service=WMTS&request=GetTile&layer=Maxar:Imagery&tileMatrixSet=EPSG:3857&tileMatrix=EPSG:3857:11&tileCol=326&tileRow=791&format=image/jpeg&cql_filter=productName='DAILY_TAKE' OR productName='BASE_MOSAIC'&shoreline_masking=true
CQL Filters
CQL filters can be applied to WMTS requests to filter results. This example uses a cql filter to request a specific feature ID:
https://api.maxar.com/streaming/v1/ogc/gwc/service/wmts?service=WMTS&request=GetTile&version=1.0.0&layer=Maxar:Imagery&format=image/png&tileMatrixSet=EPSG:3857&tileMatrix=EPSG:3857:13&tileCol=2108&tileRow=2952&cql_filter=featureId='089ffaa3-8d86-ac82-96df-31413f61b8dc'
For more information about CQL filters, see the Using CQL Filters in the WMS documentation.
Supported tile matrix sets
Supported tile matrix sets
EPSG:3857
EPSG:3857x2
EPSG:4326
EPSG:4326x2
EPSG:900913
EPSG:900913x2
Supported output formats
By default, a map tile is returned in PNG format. The JPEG format will return the fastest service response. PNG is required for tiles with transparent backgrounds.
Supported output formats
image/png
image/jpeg
Response
Successful response code: 200 OK
The response is an image of the requested map tile.