Streaming Imagery - WMS
Overview
The Web Map Service (WMS) generates an image from features in the requested imagery layer, based on request parameters. You can use CQL filters to further refine the features used in the map.
Authentication
All OGC services accept an API key or a bearer token for authentication.
Bearer tokens
Maxar 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 Maxar 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 capabilities available for WMS. | https://api.maxar.com/streaming/v1/ogc/wms?service=WMS&request=GetCapabilities |
| GetMap | Generates a map based on the input query parameters. | https://api.maxar.com/streaming/v1/ogc/wms?service=WMS&request=GetMap |
WMS Get Capabilities
Returns a list of services and operations supported by WMS.
Request URL
https://api.maxar.com/streaming/v1/ogc/wms?service=WMS&request=GetCapabilities
Query parameters
| Name | Required/Optional | Description | Value |
|---|---|---|---|
| service | required | The name of the requested OGC service. | WMS |
| request | required | The name of the request type | GetCapabilities |
| version | optional | WMS version number, defaults to 1.3.0 | Accepts 1.3.0 and 1.1.1 |
We recommend using the latest WMS version - 1.3.0 - unless you have a specific reason to use 1.1.1. See Differences between WMS versions in the Geoserver spec for more information.
Response
Response output format: XML
Successful status code: 200 OK
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 WMS services and imagery layers.
WMS Get Map
Generates a map 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 WMS results to Daily Take imagery, use the cql filter clause productName='DAILY_TAKE'.
Request URL
URL path with required parameters:
Examples:
WMS example with EPSG:4326
https://api.maxar.com/streaming/v1/ogc/wms?service=WMS&request=GetMap&version=1.3.0&bbox=39.719534,-105.009465,39.746465,-104.957624&crs=EPSG:4326&layers=Maxar:Imagery&height=512&width=512&format=image/png&cql_Filter=productName='DAILY_TAKE'
WMS example with EPSG:3857
https://api.maxar.com/streaming/v1/ogc/wms?service=WMS&request=GetMap&version=1.3.0&bbox=-11683553, 4832655,-11683247, 4832960&crs=EPSG:3857&layers=Maxar:Imagery&height=512&width=512&format=image/vnd.jpeg-png&cql_Filter=(acquisitionDate>='2019-01-01')AND(cloudCover<.20)
Query parameters
| Name | Required/Optional | Description | Allowed Values |
|---|---|---|---|
| service | required | The OGC service name. | WMS |
| request | required | The name of the WMS request type. | GetMap |
| version | optional | WMS version number. 1.3.0 is the latest version and is set by default. This is the recommended version. | Accepts 1.3.0 and 1.1.1 |
| bbox | required | Your area of interest in bounding box format. The order of the bbox coordinates depends on the selected CRS projection. | See Bounding Box Coordinate Order |
| layers | required | The name of the imagery layer to query. | Use Maxar:Imagery |
| crs | required | The requested output projection. | EPSG:4326 EPSG:3857 EPSG:3395 AUTO:42004 CRS:84 |
| height | required | The height of the vertical tile column | Example: 512 |
| width | required | The width of the horizontal tile row | Example: 512 |
| format | optional | The output file format of the response. | See Supported Output Formats |
| transparent | optional | Removes blank background space from returned images. | true |
| styles | optional | Renders the layers in the selected style. | For the Maxar:Imagery layer, the style is raster. |
| cql_filter | optional | Filter by feature metadata attributes. | See Using 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/basemaps/v1/ogc/wms?service=wms&request=GetMap&version=1.3.0&bbox=-13640313.39894550852,4546650.010356360115,-13636538.06416588835,4550119.459330277517&crs=EPSG:3857&layers=Maxar:Imagery&height=1719&width=1580&format=image/vnd.jpeg-png&shoreline_masking=true&cql_filter=productName='DAILY_TAKE' OR productName='BASE_MOSAIC'
Use the latest WMS version - 1.3.0 - unless you have a specific reason to use 1.1.1. See Differences between WMS versions in the Geoserver spec for more information.
Bounding Box Coordinate Order
The required order of the bounding box coordinates depends on the specified CRS projection. This table shows the coordinate order for the supported projections. Click the Projection Name to view supporting documentation.
To read the coordinate order, the coordinates of a bounding box are encoded with four values in pixels: [x_min, y_min, x_max, y_max]. x_min and y_min are coordinates of the top-left corner of the bounding box.
| Projection | BBox coordinate order | Example |
|---|---|---|
| EPSG:4326 | [ymin, xmin, ymax, xmax] | 39.719534,-105.009465,39.746465,-104.957624 |
| EPSG:3857 | [xmin, ymin, xmax, ymax] | -11683553, 4832655,-11683247, 48329601 |
Note: If you are using WMS version 1.1.1, the coordinate order for EPSG:4326 must be [xmin, ymin, xmax, ymax]. See WMS Basics: Axis ordering for a full explanation.
Supported output formats
The response to a WMS Get Map query can be returned in a variety of formats. In most cases, requesting the format image/vnd.jpeg-png will give the best results, automatically picking JPEG or PNG depending on whether transparency is needed.
image/png
application/atom+xml
application/json;type=utfgrid
application/rss+xml
application/vnd.google-earth.kml+xml
application/vnd.google-earth.kml+xml;mode=networklink
application/vnd.google-earth.kmz
image/geotiff
image/geotiff8
image/gif
image/jpeg
image/png; mode=8bit
image/svg+xml
image/tiff
image/tiff8
image/vnd.jpeg-png
image/vnd.jpeg-png8
text/html; subtype=openlayers
text/html; subtype=openlayers2
text/html; subtype=openlayers3
Response
Successful response code: 200 OK
The response is a map visualization.
Using CQL Filters
The images displayed in a Get Map request can be filtered by feature attributes by including a CQL query clause. To see the queryable feature attributes, make a WFS Get Feature Info request, or view the attributes in the WFS Guide.
Try the CQL Playground to see how different queries and sort orders change the returned images.
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 | source='WV02' |
> | 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 | dataLayer<>'daily_take' |
% | Wildcard | source LIKE 'LG%' |
CQL search keywords
Use CQL keywords to create a complex query that joins two clauses together. MGP Streaming services support the following keywords:
| Keyword | Description | Example |
|---|---|---|
| AND | The search results will match all clauses in the query. | (acquisitionDate>='2019-01-01')AND(cloudCover<.20) |
| OR | The search results will match at least one of the clauses in the query. | (source='WV02') OR (source='WV03_VNIR') |
| BETWEEN | The search results will fall between the dates provide. | groundSampleDistance BETWEEN .30 AND .50 |
| NOT | The search results will not contain the value listed in the clause or clauses. | NOT (source='WV02') |
| LIKE | Use with a % wildcard character in the value to filter for results that match part of a value. | source LIKE 'LG%' |
Query by date range
To filter for items within a date range, use one of the following query formats:
cql_filter=(acquisitionDate>='2020-01-01')AND(acquisitionDate<='2020-03-31')
cql_filter=acquisitionDate between '2019-12-15' AND '2020-01-01'
Query for imagery that does not match the value
Use the NOT keyword to filter for items that do not match a specified value.
NOT (source='WV02')
NOT (source='WV02') AND NOT(source='WV03_VNIR')
Query for WorldView Legion data
To query for Legion data, use the "source" field.
cql_filter=source='LGO1'
To query for all Legion data, use the LIKE operator with a wildcard character.
cql_filter=source LIKE 'LG%'
This will return all WorldView Legion imagery that matches the filter criteria.
Imagery metadata
The same fields that are exposed via WFS apply to WMS CQL queries:
| Field | Description | Allowed Values |
|---|---|---|
acquisitionDate | The date and time the satellite acquired the image in Zulu time. | YYYY-MM-DDTHH:MM:SSSZ |
bandConfiguration | Null for panchromatic data; otherwise the order in which the spectral bands occur in the product described by the Feature. | RGB, RGBA, RGBU, GUUU, 631_245_788 |
bandDescription | Describes the band combination for the feature. In the MGP Pro UI this is referred to as ProductType. | MS1, Pan Sharpened Natural Color, Pan Sharpened Color Infrared, Panchromatic, SWIR 8-Band |
ce90Accuracy | CE90 standard for geolocation accuracy. CE90 is the circular error at the 90th percentile. This means that a minimum of 90 percent of the points measured has a horizontal error less than the stated CE90 value. | Example: 8.4 |
cloudCover | The percentage of the image that is covered by clouds. | 0-90 |
createdDate | The date and time the feature was created, in Zulu time. | YYYY-MM-DDTHH:MM:SSSZ |
crs | The EPSG code for the coordinate reference system. | Examples: EPSG:4326, EPSG:32638 |
dataLayer | The data layer the feature is part of. | daily_take, sw_sites_eo, crisis_event |
earliestAcquisitionTime | The earliest date and time of acquisition for an image associated with the feature, in Zulu time. | YYYY-MM-DDTHH:MM:SSSZ |
featureCentroid | The center of the feature geometry. | bounding box |
featureGeometry | The geometry for the feature in GeoJSON feature format. | Polygon |
featureId | The unique identifier assigned to the feature. | alphanumeric string |
groundSampleDistance | The spatial resolution of the sensor that acquired the image, stated in meters. | number |
groundSampleDistanceUnit | The unit used to measure ground sample distance. | Meter |
isEnvelopeGeometry | An envelope is a bounding box enclosing other geometry or set of geometries. | true/false |
latestAcquisitionTime | The latest date and time of acquisition for an image associated with the feature, in Zulu time. | YYYY-MM-DDTHH:MM:SSSZ |
legacyDescription | Legacy description retained for backwards compatibility. | string |
legacyIdentifier | The unique identifier for the image in the archive catalog. | alphanumeric string |
niirs | National Imagery Interpretability Rating Scale value | 0 (worst quality) to 9 (best quality). |
offNadirAngle | The angle from the sensor between nadir (straight down) and the scene center. Measured in degrees | 0-90 |
processingLevel | The processing level for the image. | For image features: standard, Ortho - 1:12,000 |
productName | The product name assigned to the feature. | DAILY_TAKE, SW_SITES_EO, CRISIS_EVENT |
resolutionX | The pixel size in the X direction. | Example: 4.5E-6 |
resolutionY | The pixel size in the Y direction. | Example: -4.5E-6 |
source | The satellite that acquired the image. If the feature is comprised of more than one image, the source value will be "multiple". | WV01 WV02 WV03 WV03_VNIR WV03_SWIR GE01 QB02 LG01 LG02 LGO3 LG04 |
sunAzimuth | From the scene center point on the ground, this is the angle between truth north and the sun. Measured clockwise in degrees. | 0-360 |
sunElevation | The angle from the tangent of the scene center point to the sun. Measured from the horizon in degrees. | 0-90 |
usageProductID | The usage ID assigned to the product. | number |
Some feature metadata fields will only have a null value. These fields are not included in the table.