openapi: 3.0.2
info:
title: EOC EO Products Service Capabilities STAC API
description: Provides interoperable access to metadata from EO collections and products of DLR's Earth Observation Center (EOC).
contact:
name: Geoservice Manager - Earth Observation Center (EOC), DLR
email: geoservice@dlr.de
version: 1.0.0
servers:
- url: https://geoservice.dlr.de/eoc/ogc/stac/v1
description: This server
tags:
- name: STAC
paths:
/search:
get:
tags:
- STAC
summary: Search STAC items with simple filtering.
description: 'Retrieve Items matching filters. Intended as a shorthand API for simple
queries.'
operationId: getSearchSTAC
parameters:
- 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 (height
or depth):
* Lower left corner, coordinate axis 1
* Lower left corner, coordinate axis 2
* Minimum value, coordinate axis 3 (optional)
* Upper right corner, coordinate axis 1
* Upper right corner, coordinate axis 2
* Maximum value, 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).
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 the vertical axis is included, the third and the sixth number are
the bottom and the top of the 3-dimensional bounding box.
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.
Example: The bounding box of the New Zealand Exclusive Economic Zone in
WGS 84 (from 160.6°E to 170°W and from 55.95°S to 25.89°S) would be
represented in JSON as `[160.6, -55.95, -170, -25.89]` and in a query as
`bbox=160.6,-55.95,-170,-25.89`.'
required: false
style: form
explode: false
schema:
type: array
items:
type: number
- 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
style: form
explode: false
schema:
type: string
- 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
style: form
explode: false
schema:
maximum: 10000
minimum: 1
type: integer
default: 10
- name: ids
in: query
description: 'Array of Item ids to return. All other filter parameters that further
restrict the number of search results are ignored'
required: false
style: form
explode: false
schema:
$ref: '#/components/schemas/ids'
- name: collections
in: query
description: 'Array of Collection IDs to include in the search for items.
Only Items in one of the provided Collections will be searched
'
required: false
style: form
explode: false
schema:
$ref: '#/components/schemas/collectionsArray'
- name: sortby
in: query
description: 'An array of property names, prefixed by either "+" for ascending or
"-" for descending. If no prefix is provided, "+" is assumed.'
required: false
style: form
explode: false
schema:
type: string
example: +id,-properties.eo:cloud_cover
- name: fields
in: query
description: Determines the shape of the features in the response
required: false
style: form
explode: false
schema:
type: string
example: id,type,-geometry,bbox,properties,-links,-assets
- name: query
in: query
description: query for properties in items. Use the JSON form of the queryFilter in POST.
required: false
style: form
explode: true
schema:
type: string
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:
tags:
- STAC
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 /search` is implemented.
If this endpoint is implemented on a server, it is required to add a
link referring to this endpoint with `rel` set to `search` and `method`
set to `POST` to the `links` array in `GET /`.'
operationId: postSearchSTAC
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:
queryFilter:
type: object
properties:
query:
$ref: '#/components/schemas/query'
description: Allows users to query properties for specific values
stac_extensions:
title: STAC extensions
uniqueItems: true
type: array
items:
anyOf:
- title: Reference to a JSON Schema
type: string
format: uri
- title: Reference to a core extension
type: string
exception:
required:
- code
type: object
properties:
code:
type: string
description:
type: string
description: 'Information about the exception: an error code plus an optional description.'
datetimeFilter:
type: object
properties:
datetime:
$ref: '#/components/schemas/datetime_interval'
description: An object representing a date+time based filter.
item:
required:
- assets
- bbox
- geometry
- id
- links
- properties
- stac_version
- type
type: object
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:
$ref: '#/components/schemas/geometryGeoJSON'
type:
$ref: '#/components/schemas/itemType'
properties:
$ref: '#/components/schemas/itemProperties'
links:
type: array
items:
$ref: '#/components/schemas/link'
assets:
$ref: '#/components/schemas/itemAssets'
description: A GeoJSON Feature augmented with foreign members that contain values relevant to a STAC entity
example:
stac_version: 0.9.0
stac_extensions:
- eo
- view
- https://example.com/cs-extension/1.0/schema.json
type: Feature
id: CS3-20160503_132131_05
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:22:30.040Z'
title: A CS3 item
license: PDDL-1.0
providers:
- name: CoolSat
roles:
- producer
- licensor
url: https://cool-sat.com/
view:sun_azimuth: 168.7
eo:cloud_cover: 0.12
view:off_nadir: 1.4
platform: coolsat2
instruments:
- cool_sensor_v1
eo:bands: []
view:sun_elevation: 33.4
eo:gsd: 0.512
collection: CS3
links:
- rel: self
href: http://cool-sat.com/collections/CS3/items/20160503_132130_04
- rel: root
href: http://cool-sat.com/collections
- rel: parent
href: http://cool-sat.com/collections/CS3
- rel: collection
href: http://cool-sat.com/collections/CS3
assets:
analytic:
href: http://cool-sat.com/static-catalog/CS3/20160503_132130_04/analytic.tif
title: 4-Band Analytic
thumbnail:
href: http://cool-sat.com/static-catalog/CS3/20160503_132130_04/thumbnail.png
title: Thumbnail
bboxFilter:
type: object
properties:
bbox:
$ref: '#/components/schemas/bbox'
description: Only return items that intersect the provided bounding box.
link:
required:
- href
type: object
properties:
href:
type: string
example: http://data.example.com/buildings/123
rel:
type: string
example: alternate
type:
type: string
example: application/geo+json
hreflang:
type: string
example: en
title:
type: string
example: Trierer Strasse 70, 53115 Bonn
length:
type: integer
limit:
maximum: 10000
minimum: 1
type: integer
description: The maximum number of results to return (page size). Defaults to 10
example: 10
default: 10
polygonGeoJSON:
required:
- coordinates
- type
type: object
properties:
type:
type: string
enum:
- Polygon
coordinates:
type: array
items:
minItems: 4
type: array
items:
minItems: 2
type: array
items:
type: number
multipolygonGeoJSON:
required:
- coordinates
- type
type: object
properties:
type:
type: string
enum:
- MultiPolygon
coordinates:
type: array
items:
type: array
items:
minItems: 4
type: array
items:
minItems: 2
type: array
items:
type: number
bbox:
maxItems: 6
minItems: 4
type: array
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\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\nExample: The bounding box of the New Zealand Exclusive Economic Zone in\nWGS 84 (from 160.6°E to 170°W and from 55.95°S to 25.89°S) would be\nrepresented in JSON as `[160.6, -55.95, -170, -25.89]` and in a query as\n`bbox=160.6,-55.95,-170,-25.89`."
example:
- -110
- 39.5
- -105
- 40.5
items:
type: number
datetime_interval:
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
sortby:
minItems: 1
type: array
description: 'An array of objects containing a property name and sort direction.
'
example:
- field: properties.eo:cloud_cover
direction: asc
- field: id
direction: desc
items:
required:
- direction
- field
type: object
properties:
field:
type: string
direction:
type: string
enum:
- asc
- desc
default: asc
geometryGeoJSON:
oneOf:
- $ref: '#/components/schemas/pointGeoJSON'
- $ref: '#/components/schemas/multipointGeoJSON'
- $ref: '#/components/schemas/linestringGeoJSON'
- $ref: '#/components/schemas/multilinestringGeoJSON'
- $ref: '#/components/schemas/polygonGeoJSON'
- $ref: '#/components/schemas/multipolygonGeoJSON'
- $ref: '#/components/schemas/geometrycollectionGeoJSON'
intersectsFilter:
type: object
properties:
intersects:
$ref: '#/components/schemas/geometryGeoJSON'
description: Only returns items that intersect with the provided polygon.
fieldsFilter:
type: object
properties:
fields:
$ref: '#/components/schemas/fields'
description: Determines the shape of the features in the response
linestringGeoJSON:
required:
- coordinates
- type
type: object
properties:
type:
type: string
enum:
- LineString
coordinates:
minItems: 2
type: array
items:
minItems: 2
type: array
items:
type: number
ids:
type: array
description: 'Array of Item ids to return. All other filter parameters that further
restrict the number of search results are ignored'
items:
type: string
multilinestringGeoJSON:
required:
- coordinates
- type
type: object
properties:
type:
type: string
enum:
- MultiLineString
coordinates:
type: array
items:
minItems: 2
type: array
items:
minItems: 2
type: array
items:
type: number
itemCollection:
required:
- features
- type
type: object
properties:
type:
type: string
enum:
- FeatureCollection
features:
type: array
items:
$ref: '#/components/schemas/item'
links:
$ref: '#/components/schemas/itemCollectionLinks'
context:
$ref: '#/components/schemas/itemCollection_context'
description: A GeoJSON FeatureCollection augmented with foreign members that contain values relevant to a STAC entity
itemProperties:
required:
- datetime
type: object
properties:
datetime:
$ref: '#/components/schemas/datetime'
additionalProperties:
type: object
description: Any additional properties added in via Item specification or extensions.
description: provides the core metatdata fields plus extensions
limitFilter:
type: object
properties:
limit:
$ref: '#/components/schemas/limit'
description: Only returns maximum number of results (page size)
query:
type: string
description: Define which properties to query and the operations to apply
example: '{"eo:cloud_cover":{"value":"properties.eo:cloud_cover >= 0 && properties.eo:cloud_cover < 10","summary":"Cloud Cover is between 0 and 10 (exclusive)"},"datetime":{"value":"(properties.datetime >= 2019-01-01T00:00:00Z && properties.datetime < 2019-01-02T00:00:00Z) || (properties.datetime >= 2019-02-01T00:00:00Z && properties.datetime < 2019-02-02T00:00:00Z)","summary":"Datetime is either on the first day of January or first day of February 2019"},"gsd":{"value":"properties.gsd < 10","summary":"GSD (resolution) is less than 10 meters"}}'
collectionsFilter:
type: object
properties:
collections:
$ref: '#/components/schemas/collectionsArray'
description: Only returns the collections specified
itemAssets:
type: object
additionalProperties:
required:
- href
type: object
properties:
href:
type: string
description: Link to the asset object
format: url
example: http://cool-sat.com/catalog/collections/cs/items/CS3-20160503_132130_04/thumb.png
title:
type: string
description: Displayed title
example: Thumbnail
description:
type: string
description: 'Multi-line description to explain the asset.
[CommonMark 0.29](http://commonmark.org/) syntax MAY be used for rich text representation.'
example: Small 256x256px PNG thumbnail for a preview.
type:
type: string
description: Media type of the asset
example: image/png
roles:
type: array
description: Purposes of the asset
example:
- thumbnail
items:
type: string
geometrycollectionGeoJSON:
required:
- geometries
- type
type: object
properties:
type:
type: string
enum:
- GeometryCollection
geometries:
type: array
items:
$ref: '#/components/schemas/geometryGeoJSON'
itemCollection_context:
required:
- returned
type: object
properties:
returned:
minimum: 0
type: integer
example: 1
limit:
minimum: 0
type: integer
nullable: true
example: 5
matched:
minimum: 0
type: integer
example: 314159
fields:
type: object
properties:
include:
type: array
items:
type: string
exclude:
type: array
items:
type: string
description: 'The include and exclude members specify an array of
property names that are either included or excluded
from the result, respectively. If both include and
exclude are specified, include takes precedence.
Values should include the full JSON path of the property.
'
example:
include:
- id
- properties.eo:cloud_cover
exclude:
- geometry
- properties.datetime
pointGeoJSON:
required:
- coordinates
- type
type: object
properties:
type:
type: string
enum:
- Point
coordinates:
minItems: 2
type: array
items:
type: number
datetime:
type: string
description: 'The searchable date and time of the assets, in UTC.
It is formatted according to [RFC 3339, section 5.6](https://tools.ietf.org/html/rfc3339#section-5.6).
`null` is allowed, but requires `start_datetime` and `end_datetime` from common metadata to be set.'
format: date-time
nullable: true
itemCollectionLinks:
type: array
description: An array of links. Can be used for pagination, e.g. by providing a link with the `next` relation type.
example:
- rel: next
href: http://api.cool-sat.com/search?next=ANsXtp9mrqN0yrKWhf-y2PUpHRLQb1GT-mtxNcXou8TwkXhi1Jbk
items:
$ref: '#/components/schemas/link'
sortFilter:
type: object
properties:
sortby:
$ref: '#/components/schemas/sortby'
description: Sort the results
stac_version:
title: STAC version
type: string
example: 0.9.0
itemId:
type: string
description: Provider identifier, a unique ID, potentially a link to a file.
example: path/to/example.tif
multipointGeoJSON:
required:
- coordinates
- type
type: object
properties:
type:
type: string
enum:
- MultiPoint
coordinates:
type: array
items:
minItems: 2
type: array
items:
type: number
idsFilter:
type: object
properties:
ids:
$ref: '#/components/schemas/ids'
description: Only returns items that match the array of given ids
itemType:
type: string
description: The GeoJSON type
enum:
- Feature
searchBody:
type: object
description: The search criteria
allOf:
- $ref: '#/components/schemas/bboxFilter'
- $ref: '#/components/schemas/datetimeFilter'
- $ref: '#/components/schemas/intersectsFilter'
- $ref: '#/components/schemas/collectionsFilter'
- $ref: '#/components/schemas/idsFilter'
- $ref: '#/components/schemas/limitFilter'
- $ref: '#/components/schemas/sortFilter'
- $ref: '#/components/schemas/fieldsFilter'
- $ref: '#/components/schemas/queryFilter'
collectionsArray:
type: array
description: 'Array of Collection IDs to include in the search for items.
Only Items in one of the provided Collections will be searched.'
items:
type: string
externalDocs:
description: STAC API specification
url: https://github.com/radiantearth/stac-api-spec