Basemaps WMTS
Overview
The Basemaps Web Map Tile Service (WMTS) returns Vivid Mosaic basemap 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.
The Basemap Web Map Service (WMTS) returns a Vivid Mosaic basemap tile for the requested product type. The following Vivid Mosaic basemap products are available to stream.
| Vivid Mosaic product | productName |
|---|---|
| Vivid Mosaic 15 cm | VIVID_ADVANCED_15 |
| Vivid Mosaic 30 cm | VIVID_STANDARD_30 |
This example shows a CQL query for Vivid Mosaic 30 cm basemap imagery.
cql_filter=productName='Vivid_Standard_30'
See CQL Filters for instructions.
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/basemaps/v1/seamlines/gwc/service/wmts?SERVICE=WMTS&REQUEST=GetCapabilities&VERSION=1.0.0 |
| GetTile | Returns a seamless image tile | https://api.maxar.com/basemaps/v1/ogc/gwc/service/wmts?service=WMTS&request=GetTile&layer=Maxar:Imagery&tileMatrixSet=EPSG:3857&tileMatrix=EPSG:3857:19&tileCol=83913&tileRow=202939&format=image/jpeg&cql_filter=productName='VIVID_ADVANCED_15' |
WMTS Get Capabilities
Returns a list of services and operations supported by WMTS.
Request URL
https://api.maxar.com/basemaps/v1/seamlines/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 | required | The version number of the service | Use 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 Mosaic basemap layers. To restrict WMTS results to Vivid Mosaic basemaps, use the cql filter clause productName LIKE 'VIVID%'. To restrict to a specific Vivid Mosaic product type, use a cql clause to call that product type. For example, productName='VIVID_ADVANCED_15'.
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/basemaps/v1/ogc/gwc/service/wmts?service=WMTS&request=GetTile&layer=Maxar:Imagery&tileMatrixSet=EPSG:3857&tileMatrix=EPSG:3857:19&tileCol=83913&tileRow=202939&format=image/jpeg&cql_filter=productName='VIVID_ADVANCED_15'
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 | required | The version number of the service. | 1.0.0 |
| layer | required | The name of the imagery layer to query. | Use Maxar:seamline |
| tileMatrixSet | required | A pre-defined set of tiles for the spatial reference system.Supported tile matrix sets | EPSG:4326 |
| tileMatrix | required | The tile matrix set and and zoom level, from 0 (lowest) to 21 (highest). | EPSG:4326:14 |
| tileCol | required | The column index of a tile matrix. | 1709 |
| tileRow | required | The row index of a tile matrix. | 3100 |
| format | required | The output file format of the response. See Supported Output Formats. | image/jpeg |
| styles | optional | Renders the layers in the selected style. | raster |
| cql_filter | optional | Filter by feature metadata attributes. For Vivid Mosaic basemaps, include a cql filter for the Basemap product name.cql_filter=productName='VIVID_STANDARD_30' | |
| 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 an image. The mask is automatically applied up to zoom level 10.
These examples shows applying a shoreline to Vivid Mosaic 30 imagery. 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='VIVID_STANDARD_30' OR productName='BASE_MOSAIC'&shoreline_masking=true
Supported tile matrix sets
Supported tile matrix sets
EPSG:4326
EPSG:900913
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.
CQL Filters
OGC Streaming services support searching for features using Common Query Language (CQL) filters.
The query format is:
cql_filter=keyname='value'
CQL operators
| Operator | Definition | Example |
|---|---|---|
= | Equals | productName='VIVID_ADVANCED_15' |
> | Greater Than | sunElevation>15 |
< | Less Than | cloudCover<.20 |
>= | Greater than or equal to | sunElevation>=15 |
<= | Less than or equal to | cloudCover<=.20 |
<> | Not equal to | productName<>'VIVID_BASIC' |
% | Wildcard | productName LIKE 'VIVID%' |
CQL search keywords
Use CQL keywords to create a complex query that joins two clauses together. Streaming services support the following keywords:
| Keyword | Description | Example |
|---|---|---|
| AND | The search results will match all clauses in the query. | (acquisitionDate >2023-12-07) AND BBOX(featureGeometry,39.906477,-105.010843,39.918031,-104.99193) |
| OR | The search results will match at least one of the clauses in the query. | (productName='VIVID_STANDARD_30') OR (productName='VIVID_ADVANCED_15') |
| BETWEEN | The search results will fall between the values provided. | groundSampleDistance BETWEEN .15 AND .39 |
| NOT | The search results will not contain the value listed in the clause or clauses. | NOT (productName='VIVID_STANDARD_30') |
| LIKE | Use with a % wildcard character in the value to filter for results that match part of a value. | productName LIKE 'VIVID%' |