NASA CMR STAC API
Extension to WFS3 Core to support STAC metadata model and search API
OpenAPI Specification
swagger: '2.0'
info:
title: CMR Search Capabilities STAC API
version: 1.0.0
description: CMR Search API
host: cmr.earthdata.nasa.gov
basePath: /search
schemes:
- https
consumes: []
produces: []
tags:
- name: STAC
description: Extension to WFS3 Core to support STAC metadata model and search API
paths:
/{providerId}/search:
get:
summary: Search STAC items with simple filtering.
description: 'Retrieve Items matching filters. Intended as a shorthand API for simple queries.
This method is optional, but you MUST implement `POST /stac/search` if you want to implement this method.'
operationId: getSearchSTAC
tags:
- STAC
parameters:
- $ref: '#/components/parameters/providerId'
- $ref: '#/components/parameters/bbox'
- $ref: '#/components/parameters/datetime'
- $ref: '#/components/parameters/limit'
- $ref: '#/components/parameters/page'
- $ref: '#/components/parameters/ids'
- $ref: '#/components/parameters/collections'
responses:
'200':
description: A feature collection.
content:
application/geo+json:
schema:
$ref: '#/components/schemas/itemCollection'
text/html:
schema:
type: string
default:
description: An error occurred.
content:
application/json:
schema:
$ref: '#/components/schemas/exception'
text/html:
schema:
type: string
post:
summary: Search STAC items with full-featured filtering.
description: 'retrieve items matching filters. Intended as the standard, full-featured query API.
This method is mandatory to implement if `GET /stac/search` is implemented. If this endpoint is implemented on a server, it is required to add a link with `rel` set to `search` to the `links` array in `GET /stac` that refers to this endpoint.'
operationId: postSearchSTAC
tags:
- STAC
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/searchBody'
responses:
'200':
description: A feature collection.
content:
application/geo+json:
schema:
$ref: '#/components/schemas/itemCollection'
text/html:
schema:
type: string
default:
description: An error occurred.
content:
application/json:
schema:
$ref: '#/components/schemas/exception'
text/html:
schema:
type: string
components:
schemas:
stac_extensions:
title: STAC extensions
type: array
uniqueItems: true
items:
anyOf:
- title: Reference to a JSON Schema
type: string
format: uri
- title: Reference to a core extension
type: string
exception:
type: object
description: 'Information about the exception: an error code plus an optional description.'
properties:
code:
type: string
description:
type: string
required:
- code
datetimeFilter:
description: An object representing a date+time based filter.
type: object
properties:
datetime:
$ref: '#/components/schemas/datetime'
item:
description: A GeoJSON Feature augmented with foreign members that contain values relevant to a STAC entity
type: object
required:
- stac_version
- id
- type
- geometry
- bbox
- links
- properties
- assets
properties:
stac_version:
$ref: '#/components/schemas/stac_version'
stac_extensions:
$ref: '#/components/schemas/stac_extensions'
id:
$ref: '#/components/schemas/itemId'
bbox:
$ref: '#/components/schemas/bbox'
geometry:
$schema: http://json-schema.org/draft-07/schema#
$id: https://geojson.org/schema/Geometry.json
title: GeoJSON Geometry
oneOf:
- title: GeoJSON Point
type: object
required:
- type
- coordinates
properties:
type:
type: string
enum:
- Point
coordinates:
type: array
minItems: 2
items:
type: number
bbox:
type: array
minItems: 4
items:
type: number
- title: GeoJSON LineString
type: object
required:
- type
- coordinates
properties:
type:
type: string
enum:
- LineString
coordinates:
type: array
minItems: 2
items:
type: array
minItems: 2
items:
type: number
bbox:
type: array
minItems: 4
items:
type: number
- title: GeoJSON Polygon
type: object
required:
- type
- coordinates
properties:
type:
type: string
enum:
- Polygon
coordinates:
type: array
items:
type: array
minItems: 4
items:
type: array
minItems: 2
items:
type: number
bbox:
type: array
minItems: 4
items:
type: number
- title: GeoJSON MultiPoint
type: object
required:
- type
- coordinates
properties:
type:
type: string
enum:
- MultiPoint
coordinates:
type: array
items:
type: array
minItems: 2
items:
type: number
bbox:
type: array
minItems: 4
items:
type: number
- title: GeoJSON MultiLineString
type: object
required:
- type
- coordinates
properties:
type:
type: string
enum:
- MultiLineString
coordinates:
type: array
items:
type: array
minItems: 2
items:
type: array
minItems: 2
items:
type: number
bbox:
type: array
minItems: 4
items:
type: number
- title: GeoJSON MultiPolygon
type: object
required:
- type
- coordinates
properties:
type:
type: string
enum:
- MultiPolygon
coordinates:
type: array
items:
type: array
items:
type: array
minItems: 4
items:
type: array
minItems: 2
items:
type: number
bbox:
type: array
minItems: 4
items:
type: number
type:
$ref: '#/components/schemas/itemType'
properties:
$ref: '#/components/schemas/itemProperties'
links:
type: array
items:
$ref: '#/components/schemas/link'
assets:
$ref: '#/components/schemas/itemAssets'
example:
stac_version: 1.0.0
type: Feature
id: CS3-20160503_132130_04
bbox:
- -122.59750209
- 37.48803556
- -122.2880486
- 37.613537207
geometry:
type: Polygon
coordinates:
- - - -122.308150179
- 37.488035566
- - -122.597502109
- 37.538869539
- - -122.576687533
- 37.613537207
- - -122.2880486
- 37.562818007
- - -122.308150179
- 37.488035566
properties:
datetime: '2016-05-03T13:21:30.040Z'
links:
- rel: self
href: http://cool-sat.com/catalog/collections/cs/items/CS3-20160503_132130_04.json
assets:
analytic:
title: 4-Band Analytic
href: http://cool-sat.com/catalog/collections/cs/items/CS3-20160503_132130_04/analytic.tif
thumbnail:
title: Thumbnail
href: http://cool-sat.com/catalog/collections/cs/items/CS3-20160503_132130_04/thumb.png
type: image/png
bboxFilter:
type: object
description: Only return items that intersect the provided bounding box.
properties:
bbox:
$ref: '#/components/schemas/bbox'
link:
type: object
properties:
href:
type: string
example: http://www.geoserver.example/stac/naip/child/catalog.json
format: url
rel:
type: string
example: child
type:
type: string
example: application/json
hreflang:
type: string
example: en
title:
type: string
example: NAIP Child Catalog
length:
type: integer
title: Link
description: A generic link.
required:
- href
- rel
bbox:
description: "Only features that have a geometry that intersects the bounding box are\nselected. The bounding box is provided as four or six numbers,\ndepending on whether the coordinate reference system includes a\nvertical axis (elevation or depth):\n\n* Lower left corner, coordinate axis 1\n* Lower left corner, coordinate axis 2 \n* Lower left corner, coordinate axis 3 (optional) \n* Upper right corner, coordinate axis 1 \n* Upper right corner, coordinate axis 2 \n* Upper right corner, coordinate axis 3 (optional)\n\nThe coordinate reference system of the values is WGS84\nlongitude/latitude (http://www.opengis.net/def/crs/OGC/1.3/CRS84) unless\na different coordinate reference system is specified in the parameter\n`bbox-crs`.\n\nFor WGS84 longitude/latitude the values are in most cases the sequence\nof minimum longitude, minimum latitude, maximum longitude and maximum\nlatitude. However, in cases where the box spans the antimeridian the\nfirst value (west-most box edge) is larger than the third value\n(east-most box edge).\n\n\nIf a feature has multiple spatial geometry properties, it is the\ndecision of the server whether only a single spatial geometry property\nis used to determine the extent or all relevant geometries.\n"
type: array
minItems: 4
maxItems: 6
items:
type: number
example:
- -110
- 39.5
- -105
- 40.5
intersectsFilter:
type: object
description: Only returns items that intersect with the provided polygon.
properties:
intersects:
$ref: '#/components/schemas/item/properties/geometry'
itemCollection:
description: A GeoJSON FeatureCollection augmented with foreign members that contain values relevant to a STAC entity
type: object
required:
- features
- type
properties:
type:
type: string
enum:
- FeatureCollection
features:
type: array
items:
$ref: '#/components/schemas/item'
links:
$ref: '#/components/schemas/itemCollectionLinks'
itemProperties:
type: object
required:
- datetime
description: provides the core metatdata fields plus extensions
properties:
datetime:
$ref: '#/components/schemas/datetime'
additionalProperties:
description: Any additional properties added in via Item specification or extensions.
itemAssets:
type: object
additionalProperties:
type: object
required:
- href
properties:
href:
type: string
format: url
description: Link to the asset object
example: http://cool-sat.com/catalog/collections/cs/items/CS3-20160503_132130_04/thumb.png
title:
type: string
description: Displayed title
example: Thumbnail
type:
type: string
description: Media type of the asset
example: image/png
datetime:
type: string
description: 'Either a date-time or an interval, open or closed. Date and time expressions
adhere to RFC 3339. Open intervals are expressed using double-dots.
Examples:
* A date-time: "2018-02-12T23:20:50Z"
* A closed interval: "2018-02-12T00:00:00Z/2018-03-18T12:31:12Z"
* Open intervals: "2018-02-12T00:00:00Z/.." or "../2018-03-18T12:31:12Z"
Only features that have a temporal property that intersects the value of
`datetime` are selected.
If a feature has multiple temporal properties, it is the decision of the
server whether only a single temporal property is used to determine
the extent or all relevant temporal properties.'
example: 2018-02-12T00:00:00Z/2018-03-18T12:31:12Z
itemCollectionLinks:
type: array
description: An array of links. Can be used for pagination, e.g. by providing a link with the `next` relation type.
items:
$ref: '#/components/schemas/link'
example:
- rel: next
href: http://api.cool-sat.com/stac/search?next=ANsXtp9mrqN0yrKWhf-y2PUpHRLQb1GT-mtxNcXou8TwkXhi1Jbk
stac_version:
title: STAC version
type: string
example: 1.0.0
itemId:
type: string
example: path/to/example.tif
description: Provider identifier, a unique ID, potentially a link to a file.
itemType:
type: string
description: The GeoJSON type
enum:
- Feature
searchBody:
description: The search criteria
type: object
allOf:
- $ref: '#/components/schemas/bboxFilter'
- $ref: '#/components/schemas/datetimeFilter'
- $ref: '#/components/schemas/intersectsFilter'
- type: object
properties:
limit:
type: integer
example: 10
parameters:
bbox:
name: bbox
in: query
description: 'Only features that have a geometry that intersects the bounding box are selected.
The bounding box is provided as four or six numbers, depending on whether the
coordinate reference system includes a vertical axis (elevation or depth):
* Lower left corner, coordinate axis 1
* Lower left corner, coordinate axis 2
* Lower left corner, coordinate axis 3 (optional)
* Upper right corner, coordinate axis 1
* Upper right corner, coordinate axis 2
* Upper right corner, coordinate axis 3 (optional)
The coordinate reference system of the values is WGS 84 longitude/latitude
(http://www.opengis.net/def/crs/OGC/1.3/CRS84) unless a different coordinate
reference system is specified in the parameter `bbox-crs`.
For WGS 84 longitude/latitude the values are in most cases the sequence of
minimum longitude, minimum latitude, maximum longitude and maximum latitude.
However, in cases where the box spans the antimeridian the first value
(west-most box edge) is larger than the third value (east-most box edge).
If a feature has multiple spatial geometry properties, it is the decision of the
server whether only a single spatial geometry property is used to determine
the extent or all relevant geometries.'
required: false
schema:
type: array
minItems: 4
maxItems: 6
items:
type: number
style: form
explode: false
datetime:
name: datetime
in: query
description: 'Either a date-time or an interval, open or closed. Date and time expressions
adhere to RFC 3339. Open intervals are expressed using double-dots.
Examples:
* A date-time: "2018-02-12T23:20:50Z"
* A closed interval: "2018-02-12T00:00:00Z/2018-03-18T12:31:12Z"
* Open intervals: "2018-02-12T00:00:00Z/.." or "../2018-03-18T12:31:12Z"
Only features that have a temporal property that intersects the value of
`datetime` are selected.
If a feature has multiple temporal properties, it is the decision of the
server whether only a single temporal property is used to determine
the extent or all relevant temporal properties.'
required: false
schema:
type: string
style: form
explode: false
limit:
name: limit
in: query
description: 'The optional limit parameter limits the number of items that are presented in the response document.
Only items are counted that are on the first level of the collection in the response document.
Nested objects contained within the explicitly requested items shall not be counted.
Minimum = 1. Maximum = 10000. Default = 10.'
required: false
schema:
type: integer
minimum: 1
maximum: 10000
default: 10
style: form
explode: false
providerId:
name: providerId
in: path
description: local identifier of a provider
required: true
schema:
type: string
page:
name: page
in: query
description: 'The optional page parameter returns the specified page of results
(with each page having size=limit).
* Minimum = 1
* Default = 1
'
required: false
schema:
type: integer
minimum: 1
default: 1
style: form
explode: false
ids:
name: ids
in: query
description: 'The optional ids parameter returns a FeatureCollection of all matching ids.
If provided all other parameters that further restrict the number of search results (except `page` and `limit`) will be ignored.
'
required: false
schema:
type: array
minItems: 1
items:
type: string
explode: false
collections:
name: collections
in: query
description: 'The collections search parameter is a list of of collection IDs for Items to match.
Only items that are included in one of these collections will be returned, otherwise
all collections will be searched.
'
required: false
schema:
type: array
minItems: 1
items:
type: string
explode: false