Quickstart: Streaming Vivid Mosaic Basemaps
In this tutorial, you will learn how to place a Basemap WMS streaming request for Vivid Mosaic 30 cm basemap imagery over an AOI:
Topic summary:
Get an API Key
-
Sign in to MGP Pro
-
Click the "down" arrow next to the gold circle in the top right hand corner to expand the profile menu and select "API Key" from the list.
- From the API key menu, select the "copy" button to copy your API key.
API keys have a duration of 180 days.
To retrieve an API key programmatically, see API Keys
Make a basemaps WMS request
To request Vivid Mosaic imagery from the Streaming - Basemaps API, you will make a call to the /basemaps/v1/ogc endpoint. This request can return both Vivid Mosaic basemaps and image strips. To restrict your search to Vivid Mosaic Basemaps, you need to include a cql filter for product name as part of your request.
This is an example of a Basemaps WMS URL request for Vivid Mosaic 30 cm basemaps.
https://api.maxar.com/basemaps/v1/ogc/wms?service=WMS&version=1.3.0&request=GetMap&bbox=36.985003,-109.028320,40.996484,-102.041016&crs=EPSG:4326&format=image/png&transparent=true&layers=Maxar:Imagery&tiled=true&width=512&height=512&cql_Filter=productName='VIVID_STANDARD_30'&Maxar_API_Key
This section explains how to construct the URL shown above.
1. Set the base URL
The base URL for retrieving imagery from the Basemaps API is:
https://api.maxar.com/basemaps/v1/ogc/wms
2. Add query parameters
Once your base URL is set up, you'll add required and optional query parameters.
WMS 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 |
| 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. For Vivid Mosaic basemaps, include a cql filter for the Basemap product name.cql_filter=productName='Vivid_Standard_30' | |
| maxar_api_key | optional | Include your API key as a query parameter or as a request header. | a valid API key |
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.
3. Use CQL queries to filter results
CQL is a query language that is supported by the OGC WMS service. You can add CQL filters to a WMS request to filter by metadata associated with basemaps imagery. A CQL filter can be made up of a single clause or multiple clauses.
Use a cql filter to query for Vivid Mosaic 30 cm basemaps. . To specify the Vivid Mosaic 30 cm product, your cql filter will look like this:
cql_filter=productName='Vivid_Standard_30'
You may want to use cql filters to further refine your query. You can combine multiple query clauses. Be sure to always include the product name clause.
For example:
cql_filter=(productName='Vivid_Standard_30') AND (acquisitionDate >2023-12-07)
4. Append your API key
Append your API key to the URL to authenticate your request.
maxar_api_key=<your API key>
Alternatively, you can add your API key as a customer header.
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.
View Basemap imagery
If you are using an API client to build your WMS query, the result will be a map image in the requested output format. The query described in this tutorial returns a Vivid Mosaic 30 cm basemap image in .png format.
