# Basemaps WFS ## Overview[​](#overview "Direct link to Overview") The Streaming - Basemaps WFS service requests data from the Streaming Imagery Geoserver and returns metadata for basemaps imagery that matches the request criteria. Basemap imagery is served from the Streaming Imagery Geoserver and is described in the "FinishedFeature" type. To request Vivid Mosaic basemap products, you will add a CQL filter for product name. The following Vivid Mosaic basemap products are available to stream. | Vivid Mosaic basemap product | productName | | ---------------------------- | ------------------- | | Vivid Mosaic 15 cm | `VIVID_ADVANCED_15` | | Vivid Mosaic 30 cm | `VIVID_STANDARD_30` | This example shows a CQL query for Vivid Mosaic 30 cm basemap imagery. ```text cql_filter=productName='Vivid_Standard_30' ``` See [Using CQL Filters](#using-cql-filters) for instructions. ## 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 ` 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=` The custom header takes the form of: `maxar-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") The Basemaps WFS service supports the following request types: | Name | Description | Request URL | | --------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ | | [Get Capabilities](#wfs-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](#wfs-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](#wfs-get-feature) | 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[​](#wfs-get-capabilities "Direct link to WFS Get Capabilities") Returns a list of services, operations, and allowed values for WFS. ### Request URL[​](#request-url "Direct link to Request URL") ```text https://api.maxar.com/basemaps/v1/ogc/wfs?service=WFS&request=GetCapabilities&version=2.0.0 ``` ### Request parameters[​](#request-parameters "Direct link to 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 "Direct link to 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[​](#wfs-describe-feature-type "Direct link to 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[​](#request-url-1 "Direct link to Request URL") ```text https://api.maxar.com/basemaps/v1/ogc/ows?service=WFS&request=DescribeFeatureType&version=2.0.0 ``` ### Request parameters[​](#request-parameters-1 "Direct link to 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 Mosaic 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 Mosaic 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 Streaming service requests. ### Response[​](#response-1 "Direct link to 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[​](#wfs-get-feature "Direct link to WFS Get Feature") Returns Vivid Mosaic 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 Mosaic basemap layers. To restrict WFS results to Vivid Mosaic basemaps, use the cql filter clause `productName LIKE 'VIVID%'`. To restrict to a specific Vivid Mosaic product type, use a cql clause to call that product type. For example, `productName='VIVID_ADVANCED_15'` ### Request URL[​](#request-url-2 "Direct link to Request URL") This example uses a CQL filter to query for Vivid Mosaic 30 cm basemap imagery. ```text 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[​](#request-parameters-2 "Direct link to 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 Mosaic basemaps. | `Maxar:FinishedFeature` | | | outputFormat | optional | Response output format. Default is text/xml; subtype=gml/3.1.1. | See [Supported Output Formats](#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](#using-cql-filters). | #### Axis Order[​](#axis-order "Direct link to 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](https://docs.geoserver.org/main/en/user/services/wfs/axis_order.html) 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[​](#supported-output-formats "Direct link to 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 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[​](#using-cql-filters "Direct link to Using CQL Filters") OGC Streaming services support searching for features using Common Query Language (CQL) filters. The query format is: ```text cql_filter=keyname='value' ``` ### CQL operators[​](#cql-operators "Direct link to 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[​](#cql-search-keywords "Direct link to CQL search keywords") Use CQL keywords to create a complex query that joins two clauses together. 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[​](#query-for-a-bounding-box "Direct link to 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: ```text 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: ```text 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: ```text BBOX(featureGeometry,39.7530,-104.9962,39.7580,-104.9912)AND(product_name='VIVID_STANDARD_30') ```