European Space Agency (ESA) Search API
The Search API from European Space Agency (ESA) — 1 operation(s) for search.
OpenAPI Specification
openapi: 3.1.0
info:
title: Copernicus Data Space Ecosystem (CDSE) asset-level STAC catalogue Bulk Transaction Extension Search API
description: 'A comprehensive and searchable catalog of Earth observation and scientific datasets that is actively maintained and updated by the Copernicus Data Space Ecosystem. The integrated STAC (SpatioTemporal Asset Catalog) API, which follows the open STAC specification, enables users to access detailed asset-level metadata, including spatial information, temporal coverage, and data specifications. This standardized interface facilitates efficient data discovery and retrieval across the extensive collection of environmental and scientific resources. More information: https://documentation.dataspace.copernicus.eu/'
version: 1.1.0
servers:
- url: /v1
tags:
- name: Search
paths:
/search:
post:
summary: Search
description: Endpoint.
operationId: Search_search_post
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/SearchPostRequest'
responses:
'200':
description: Successful Response
content:
application/geo+json:
schema:
$ref: '#/components/schemas/ItemCollection-Output'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
tags:
- Search
get:
summary: Search
description: Endpoint.
operationId: Search_search_get
parameters:
- name: collections
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: Array of collection Ids to search for items.
example: collection1,collection2
title: Collections
description: Array of collection Ids to search for items.
- name: ids
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: Array of Item ids to return.
example: item1,item2
title: Ids
description: Array of Item ids to return.
- name: bbox
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: Only return items intersecting this bounding box. Mutually exclusive with **intersects**.
example: -175.05,-85.05,175.05,85.05
title: Bbox
description: Only return items intersecting this bounding box. Mutually exclusive with **intersects**.
- name: intersects
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: "Only return items intersecting this GeoJSON Geometry. Mutually exclusive with **bbox**. \n\n*Remember to URL encode the GeoJSON geometry when using GET request*."
title: Intersects
description: "Only return items intersecting this GeoJSON Geometry. Mutually exclusive with **bbox**. \n\n*Remember to URL encode the GeoJSON geometry when using GET request*."
examples:
madrid:
value:
type: Feature
properties: {}
geometry:
coordinates:
- - - -3.8549260500072933
- 40.54923557897152
- - -3.8549260500072933
- 40.29428000041938
- - -3.516597069715033
- 40.29428000041938
- - -3.516597069715033
- 40.54923557897152
- - -3.8549260500072933
- 40.54923557897152
type: Polygon
new-york:
value:
type: Feature
properties: {}
geometry:
coordinates:
- - - -74.50117532354284
- 41.128266394414055
- - -74.50117532354284
- 40.35633909727355
- - -73.46713183168603
- 40.35633909727355
- - -73.46713183168603
- 41.128266394414055
- - -74.50117532354284
- 41.128266394414055
type: Polygon
- name: datetime
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: 'Only return items that have a temporal property that intersects this value.
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.'
title: Datetime
description: 'Only return items that have a temporal property that intersects this value.
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:
datetime:
value: '2018-02-12T23:20:50Z'
closed-interval:
value: 2018-02-12T00:00:00Z/2018-03-18T12:31:12Z
open-interval-from:
value: 2018-02-12T00:00:00Z/..
open-interval-to:
value: ../2018-03-18T12:31:12Z
- name: limit
in: query
required: false
schema:
anyOf:
- type: integer
exclusiveMinimum: 0
- type: 'null'
description: Limits the number of results that are included in each page of the response (capped to 10_000).
default: 10
title: Limit
description: Limits the number of results that are included in each page of the response (capped to 10_000).
- name: query
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: Allows additional filtering based on the properties of Item objects
example: '{"eo:cloud_cover": {"gte": 95}}'
title: Query
description: Allows additional filtering based on the properties of Item objects
- name: sortby
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: An array of property names, prefixed by either '+' for ascending or '-' for descending. If no prefix is provided, '+' is assumed.
example: -gsd,-datetime
title: Sortby
description: An array of property names, prefixed by either '+' for ascending or '-' for descending. If no prefix is provided, '+' is assumed.
- name: fields
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: Include or exclude fields from items body.
example: properties.datetime
title: Fields
description: Include or exclude fields from items body.
- name: filter
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: 'A CQL filter expression for filtering items.
Supports `CQL-JSON` as defined in https://portal.ogc.org/files/96288
Remember to URL encode the CQL-JSON if using GET'
example: id='LC08_L1TP_060247_20180905_20180912_01_T1_L1TP' AND collection='landsat8_l1tp'
title: Filter
description: 'A CQL filter expression for filtering items.
Supports `CQL-JSON` as defined in https://portal.ogc.org/files/96288
Remember to URL encode the CQL-JSON if using GET'
- name: filter-crs
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: The coordinate reference system (CRS) used by spatial literals in the 'filter' value. Default is `http://www.opengis.net/def/crs/OGC/1.3/CRS84`
title: Filter-Crs
description: The coordinate reference system (CRS) used by spatial literals in the 'filter' value. Default is `http://www.opengis.net/def/crs/OGC/1.3/CRS84`
- name: filter-lang
in: query
required: false
schema:
anyOf:
- enum:
- cql-json
- cql2-json
- cql2-text
type: string
- type: 'null'
description: The CQL filter encoding that the 'filter' value uses.
default: cql2-text
title: Filter-Lang
description: The CQL filter encoding that the 'filter' value uses.
- name: token
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
title: Token
responses:
'200':
description: Successful Response
content:
application/geo+json:
schema:
$ref: '#/components/schemas/ItemCollection-Output'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
tags:
- Search
components:
schemas:
stac_pydantic__api__item__Item:
properties:
bbox:
anyOf:
- prefixItems:
- type: number
- type: number
- type: number
- type: number
type: array
maxItems: 4
minItems: 4
- prefixItems:
- type: number
- type: number
- type: number
- type: number
- type: number
- type: number
type: array
maxItems: 6
minItems: 6
- type: 'null'
title: Bbox
type:
type: string
const: Feature
title: Type
geometry:
anyOf:
- oneOf:
- $ref: '#/components/schemas/Point'
- $ref: '#/components/schemas/MultiPoint'
- $ref: '#/components/schemas/LineString'
- $ref: '#/components/schemas/MultiLineString'
- $ref: '#/components/schemas/Polygon'
- $ref: '#/components/schemas/MultiPolygon'
- $ref: '#/components/schemas/GeometryCollection-Output'
discriminator:
propertyName: type
mapping:
GeometryCollection: '#/components/schemas/GeometryCollection-Output'
LineString: '#/components/schemas/LineString'
MultiLineString: '#/components/schemas/MultiLineString'
MultiPoint: '#/components/schemas/MultiPoint'
MultiPolygon: '#/components/schemas/MultiPolygon'
Point: '#/components/schemas/Point'
Polygon: '#/components/schemas/Polygon'
- type: 'null'
title: Geometry
properties:
$ref: '#/components/schemas/ItemProperties'
id:
type: string
minLength: 1
title: Id
stac_version:
type: string
pattern: ^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$
title: Stac Version
default: 1.0.0
assets:
additionalProperties:
$ref: '#/components/schemas/Asset'
type: object
title: Assets
links:
$ref: '#/components/schemas/stac_pydantic__links__Links-Output'
stac_extensions:
anyOf:
- items:
type: string
minLength: 1
format: uri
type: array
- type: 'null'
title: Stac Extensions
default: []
collection:
anyOf:
- type: string
- type: 'null'
title: Collection
type: object
required:
- type
- geometry
- properties
- id
- assets
- links
title: Item
Operator:
type: string
enum:
- eq
- ne
- lt
- lte
- gt
- gte
title: Operator
description: Defines the set of operators supported by the API.
ValidationError:
properties:
loc:
items:
anyOf:
- type: string
- type: integer
type: array
title: Location
msg:
type: string
title: Message
type:
type: string
title: Error Type
type: object
required:
- loc
- msg
- type
title: ValidationError
Point:
properties:
bbox:
anyOf:
- prefixItems:
- type: number
- type: number
- type: number
- type: number
type: array
maxItems: 4
minItems: 4
- prefixItems:
- type: number
- type: number
- type: number
- type: number
- type: number
- type: number
type: array
maxItems: 6
minItems: 6
- type: 'null'
title: Bbox
type:
type: string
const: Point
title: Type
coordinates:
anyOf:
- $ref: '#/components/schemas/Position2D'
- $ref: '#/components/schemas/Position3D'
title: Coordinates
type: object
required:
- type
- coordinates
title: Point
description: Point Model
SortDirections:
type: string
enum:
- asc
- desc
title: SortDirections
Polygon:
properties:
bbox:
anyOf:
- prefixItems:
- type: number
- type: number
- type: number
- type: number
type: array
maxItems: 4
minItems: 4
- prefixItems:
- type: number
- type: number
- type: number
- type: number
- type: number
- type: number
type: array
maxItems: 6
minItems: 6
- type: 'null'
title: Bbox
type:
type: string
const: Polygon
title: Type
coordinates:
items:
items:
anyOf:
- $ref: '#/components/schemas/Position2D'
- $ref: '#/components/schemas/Position3D'
type: array
minItems: 4
type: array
title: Coordinates
type: object
required:
- type
- coordinates
title: Polygon
description: Polygon Model
Link:
properties:
href:
type: string
minLength: 1
title: Href
rel:
type: string
minLength: 1
title: Rel
type:
anyOf:
- $ref: '#/components/schemas/MimeTypes'
- type: 'null'
title:
anyOf:
- type: string
- type: 'null'
title: Title
label:assets:
anyOf:
- type: string
- type: 'null'
title: Label:Assets
additionalProperties: true
type: object
required:
- href
- rel
title: Link
description: https://github.com/radiantearth/stac-spec/blob/v1.0.0/collection-spec/collection-spec.md#link-object
Provider:
properties:
name:
type: string
minLength: 1
title: Name
description:
anyOf:
- type: string
- type: 'null'
title: Description
roles:
anyOf:
- items:
type: string
type: array
- type: 'null'
title: Roles
url:
anyOf:
- type: string
- type: 'null'
title: Url
type: object
required:
- name
title: Provider
description: https://github.com/radiantearth/stac-spec/blob/v1.0.0/collection-spec/collection-spec.md#provider-object
ItemProperties:
properties:
title:
anyOf:
- type: string
- type: 'null'
title: Title
description:
anyOf:
- type: string
- type: 'null'
title: Description
datetime:
anyOf:
- type: string
format: date-time
- type: 'null'
title: Datetime
created:
anyOf:
- type: string
format: date-time
- type: 'null'
title: Created
updated:
anyOf:
- type: string
format: date-time
- type: 'null'
title: Updated
start_datetime:
anyOf:
- type: string
format: date-time
- type: 'null'
title: Start Datetime
end_datetime:
anyOf:
- type: string
format: date-time
- type: 'null'
title: End Datetime
license:
anyOf:
- type: string
- type: 'null'
title: License
providers:
anyOf:
- items:
$ref: '#/components/schemas/Provider'
type: array
- type: 'null'
title: Providers
platform:
anyOf:
- type: string
- type: 'null'
title: Platform
instruments:
anyOf:
- items:
type: string
type: array
- type: 'null'
title: Instruments
constellation:
anyOf:
- type: string
- type: 'null'
title: Constellation
mission:
anyOf:
- type: string
- type: 'null'
title: Mission
gsd:
anyOf:
- type: number
exclusiveMinimum: 0.0
- type: 'null'
title: Gsd
additionalProperties: true
type: object
required:
- datetime
title: ItemProperties
description: https://github.com/radiantearth/stac-spec/blob/v1.0.0/item-spec/item-spec.md#properties-object
GeometryCollection-Input:
properties:
bbox:
anyOf:
- prefixItems:
- type: number
- type: number
- type: number
- type: number
type: array
maxItems: 4
minItems: 4
- prefixItems:
- type: number
- type: number
- type: number
- type: number
- type: number
- type: number
type: array
maxItems: 6
minItems: 6
- type: 'null'
title: Bbox
type:
type: string
const: GeometryCollection
title: Type
geometries:
items:
oneOf:
- $ref: '#/components/schemas/Point'
- $ref: '#/components/schemas/MultiPoint'
- $ref: '#/components/schemas/LineString'
- $ref: '#/components/schemas/MultiLineString'
- $ref: '#/components/schemas/Polygon'
- $ref: '#/components/schemas/MultiPolygon'
- $ref: '#/components/schemas/GeometryCollection-Input'
discriminator:
propertyName: type
mapping:
GeometryCollection: '#/components/schemas/GeometryCollection-Input'
LineString: '#/components/schemas/LineString'
MultiLineString: '#/components/schemas/MultiLineString'
MultiPoint: '#/components/schemas/MultiPoint'
MultiPolygon: '#/components/schemas/MultiPolygon'
Point: '#/components/schemas/Point'
Polygon: '#/components/schemas/Polygon'
type: array
title: Geometries
type: object
required:
- type
- geometries
title: GeometryCollection
description: GeometryCollection Model
SearchPostRequest:
properties:
collections:
anyOf:
- items:
type: string
type: array
- type: 'null'
title: Collections
ids:
anyOf:
- items:
type: string
type: array
- type: 'null'
title: Ids
bbox:
anyOf:
- prefixItems:
- anyOf:
- type: number
- type: integer
- anyOf:
- type: number
- type: integer
- anyOf:
- type: number
- type: integer
- anyOf:
- type: number
- type: integer
type: array
maxItems: 4
minItems: 4
- prefixItems:
- anyOf:
- type: number
- type: integer
- anyOf:
- type: number
- type: integer
- anyOf:
- type: number
- type: integer
- anyOf:
- type: number
- type: integer
- anyOf:
- type: number
- type: integer
- anyOf:
- type: number
- type: integer
type: array
maxItems: 6
minItems: 6
- type: 'null'
title: Bbox
intersects:
anyOf:
- $ref: '#/components/schemas/Point'
- $ref: '#/components/schemas/MultiPoint'
- $ref: '#/components/schemas/LineString'
- $ref: '#/components/schemas/MultiLineString'
- $ref: '#/components/schemas/Polygon'
- $ref: '#/components/schemas/MultiPolygon'
- $ref: '#/components/schemas/GeometryCollection-Input'
- type: 'null'
title: Intersects
datetime:
anyOf:
- type: string
- type: 'null'
title: Datetime
limit:
anyOf:
- type: integer
exclusiveMinimum: 0.0
- type: 'null'
title: Limit
description: Limits the number of results that are included in each page of the response (capped to 10_000).
default: 10
conf:
anyOf:
- additionalProperties: true
type: object
- type: 'null'
title: Conf
query:
anyOf:
- additionalProperties:
additionalProperties: true
propertyNames:
$ref: '#/components/schemas/Operator'
type: object
type: object
- type: 'null'
title: Query
sortby:
anyOf:
- items:
$ref: '#/components/schemas/SortExtension'
type: array
- type: 'null'
title: Sortby
description: 'An array of property (field) names, and direction in form of ''{''field'': ''<property_name>'', ''direction'':''<direction>''}'''
example:
- direction: asc
field: properties.created
fields:
anyOf:
- $ref: '#/components/schemas/PostFieldsExtension'
- type: 'null'
description: Include or exclude fields from items body.
default:
include: []
exclude: []
filter:
anyOf:
- additionalProperties: true
type: object
- type: 'null'
title: Filter
description: A CQL filter expression for filtering items.
example:
args:
- args:
- property: id
- LC08_L1TP_060247_20180905_20180912_01_T1_L1TP
op: '='
- args:
- property: collection
- landsat8_l1tp
op: '='
op: and
filter-crs:
anyOf:
- type: string
- type: 'null'
title: Filter-Crs
description: The coordinate reference system (CRS) used by spatial literals in the 'filter' value. Default is `http://www.opengis.net/def/crs/OGC/1.3/CRS84`
filter-lang:
anyOf:
- type: string
enum:
- cql-json
- cql2-json
- type: 'null'
title: Filter-Lang
description: The CQL filter encoding that the 'filter' value uses.
default: cql2-json
token:
anyOf:
- type: string
- type: 'null'
title: Token
type: object
title: SearchPostRequest
PostFieldsExtension:
properties:
include:
anyOf:
- items:
type: string
type: array
uniqueItems: true
- type: 'null'
title: Include
default: []
exclude:
anyOf:
- items:
type: string
type: array
uniqueItems: true
- type: 'null'
title: Exclude
default: []
type: object
title: PostFieldsExtension
description: "FieldsExtension.\n\nAttributes:\n include: set of fields to include.\n exclude: set of fields to exclude."
Position3D:
prefixItems:
- type: number
title: Longitude
- type: number
title: Latitude
- type: number
title: Altitude
type: array
maxItems: 3
minItems: 3
SortExtension:
properties:
field:
type: string
minLength: 1
title: Field
direction:
$ref: '#/components/schemas/SortDirections'
type: object
required:
- field
- direction
title: SortExtension
description: https://github.com/radiantearth/stac-api-spec/tree/master/extensions/sort#sort-api-extension
PaginationLink:
properties:
href:
type: string
minLength: 1
title: Href
rel:
type: string
enum:
- next
- prev
title: Rel
type:
anyOf:
- $ref: '#/components/schemas/MimeTypes'
- type: 'null'
title:
anyOf:
- type: string
- type: 'null'
title: Title
label:assets:
anyOf:
- type: string
- type: 'null'
title: Label:Assets
method:
type: string
enum:
- GET
- POST
title: Method
default: GET
headers:
anyOf:
- additionalProperties: true
type: object
- type: 'null'
title: Headers
body:
anyOf:
- additionalProperties: true
type: object
- type: 'null'
title: Body
merge:
type: boolean
title: Merge
default: false
additionalProperties: true
type: object
required:
- href
- rel
title: PaginationLink
description: https://github.com/radiantearth/stac-api-spec/blob/v1.0.0/item-search/README.md#pagination
ItemsLink:
properties:
href:
type: string
pattern: .*\/items(\?.*)?\b
title: Href
rel:
type: string
enum:
- self
- items
title: Rel
type:
type: string
const: application/geo+json
title: Type
default: application/geo+json
title:
anyOf:
- type: string
- type: 'null'
title: Title
label:assets:
anyOf:
- type: string
- type: 'null'
title: Label:Assets
method:
type: string
enum:
- GET
- POST
title: Method
default: GET
headers:
anyOf:
- additionalProperties: true
type: object
- type: 'null'
title: Headers
body:
anyOf:
- additionalProperties: true
type: object
- type: 'null'
title: Body
merge:
type: boolean
title: Merge
default: false
additionalProperties: true
type: object
required:
- href
- rel
title: ItemsLink
SearchLink:
properties:
href:
type: string
pattern: .*\/search(\?.*)?\b
title: Href
rel:
type: string
enum:
- self
- search
- next
- prev
title: Rel
type:
type: string
const: application/geo+json
title: Type
default: application/geo+json
title:
anyOf:
- type: string
- type: 'null'
title: Title
label:assets:
anyOf:
- type: string
- type: 'null'
title: Label:Assets
method:
type: string
enum:
- GET
- POST
title: Method
default: GET
headers:
anyOf:
- additionalProperties: true
type: object
- type: 'null'
title: Headers
body:
anyOf:
- additionalProperties: true
type: object
- type: 'null'
title: Body
merge:
type: boolean
title: Merge
default: false
additionalProperties: true
type: object
required:
- href
- rel
title: SearchLink
description: https://github.com/radiantearth/stac-api-spec/tree/v1.0.0/item-search#link-relations
MultiPolygon:
properties:
bbox:
anyOf:
- prefixItems:
- type: number
- type: number
- type: number
- type: number
type: array
maxItems: 4
minItems: 4
- prefixItems:
- type: number
- type: number
- type: number
- type: number
- type: number
- type: number
type: array
maxItems: 6
minItems: 6
- type: 'null'
title: Bbox
type:
type: string
const: MultiPolygon
title: Type
coordinates:
items:
items:
items:
anyOf:
- $ref: '#/components/schemas/Position2D'
- $ref: '#/components/schemas/Position3D'
type: array
minItems: 4
type: array
type: array
title: Coordinates
type: object
required:
- type
- coordinates
title: MultiPolygon
description: MultiPolygon Model
MultiPoint:
properties:
bbox:
anyOf:
- prefixItems:
- type: number
- type: number
- type: number
- type: number
type: array
maxItems: 4
minItems: 4
- prefixItems:
- type: number
- type: number
- type: number
- type: number
- type: number
- type: number
type: array
maxItems: 6
minItems: 6
- type: 'null'
title: Bbox
type:
type: string
const: MultiPoint
title: Type
coordinates:
items:
anyOf:
- $ref: '#/components/schemas/Position2D'
- $ref: '#/components/schemas/Position3D'
type: array
title: Coordinates
type: object
required:
- type
- coordinates
title: MultiPoint
description: MultiPoint Model
HTTPValidationError:
properties:
detail:
items:
$ref: '#/components/schemas/ValidationError'
type: array
title: Detail
type: object
title: HTTPValidationError
Asset:
properties:
href:
type: s
# --- truncated at 32 KB (39 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/esa/refs/heads/main/openapi/esa-search-api-openapi.yml