Quickstart: Streaming Vivid Basemaps
In this tutorial, you will learn how to place a Basemap WMS streaming request for Vivid Standard 30 cm basemap imagery over an AOI:
Topic summary:
Prerequisite: 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 Basemaps imagery from the Streaming -Basemaps API, you will make a call to the /basemaps/v1/ogc endpoint. This request can return both Vivid basemaps and image strips. To restrict your search to Vivid 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 Standard 30 cm HD 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 Basemaps, include a cql filter for the Basemap product name.cql_filter=productName='Vivid_Standard_30' | |
| maxar_api_key | optional | Include your Maxar 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 Standard 30 cm basemaps. . To specify the Vivid Standard 30 cm HD 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 Standard 30 cm basemap image in .png format.
