# Streaming Imagery - WMTS

## Overview[​](#overview "Direct link to 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](#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[​](#authentication "Direct link to Authentication")

All OGC services accept an API key or a bearer token for authentication.

#### Bearer tokens[​](#bearer-tokens "Direct link to 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](/docs/authentication/guides/get-a-token.md)

#### API keys[​](#api-keys "Direct link to 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](/docs/authentication/guides/api-key.md)

## Services[​](#services "Direct link to Services")

| Name                                       | Description                                | Request URL                                                                                    |
| ------------------------------------------ | ------------------------------------------ | ---------------------------------------------------------------------------------------------- |
| [Get Capabilities](#wmts-get-capabilities) | Describes the Get Tile service and layers. | `https://api.maxar.com/streaming/v1/ogc/gwc/service/wmts?service=WMTS&request=GetCapabilities` |
| [GetTile](#wmts-get-tile)                  | Returns a map tile                         | `https://api.maxar.com/streaming/v1/ogc/gwc/service/wmts?service=WMTS&request=GetTile`         |

## WMTS Get Capabilities[​](#wmts-get-capabilities "Direct link to WMTS Get Capabilities")

Returns a list of services and operations supported by WMTS.

### Request URL[​](#request-url "Direct link to Request URL")

```text
https://api.maxar.com/streaming/v1/ogc/gwc/service/wmts?service=WMTS&request=GetCapabilities&version=1.0.0

```

### Query parameters[​](#query-parameters "Direct link to 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[​](#response "Direct link to 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[​](#wmts-get-tile "Direct link to 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 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](#wmts-get-capabilities) request to see the details of the WMTS service.

### Request URL[​](#request-url-1 "Direct link to Request URL")

Example:

```text
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[​](#query-parameters-1 "Direct link to 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](#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](#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](#cql-filters) |
| shoreline\_masking | optional          | Applies a shoreline mask when set to true.                                                                            | `shoreline_masking=true`        |

#### Shoreline masking[​](#shoreline-masking "Direct link to 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`.

```text
https://api.maxar.com/streaming/v1/ogc/gwc/service/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 "Direct link to 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:

```text
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](/docs/streaming-imagery/guides/wms.md#using-cql-filters) in the WMS documentation.

### Supported tile matrix sets[​](#supported-tile-matrix-sets "Direct link to Supported tile matrix sets")

Supported tile matrix sets

<!-- -->

```text
 EPSG:3857
 EPSG:3857x2
 EPSG:4326
 EPSG:4326x2
 EPSG:900913
 EPSG:900913x2

```

### Supported output formats[​](#supported-output-formats "Direct link to 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

<!-- -->

```text
image/png
image/jpeg

```

### Response[​](#response-1 "Direct link to Response")

Successful response code: `200 OK`

The response is an image of the requested map tile.