Basemaps WFS
Overview
The Streaming - Basemaps WFS service requests data from the Maxar Imagery geoserver and returns metadata for basemaps imagery that matches the request criteria.
Basemap imagery is served from the Maxar Imagery geoserver and is described in the "FinishedFeature" type. To request Vivid Basemap products, you will add a CQL filter for product name. The following Vivid Basemap products are available to stream.
| Vivid basemap product | productName |
|---|---|
| Vivid Advanced 15 cm | VIVID_ADVANCED_15 |
| Vivid Standard 30 cm | VIVID_STANDARD_30 |
This example shows a CQL query for Vivid Standard 30 cm basemap imagery.
cql_filter=productName='Vivid_Standard_30'
See Using CQL Filters for instructions.
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
The Basemaps WFS service supports the following request types:
| Name | Description | Request URL |
|---|---|---|
| Get Capabilities | Describes the capabilities and allowed values for WFS. | https://api.maxar.com/basemaps/v1/ogc/wfs?service=WFS&request=GetCapabilities&version=2.0.0 |
| Describe Feature Type | Returns information about available feature types. For basemap imagery, use the feature type "FinishedFeature." | https://api.maxar.com/basemaps/v1/ogc/ows?service=WFS&request=DescribeFeatureType&version=2.0.0 |
| GetFeature | Returns metadata for basemap imagery that matches the search criteria. | https://api.maxar.com/basemaps/v1/ogc/wfs?service=WFS&request=GetFeature&version=2.0.0&typeNames=Maxar:FinishedFeature |
WFS Get Capabilities
Returns a list of services, operations, and allowed values for WFS.
Request URL
https://api.maxar.com/basemaps/v1/ogc/wfs?service=WFS&request=GetCapabilities&version=2.0.0
Request parameters
| Name | Required/Optional | Description | Value |
|---|---|---|---|
| service | required | The requested OGC service | wfs |
| request | required | The name of the WFS request type | GetCapabilities |
| version | required | The version number of the service. We recommend using 2.0.0 which is the latest version. | Accepts 1.0.0, 1.1.0, 2.0.0 |
Response
Response output format: XML
Successful status code: 200 OK
Exceptions may also return a 200 OK, with an error in the response body.
Make a Get Capabilities request to see the full response.
WFS Describe Feature Type
Returns a description of feature types supported by the WFS service for imagery. For basemap imagery, use the feature type "FinishedFeature."
Request URL
https://api.maxar.com/basemaps/v1/ogc/ows?service=WFS&request=DescribeFeatureType&version=2.0.0
Request parameters
| Name | Required/Optional | Description | Value |
|---|---|---|---|
| service | required | The requested OGC service. | wfs |
| request | required | The name of the WFS request type | DescribeFeatureType |
| version | required | The version number of the service. We recommend using 2.0.0 which is the latest version. | Accepts 1.0.0, 1.1.0, 2.0.0 |
The "FinishedFeature" type description includes metadata for image strips and Vivid basemap imagery. When you make a WFS "Get Feature" request, it will return the metadata fields that apply to the feature. The metadata returned for an image strip is a different subset than the metadata returned for a Vivid basemap.
The "Describe Feature Type" response describes three feature types: FinishedFeature, RasterFeature, and VectorFeature. You should use FinishedFeature for basemap imagery. Raster Feature is nearly identical to FinishedFeature and can also be used. VectorFeature has been deprecated and will be removed from the streaming services in the future. It should not be used for any MGP Streaming service requests.
Response
Response output format: XML
Successful status code: 200 OK
Exceptions may also return a 200 OK, with an error in the response body.
WFS Get Feature
Returns Vivid basemaps imagery that matches the query criteria. The results can be further refined by applying CQL filters to search by metadata.
The bbox and cql_filter parameters cannot be used together in a WFS Get Feature request. If you're using cql filters, you can add the bbox as a cql clause instead of in the bbox field. This is shown in the cql filter example in this request.
The feature type Maxar:FinishedFeature includes all imagery layers, including the Daily Take imagery layer and the Vivid basemap layers. To restrict WFS results to Vivid basemaps, use the cql filter clause productName LIKE 'VIVID%'. To restrict to a specific Vivid product type, use a cql clause to call that product type. For example, productName='VIVID_ADVANCED_15'
Request URL
This example uses a CQL filter to query for Vivid Standard 30 cm basemap imagery.
https://api.maxar.com/basemaps/v1/ogc/wfs?service=WFS&request=GetFeature&version=2.0.0&typeNames=Maxar:FinishedFeature&cql_Filter=BBOX(featureGeometry,39.7530,-104.9962,39.7580,-104.9912)AND(productName='VIVID_STANDARD_30')
Request parameters
| Name | Required/Optional | Description | Value |
|---|---|---|---|
| service | required | The requested OGC service. | wfs |
| request | required | The service request type. | GetFeature |
| version | required | The OGC version to use for the request. | 2.0.0 |
| bbox | required | The geographic extents of the features to return. | Example: 39.7530,-104.9962,39.7580,-104.9912 |
| srsName | optional | This parameter is used to specify the spatial reference system to encode feature geometries in. | Accepts EPSG:4326. |
| typeNames | Use the type name "FinishedFeature" for Vivid basemaps. | Maxar:FinishedFeature | |
| outputFormat | optional | Response output format. Default is text/xml; subtype=gml/3.1.1. | See Supported Output Formats. |
| count | optional | The number of features to return in the response. The default is to show all features that match the request, with a maximum of 1000. | 1 - 1000. |
| sortBy | optional | Specify the attribute to sort by and whether to sort in ascending (A) or descending (D) order. | Example: sortBy=acquisitionDate A |
| cql_filter | optional | Filter by additional metadata attributes. Cannot be used with the "BBox" parameter; however, bbox can be queried as a cql filter. | See Using CQL filters. |
Axis Order
The source data are in EPSG:4326 which uses (y,x) coordinate order. This means the bbox parameter needs to also follow, i.e. latitude before longitude.
The WFS specification also allows you to include a coordinate reference system with the bounding box when the coordinate systems differ. This syntax looks like bbox=-11683553, 4832655,-11683247, 4832960, EPSG:3857.
However, if you include EPSG:4326 with your bounding box, you will actually be using a compatibility override in Geoserver that assumes you are providing a bbox in (x,y) coordinate order. To use EPSG:4326 as defined with (y,x) coordinate order you must use the strict definition urn:ogc:def:crs:EPSG::4326. Furthermore, this exception only applies to the bbox parameter in WFS and not WMS. It also does not apply to the srsName parameter
To avoid this confusion, you can omit specifying EPSG:4326 since this is the coordinate system already in use. As shown in the table above, passing the parameter as bbox= 39.7530,-104.9962,39.7580,-104.9912 is sufficient.
Supported output formats
The response to a WFS Get Feature query can be returned in a variety of formats. The default format is text/xml; subtype=gml/3.1.1.
Supported output formats
text/xml; subtype=gml/3.1.1
GML2
KML
SHAPE-ZIP
application/vnd.google-earth.kml xml
application/vnd.google-earth.kml+xml
csv
gml3
gml32
json
text/csv
text/xml; subtype=gml/2.1.2
text/xml; subtype=gml/3.2
The list of supported output formats for a WFS Get Feature request can also be found in the WFS Get Capabilities response.
Using 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. MGP 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%' |
Query for a bounding box
The WFS specification does not allow BBOX and cql_filter parameters in the same request. In WFS, BBOX is a shorthand parameter for a spatial filter. With a CQL filter you can add the bounding box filter to the CQL filter string.
This does not apply to the WMS parameter BBOX which is not a filter. Using BBOX filter in the CQL query will filter which images or features are drawn within the map area described by the WMS BBOX parameter.
CQL filter BBOX syntax is similar in structure to the BBOX parameter but adds a first value for the name of the column that stores the feature geometry. Use the name featureGeometry.
Example:
BBOX(featureGeometry,39.7530,-104.9962,39.7580,-104.9912)
To set a projection other than EPSG:4326, you can append the project to the end of the bbox geometry, surrounded by single quotes.
Example:
BBOX(featureGeometry,-11712956.404248431,4851060.1776836105,-11693388.525007427,4870628.056924616,'EPSG:3857')
To add BBOX to a CQL filter you would AND the bbox to the other clauses.
Example:
BBOX(featureGeometry,39.7530,-104.9962,39.7580,-104.9912)AND(product_name='VIVID_STANDARD_30')