geodatacube API (1.0.0-beta)

Download OpenAPI specification:Download

The geodatacube API specification for interoperable cloud-based processing of large Earth observation datacubes.

Conformance class: https://api.geodatacube.example/1.0.0-beta

API Principles

Language

In the specification the key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in RFC 2119 and RFC 8174.

Casing

Unless otherwise stated the API works case sensitive.

All names SHOULD be written in snake case, i.e. words are separated with one underscore character (_) and no spaces, with all letters lower-cased. Example: hello_world. This applies particularly to endpoints and JSON property names. HTTP header fields are generally case-insensitive according to RFC 7230 and in the specification we follow their respective casing conventions, e.g. Content-Type or GDC-Identifier, for better readability and consistency.

HTTP / REST

This uses HTTP REST Level 2 for communication between client and back-end server.

Public APIs MUST be available via HTTPS only.

Endpoints are made use meaningful HTTP verbs (e.g. GET, POST, PUT, PATCH, DELETE) whenever technically possible. If there is a need to transfer big chunks of data for a GET requests to the back-end, POST requests MAY be used as a replacement as they support to send data via request body. Unless otherwise stated, PATCH requests are only defined to work on direct (first-level) children of the full JSON object. Therefore, changing a property on a deeper level of the full JSON object always requires to send the whole JSON object defined by the first-level property.

Naming of endpoints follow the REST principles. Therefore, endpoints are centered around resources. Resource identifiers MUST be named with a noun in plural form except for single actions that can not be modelled with the regular HTTP verbs. Single actions MUST be single endpoints with a single HTTP verb (POST is RECOMMENDED) and no other endpoints beneath it.

The API makes use of HTTP Content Negotiation, including, but not limited to, the request headers Accept, Accept-Charset and Accept-Language.

JSON

The API uses JSON for request and response bodies whenever feasible. Services use JSON as the default encoding. Other encodings can be requested using HTTP Content Negotiation (Accept header). Clients and servers MUST NOT rely on the order in which properties appear in JSON. To keep the response size small, lists of resources (e.g. the list of batch jobs) usually should not include nested JSON objects, if this information can be requested from the individual resource endpoints (e.g. the metadata for a single batch job).

Charset

Services use UTF-8 as the default charset if not negotiated otherwise with HTTP Content Negotiation (Accept-Charset header).

Web Linking

The API is designed in a way that to most entities (e.g. collections and processes) a set of links can be added. These can be alternate representations, e.g. data discovery via OGC WCS or OGC CSW, references to a license, references to actual raw data for downloading, detailed information about pre-processing and more. Clients should allow users to follow the links.

Whenever links are utilized in the API, the description explains which relation (rel property) types are commonly used. A list of standardized link relations types is provided by IANA and the API tries to align whenever feasible.

Some very common relation types - usually not mentioned explicitly in the description of links fields - are:

  1. self: which allows link to the location that the resource can be (permanently) found online.This is particularly useful when the data is data is made available offline, so that the downstream user knows where the data has come from.

  2. alternate: An alternative representation of the resource, may it be another metadata standard the data is available in or simply a human-readable version in HTML or PDF.

  3. about: A resource that is related or further explains the resource, e.g. a user guide.

  4. canonical: This relation type usually points to a publicly accessible and more long-lived URL for a resource that otherwise often requires (Bearer) authentication with a short-lived token. This way the the exposed resources can be used by clients without additional authentication steps. For example, a shared user-defined process or batch job results could be exposed via a canonical link. If a URL should be publicly available to everyone, it can simply a user-specific URL, e.g. https://geodatacube.example/processes/john_doe/ndvi. For resources that should only be accessible to a certain group of user, a signed URL could be given, e.g. https://geodatacube.example/processes/81zjh1tc2pt52gbx/ndvi.

Generally, it is RECOMMENDED to add descriptive titles (propertty title) and media type information (propertty type) for a better user experience.

Error Handling

The success of requests MUST be indicated using HTTP status codes according to RFC 7231.

If the API responds with a status code between 100 and 399 the back-end indicates that the request has been handled successfully.

In general an error is communicated with a status code between 400 and 599. Client errors are defined as a client passing invalid data to the service and the service correctly rejecting that data. Examples include invalid credentials, incorrect parameters, unknown versions, or similar. These are generally "4xx" HTTP error codes and are the result of a client passing incorrect or invalid data. Client errors do not contribute to overall API availability.

Server errors are defined as the server failing to correctly return in response to a valid client request. These are generally "5xx" HTTP error codes. Server errors do contribute to the overall API availability. Calls that fail due to rate limiting or quota failures MUST NOT count as server errors.

JSON error object

A JSON error object SHOULD be sent with all responses that have a status code between 400 and 599.

{
  "id": "936DA01F-9ABD-4D9D-80C7-02AF85C822A8",
  "code": "SampleError",
  "message": "A sample error message.",
  "url": "https://geodatacube.example/docs/errors/SampleError"
}

Sending code and message is REQUIRED.

  • A back-end MAY add a free-form id (unique identifier) to the error response to be able to log and track errors with further non-disclosable details.

  • The code is proprietary textual error code.

  • The message explains the reason the server is rejecting the request. For "4xx" error codes the message explains how the client needs to modify the request.

    By default the message MUST be sent in English language. Content Negotiation is used to localize the error messages: If an Accept-Language header is sent by the client and a translation is available, the message should be translated accordingly and the Content-Language header must be present in the response. See "How to localize your API" for more information.

  • url is an OPTIONAL attribute and contains a link to a resource that is explaining the error and potential solutions in-depth.

Standardized status codes

The API usually uses the following HTTP status codes for successful requests:

  • 200 OK: Indicates a successful request with a response body being sent.
  • 201 Created Indicates a successful request that successfully created a new resource. Sends a Location header to the newly created resource without a response body.
  • 202 Accepted Indicates a successful request that successfully queued the creation of a new resource, but it has not been created yet. The response is sent without a response body.
  • 204 No Content: Indicates a successful request without a response body being sent.

The API has some commonly used HTTP status codes for failed requests:

  • 400 Bad Request: The back-end responds with this error code whenever the error has its origin on client side and no other HTTP status code in the 400 range is suitable.

  • 401 Unauthorized: The client did not provide any authentication details for a resource requiring authentication or the provided authentication details are not correct.

  • 403 Forbidden: The client did provided correct authentication details, but the privileges/permissions of the provided credentials do not allow to request the resource.

  • 404 Not Found: The resource specified by the path does not exist, i.e. one of the resources belonging to the specified identifiers are not available at the back-end. Note: Unsupported endpoints MAY also return HTTP status code 501.

  • 500 Internal Server Error: The error has its origin on server side and no other status code in the 500 range is suitable.

  • 501 Not Implemented: The requested endpoint is part of the API specification, but is not implemented (yet) by the back-end. Note: Unsupported endpoints MAY also return HTTP status code 404.

If a HTTP status code in the 400 range is returned, the client SHOULD NOT repeat the request without modifications. For HTTP status code in the 500 range, the client MAY repeat the same request later.

All HTTP status codes defined in RFC 7231 in the 400 and 500 ranges can be used as error code in addition to the most used status codes mentioned here. Responding with error codes 400 and 500 SHOULD be avoided in favor of any more specific standardized or proprietary error code.

Temporal data

Date, time, intervals and durations are formatted based on ISO 8601 or its profile RFC 3339 whenever there is an appropriate encoding available in the standard. All temporal data are specified based on the Gregorian calendar.

Authentication

The API offers one forms of authentication by default:

  • Basic at GET /credentials/basic
  • OpenID Connect at GET /credentials/oidc

After authentication with any of the methods listed above, the tokens obtained during the authentication workflows can be sent to protected endpoints in subsequent requests.

Further authentication methods MAY be added by back-ends.

Bearer

Security Scheme Type: HTTP
HTTP Authorization Scheme: bearer
Bearer format: The Bearer Token MUST consist of the authentication method, a provider ID (if available) and the token itself. All separated by a forward slash `/`. Examples (replace `TOKEN` with the actual access token): (1) Basic authentication (no provider ID available): `basic//TOKEN` (2) OpenID Connect (provider ID is `ms`): `oidc/ms/TOKEN`. For OpenID Connect, the provider ID corresponds to the value specified for `id` for each provider in `GET /credentials/oidc`.

Basic

Security Scheme Type: HTTP
HTTP Authorization Scheme: basic

Note: Although it is possible to request several public endpoints for capabilities and discovery that don't require authorization, it is RECOMMENDED that clients (re-)request the public endpoints that support Bearer authentication with the Bearer token once available to also retrieve any private data that is made available specifically for the authenticated user. This may require that clients clear any cached data they retrieved from public endpoints before.

Cross-Origin Resource Sharing (CORS)

Cross-origin resource sharing (CORS) is a mechanism that allows restricted resources [...] on a web page to be requested from another domain outside the domain from which the first resource was served. [...] CORS defines a way in which a browser and server can interact to determine whether or not it is safe to allow the cross-origin request. It allows for more freedom and functionality than purely same-origin requests, but is more secure than simply allowing all cross-origin requests.

Source: https://en.wikipedia.org/wiki/Cross-origin_resource_sharing

Geodatacube-API-based back-ends are usually hosted on a different domain / host than the client that is requesting data from the back-end. Therefore most requests to the back-end are blocked by all modern browsers. This leads to the problem that the JavaScript library and any browser-based application can't access back-ends. Therefore, all back-end providers SHOULD support CORS to enable browser-based applications to access back-ends. CORS is a recommendation of the W3C organization. The following chapters will explain how back-end providers can implement CORS support.

Tip: Most servers can send the required headers and the responses to the OPTIONS requests automatically for all endpoints. Otherwise you may also use a proxy server to add the headers and OPTIONS responses.

CORS headers

The following headers MUST be included with every response:

Name Description Example
Access-Control-Allow-Origin Allowed origin for the request, including protocol, host and port or * for all origins. It is RECOMMENDED to return the value * to allow requests from browser-based implementations. *
Access-Control-Expose-Headers Some endpoints require to send additional HTTP response headers such as GDC-Identifier and Location. To make these headers available to browser-based clients, they MUST be white-listed with this CORS header. The following HTTP headers are white-listed by browsers and MUST NOT be included: Cache-Control, Content-Language, Content-Length, Content-Type, Expires, Last-Modified and Pragma. At least the following headers MUST be listed in this version of the API: Link, Location, and GDC-Identifier. Link, Location, GDC-Identifier

Example request and response

Request:

POST /api/v1/jobs HTTP/1.1
Host: geodatacube.example
Origin: https://company.example:8080
Authorization: Bearer basic//ZXhhbXBsZTpleGFtcGxl

Response:

HTTP/1.1 201 Created
Access-Control-Allow-Origin: *
Access-Control-Expose-Headers: Location, GDC-Identifier, Link
Content-Type: application/json
Location: https://geodatacube.example/api/v1/jobs/abc123
GDC-Identifier: abc123

OPTIONS method

All endpoints must respond to the OPTIONS HTTP method. This is a response for the preflight requests made by web browsers before sending the actual request (e.g. POST /jobs). It needs to respond with a status code of 204 and no response body. In addition to the HTTP headers shown in the table above, the following HTTP headers MUST be included with every response to an OPTIONS request:

Name Description Example
Access-Control-Allow-Headers Comma-separated list of HTTP headers allowed to be sent with the actual (non-preflight) request. MUST contain at least Authorization if any kind of authorization is implemented by the back-end. Authorization, Content-Type
Access-Control-Allow-Methods Comma-separated list of HTTP methods allowed to be requested. Back-ends MUST list all implemented HTTP methods for the endpoint. OPTIONS, GET, POST, PATCH, PUT, DELETE
Content-Type SHOULD return the content type delivered by the request that the permission is requested for. application/json

Example request and response

Request:

OPTIONS /api/v1/jobs HTTP/1.1
Host: geodatacube.example
Origin: https://company.example:8080
Access-Control-Request-Method: POST 
Access-Control-Request-Headers: Authorization, Content-Type

Note that the Access-Control-Request-* headers are automatically attached to the requests by the browsers.

Response:

HTTP/1.1 204 No Content
Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: OPTIONS, GET, POST, PATCH, PUT, DELETE
Access-Control-Allow-Headers: Authorization, Content-Type
Access-Control-Expose-Headers: Location, GDC-Identifier, Link
Content-Type: application/json

Capabilities

General information about the API implementation and other supported capabilities at the back-end.

Information about the back-end

Lists general information about the back-end, including which version and endpoints of the geodatacube API are supported. May also include billing information.

Authorizations:
None

Responses

Response samples

Content type
application/json
{}

Conformance classes this API implements

Lists all conformance classes specified in various standards that the implementation conforms to. Conformance classes are commonly used in all OGC APIs and the STAC API specification.

The conformance classes listed at this endpoint and listed in the corresponding conformsTo property in GET / MUST be equal.

More details:

Responses

Account Management

The following endpoints handle authentication and basic user profiles. See also Authentication. In general, the API only defines a minimum subset of account management. It allows to authenticate and authorize a user, which may include user registration with OpenID Connect, For accounting, quota handling and similar functionality you can explore the openEO API.

Therefore, the API leaves some aspects open that have to be handled by the back-ends separately, including

  • credentials recovery, e.g. retrieving a forgotten password
  • user data management, e.g. changing the users payment details or email address
  • payments, i.e. topping up credits for pre-paid services or paying for post-paid services
  • accounting related tasks, e.g. processing costs and creating invoices,
  • user registration (except for user registration with OpenID Connect).

HTTP Basic authentication

Checks the credentials provided through HTTP Basic Authentication according to RFC 7617 and returns an access token for valid credentials.

The credentials (username and password) MUST be sent in the HTTP header Authorization with type Basic and the Base64 encoded string consisting of username and password separated by a double colon :. The header would look as follows for username user and password pw: Authorization: Basic dXNlcjpwdw==.

The access token has to be used in the Bearer token for authorization in subsequent API calls (see also the information about Bearer tokens in this document). The access token returned by this request MUST NOT be provided with basic// prefix, but the Bearer Token sent in subsequent API calls to protected endpoints MUST be prefixed with basic//. The header in subsequent API calls would look as follows: Authorization: Bearer basic//TOKEN (replace TOKEN with the actual access token).

It is RECOMMENDED to implement this authentication method for non-public services only.

Authorizations:
Basic

Responses

Response samples

Content type
application/json
{
  • "access_token": "b34ba2bdf9ac9ee1"
}

OpenID Connect authentication

Lists the supported OpenID Connect providers (OP). OpenID Connect Providers MUST support OpenID Connect Discovery.

It is highly RECOMMENDED to implement OpenID Connect for public services in favor of Basic authentication.

GDC clients MUST use the access token as part of the Bearer token for authorization in subsequent API calls (see also the information about Bearer tokens in this document). Clients MUST NOT use the id token or the authorization code. The access token provided by an OpenID Connect Provider does not necessarily provide information about the issuer (i.e. the OpenID Connect provider) and therefore a prefix MUST be added to the Bearer Token sent in subsequent API calls to protected endpoints. The Bearer Token sent to protected endpoints MUST consist of the authentication method (here oidc), the provider ID and the access token itself. All separated by a forward slash /. The provider ID corresponds to the value specified for id for each provider in the response body of this endpoint. The header in subsequent API calls for a provider with id ms would look as follows: Authorization: Bearer oidc/ms/TOKEN (replace TOKEN with the actual access token received from the OpenID Connect Provider).

Back-ends MAY request user information (including Claims) from the OpenID Connect Userinfo endpoint using the access token (without the prefix described above). Therefore, both openEO client and openEO back-end are relying parties (clients) to the OpenID Connect Provider.

Authorizations:
None

Responses

Response samples

Content type
application/json
{
  • "providers": [
    ]
}

Information about the authenticated user

Lists information about the authenticated user, e.g. the user id. The endpoint MAY return the disk quota available to the user. The endpoint MAY also return links related to user management and the user profile, e.g. where payments are handled or the user profile could be edited. This endpoint MAY be extended to fulfil the specification of the OpenID Connect UserInfo Endpoint.

Authorizations:
Bearer

Responses

Response samples

Content type
application/json
{}

Data Discovery / Access

These endpoints allow to list the collections that are available at the back-end and can be used as data cubes for data processing. It builds on top of:

  • OGC API - Coverages - Part 1
  • STAC API (incl. STAC Data Cube extension)

Basic metadata for all datasets

Lists available collections with at least the required information.

It is strongly RECOMMENDED to keep the response size small by omitting larger optional values from the objects in collections (e.g. the STAC summaries and cube:dimensions properties). To get the full metadata for a collection clients MUST request GET /collections/{collection_id}.

Note: Although it is possible to request public collections without authorization, it is RECOMMENDED that clients (re-)request the collections with the Bearer token once available to also retrieve any private collections.

NOTE: This endpoint may return collections from STAC API / openEO API and OGC API - Coverages. Distinguish them via the stac_version property which is always present for STAC API / openEO API, but not for OGC API - Coverages.

Authorizations:
NoneBearer
query Parameters
limit
integer >= 1
Example: limit=10

This parameter enables pagination for the endpoint and specifies the maximum number of elements that arrays in the top-level object (e.g. collections, processes, batch jobs, secondary services, log entries, etc.) are allowed to contain. The links array MUST NOT be paginated like the resources, but instead contain links related to the paginated resources or the pagination itself (e.g. a link to the next page). If the parameter is not provided or empty, all elements are returned.

Pagination is OPTIONAL: back-ends or clients may not support it. Therefore it MUST be implemented in a way that clients not supporting pagination get all resources regardless. Back-ends not supporting pagination MUST return all resources.

If the response is paginated, the links array MUST be used to communicate the links for browsing the pagination with predefined rel types. See the links array schema for supported rel types. Back-end implementations can, unless specified otherwise, use all kind of pagination techniques, depending on what is supported best by their infrastructure: page-based, offset-based, token-based or something else. The clients SHOULD use whatever is specified in the links with the corresponding rel types.

Responses

Response samples

Content type
application/json
{
  • "collections": [
    ],
  • "links": []
}

Full metadata for a specific dataset

Lists all information about a specific collection specified by the identifier collection_id.

Note: Providing the Bearer token is REQUIRED for private collections.

NOTE: This endpoint may return collections from STAC API / openEO API and OGC API - Coverages. Distinguish them via the stac_version property which is always present for STAC API / openEO API, but not for OGC API - Coverages.

Authorizations:
NoneBearer
path Parameters
collection_id
required
string (collection_id) ^[\w\-\.~\/]+$
Example: Sentinel-2A

Collection identifier

Responses

Response samples

Content type
application/json
{}

Metadata filters for a specific dataset

Lists all supported metadata filters (also called "queryables") for a specific collection.

This endpoint is compatible with endpoint defined in the STAC API extension filter and OGC API - Features - Part 3: Filtering. For a precise definition please follow those specifications.

This endpoints provides a JSON Schema for each queryable that geodatacube users can use in multiple scenarios:

  1. For loading data from the collection, e.g. in the process load_collection.
  2. For filtering items using CQL2 on the /collections/{collection_id}/items endpoint.

Note: Providing the Bearer token is REQUIRED for private collections.

Authorizations:
NoneBearer
path Parameters
collection_id
required
string (collection_id) ^[\w\-\.~\/]+$
Example: Sentinel-2A

Collection identifier

Responses

Response samples

Content type
application/schema+json
{}

Retrieve a coverage

Coverage identified by {collection_id}. Use content negotiation to request required format.

Authorizations:
NoneBearer
path Parameters
collection_id
required
string (collection_id) ^[\w\-\.~\/]+$
Example: Sentinel-2A

Collection identifier

query Parameters
subset
Array of strings

Retrieve only part of the data by slicing or trimming along one or more axis For trimming: {axisAbbrev}({low}:{high}) (preserves dimensionality) An asterisk (*) can be used instead of {low} or {high} to indicate the minimum/maximum value. For slicing: {axisAbbrev}({value}) (reduces dimensionality)

Array of numbers or Array of numbers

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.

datetime
string

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.

properties
string

Select specific data record fields (measured/observed properties) to be returned.

RangeSubsetSpec:   "properties"=field[,fieldName]*
field:              {fieldName}|{fieldIndex}|"*"
fieldName:          {text}
fieldIndex:         {number}

Where:
   {number} is an integer number, and
   {text} is some general ASCII text.

The field name must be one of the id defined in the RangeType DataRecord fields. The field index must be an integer between 0 and the number of fields - 1 defined in the RangeType DataRecord fields. An asterisk indicates to also include subsequent fields.

scale-factor
number

For each axis, the returned coverage will contain the number of original sampled values, divided by the scale-factor.

scale-axes
string

Returns a coverage re-scaled so as to contain {number} times less sample values along the corresponding axisName axis, and all original values along the dimensions of unspecified axes

ScalingSpec:       "scale-axes"=axisName({number})[,axisName({number})]*
axisName:          {NCName}

Where:
   {number} is an integer or floating-point number, and {axisName} is the
   same as one of the axisLabels defined in the DomainSet
scale-size
string

When scale-size is used, the returned coverage will contain exactly the specified number of sample values along each axis which is specified, and the original number of sample values for unspecified axes.

ScalingSpec:       "scale-size"=axisName({number})[,axisName({number})]*
axisName:          {text}

Where:
   {number} is an integer or floating-point number and {axisName}
   is the same as one of the axisLabels defined in the DomainSet
subset-crs
string

crs for the specified subset

bbox-crs
string

crs for the specified bbox

crs
string

reproject the output to the given crs

f
string
Enum: "png" "geotiff" "netcdf" "json" "covjson" "html"

The optional f parameter indicates the output format which the server shall provide as part of the response document. It has preference over the HTTP Accept header.

Responses

Response samples

Content type
{
  • "id": "string",
  • "type": "CoverageByPartitioning",
  • "envelope": {
    },
  • "partitionSet": {
    },
  • "rangeType": {},
  • "metadata": { }
}

Retrieve a coverage's domainset

a coverage's domainset; use content negotiation to request HTML or JSON

Authorizations:
NoneBearer
path Parameters
collection_id
required
string (collection_id) ^[\w\-\.~\/]+$
Example: Sentinel-2A

Collection identifier

query Parameters
subset
Array of strings

Retrieve only part of the data by slicing or trimming along one or more axis For trimming: {axisAbbrev}({low}:{high}) (preserves dimensionality) An asterisk (*) can be used instead of {low} or {high} to indicate the minimum/maximum value. For slicing: {axisAbbrev}({value}) (reduces dimensionality)

Array of numbers or Array of numbers

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.

datetime
string

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.

crs
string

reproject the output to the given crs

bbox-crs
string

crs for the specified bbox

subset-crs
string

crs for the specified subset

f
string
Default: "json"
Enum: "json" "html"

The optional f parameter indicates the output format which the server shall provide as part of the response document. It has preference over the HTTP Accept header.

Responses

Response samples

Content type
{}

Retrieve a coverage's rangetype

a coverage's rangetype; use content negotiation to request HTML or JSON

Authorizations:
NoneBearer
path Parameters
collection_id
required
string (collection_id) ^[\w\-\.~\/]+$
Example: Sentinel-2A

Collection identifier

query Parameters
f
string
Default: "json"
Enum: "json" "html"

The optional f parameter indicates the output format which the server shall provide as part of the response document. It has preference over the HTTP Accept header.

Responses

Response samples

Content type
{}

OGC API - Coverages

Data access through OGC API - Coverages - Part 1 (v0.0.2)

Retrieve a coverage

Coverage identified by {collection_id}. Use content negotiation to request required format.

Authorizations:
NoneBearer
path Parameters
collection_id
required
string (collection_id) ^[\w\-\.~\/]+$
Example: Sentinel-2A

Collection identifier

query Parameters
subset
Array of strings

Retrieve only part of the data by slicing or trimming along one or more axis For trimming: {axisAbbrev}({low}:{high}) (preserves dimensionality) An asterisk (*) can be used instead of {low} or {high} to indicate the minimum/maximum value. For slicing: {axisAbbrev}({value}) (reduces dimensionality)

Array of numbers or Array of numbers

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.

datetime
string

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.

properties
string

Select specific data record fields (measured/observed properties) to be returned.

RangeSubsetSpec:   "properties"=field[,fieldName]*
field:              {fieldName}|{fieldIndex}|"*"
fieldName:          {text}
fieldIndex:         {number}

Where:
   {number} is an integer number, and
   {text} is some general ASCII text.

The field name must be one of the id defined in the RangeType DataRecord fields. The field index must be an integer between 0 and the number of fields - 1 defined in the RangeType DataRecord fields. An asterisk indicates to also include subsequent fields.

scale-factor
number

For each axis, the returned coverage will contain the number of original sampled values, divided by the scale-factor.

scale-axes
string

Returns a coverage re-scaled so as to contain {number} times less sample values along the corresponding axisName axis, and all original values along the dimensions of unspecified axes

ScalingSpec:       "scale-axes"=axisName({number})[,axisName({number})]*
axisName:          {NCName}

Where:
   {number} is an integer or floating-point number, and {axisName} is the
   same as one of the axisLabels defined in the DomainSet
scale-size
string

When scale-size is used, the returned coverage will contain exactly the specified number of sample values along each axis which is specified, and the original number of sample values for unspecified axes.

ScalingSpec:       "scale-size"=axisName({number})[,axisName({number})]*
axisName:          {text}

Where:
   {number} is an integer or floating-point number and {axisName}
   is the same as one of the axisLabels defined in the DomainSet
subset-crs
string

crs for the specified subset

bbox-crs
string

crs for the specified bbox

crs
string

reproject the output to the given crs

f
string
Enum: "png" "geotiff" "netcdf" "json" "covjson" "html"

The optional f parameter indicates the output format which the server shall provide as part of the response document. It has preference over the HTTP Accept header.

Responses

Response samples

Content type
{
  • "id": "string",
  • "type": "CoverageByPartitioning",
  • "envelope": {
    },
  • "partitionSet": {
    },
  • "rangeType": {},
  • "metadata": { }
}

Retrieve a coverage's domainset

a coverage's domainset; use content negotiation to request HTML or JSON

Authorizations:
NoneBearer
path Parameters
collection_id
required
string (collection_id) ^[\w\-\.~\/]+$
Example: Sentinel-2A

Collection identifier

query Parameters
subset
Array of strings

Retrieve only part of the data by slicing or trimming along one or more axis For trimming: {axisAbbrev}({low}:{high}) (preserves dimensionality) An asterisk (*) can be used instead of {low} or {high} to indicate the minimum/maximum value. For slicing: {axisAbbrev}({value}) (reduces dimensionality)

Array of numbers or Array of numbers

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.

datetime
string

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.

crs
string

reproject the output to the given crs

bbox-crs
string

crs for the specified bbox

subset-crs
string

crs for the specified subset

f
string
Default: "json"
Enum: "json" "html"

The optional f parameter indicates the output format which the server shall provide as part of the response document. It has preference over the HTTP Accept header.

Responses

Response samples

Content type
{}

Retrieve a coverage's rangetype

a coverage's rangetype; use content negotiation to request HTML or JSON

Authorizations:
NoneBearer
path Parameters
collection_id
required
string (collection_id) ^[\w\-\.~\/]+$
Example: Sentinel-2A

Collection identifier

query Parameters
f
string
Default: "json"
Enum: "json" "html"

The optional f parameter indicates the output format which the server shall provide as part of the response document. It has preference over the HTTP Accept header.

Responses

Response samples

Content type
{}

OGC API - Features / STAC API

OPTIONAL. Data access through OGC API - Features - Part 1 (v1.0.0) and STAC API (v1.0.0)

Metadata filters for a specific dataset

Lists all supported metadata filters (also called "queryables") for a specific collection.

This endpoint is compatible with endpoint defined in the STAC API extension filter and OGC API - Features - Part 3: Filtering. For a precise definition please follow those specifications.

This endpoints provides a JSON Schema for each queryable that geodatacube users can use in multiple scenarios:

  1. For loading data from the collection, e.g. in the process load_collection.
  2. For filtering items using CQL2 on the /collections/{collection_id}/items endpoint.

Note: Providing the Bearer token is REQUIRED for private collections.

Authorizations:
NoneBearer
path Parameters
collection_id
required
string (collection_id) ^[\w\-\.~\/]+$
Example: Sentinel-2A

Collection identifier

Responses

Response samples

Content type
application/schema+json
{}

Fetch Features / Items

Fetch features of the feature collection with id collection_id.

Every feature in a dataset belongs to a collection. A dataset may consist of multiple feature collections. A feature collection is often a collection of features of a similar type, based on a common schema.

Authorizations:
NoneBearer
path Parameters
collection_id
required
string (collection_id) ^[\w\-\.~\/]+$
Example: Sentinel-2A

Collection identifier

query Parameters
limit
integer >= 1
Example: limit=10

This parameter enables pagination for the endpoint and specifies the maximum number of elements that arrays in the top-level object (e.g. collections, processes, batch jobs, secondary services, log entries, etc.) are allowed to contain. The links array MUST NOT be paginated like the resources, but instead contain links related to the paginated resources or the pagination itself (e.g. a link to the next page). If the parameter is not provided or empty, all elements are returned.

Pagination is OPTIONAL: back-ends or clients may not support it. Therefore it MUST be implemented in a way that clients not supporting pagination get all resources regardless. Back-ends not supporting pagination MUST return all resources.

If the response is paginated, the links array MUST be used to communicate the links for browsing the pagination with predefined rel types. See the links array schema for supported rel types. Back-end implementations can, unless specified otherwise, use all kind of pagination techniques, depending on what is supported best by their infrastructure: page-based, offset-based, token-based or something else. The clients SHOULD use whatever is specified in the links with the corresponding rel types.

Array of numbers or Array of numbers

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.

datetime
string

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.

Responses

Response samples

Content type
application/geo+json
{}

Fetch a Feature / Item

Fetch the feature with id feature_id in the feature collection with id collection_id.

Authorizations:
NoneBearer
path Parameters
collection_id
required
string (collection_id) ^[\w\-\.~\/]+$
Example: Sentinel-2A

Collection identifier

feature_id
required
string

local identifier of a feature

Responses

Response samples

Content type
application/geo+json
{}

Process Discovery

OPTIONAL. These endpoints allow to list the predefined processes that are available at the back-end. To list user-defined processes see 'openEO - User-Defined Processes'.

Supported predefined processes

Lists all predefined processes and returns detailed process descriptions, including parameters and return values.

NOTE: This endpoint may return processes from openEO and OGC API - Processes. Distinguish them via the version property (OGC API) and the parameters / returns (openEO) properties.

Authorizations:
NoneBearer
query Parameters
limit
integer >= 1
Example: limit=10

This parameter enables pagination for the endpoint and specifies the maximum number of elements that arrays in the top-level object (e.g. collections, processes, batch jobs, secondary services, log entries, etc.) are allowed to contain. The links array MUST NOT be paginated like the resources, but instead contain links related to the paginated resources or the pagination itself (e.g. a link to the next page). If the parameter is not provided or empty, all elements are returned.

Pagination is OPTIONAL: back-ends or clients may not support it. Therefore it MUST be implemented in a way that clients not supporting pagination get all resources regardless. Back-ends not supporting pagination MUST return all resources.

If the response is paginated, the links array MUST be used to communicate the links for browsing the pagination with predefined rel types. See the links array schema for supported rel types. Back-end implementations can, unless specified otherwise, use all kind of pagination techniques, depending on what is supported best by their infrastructure: page-based, offset-based, token-based or something else. The clients SHOULD use whatever is specified in the links with the corresponding rel types.

Responses

Response samples

Content type
application/json
{
  • "processes": [
    ],
  • "links": []
}

Retrieve an OGC API process description

The process description contains information about inputs and outputs and a link to the execution-endpoint for the process. The Core does not mandate the use of a specific process description to specify the interface of a process. That said, the Core requirements class makes the following recommendation:

Implementations SHOULD consider supporting the OGC process description.

For more information, see Section 7.10.

Authorizations:
NoneBearer
path Parameters
processID
required
string

ID of the OGC process

Responses

Response samples

Content type
application/json
{
  • "title": "string",
  • "description": "string",
  • "keywords": [
    ],
  • "metadata": [
    ],
  • "additionalParameters": {
    },
  • "id": "string",
  • "version": "string",
  • "jobControlOptions": [
    ],
  • "outputTransmission": [
    ],
  • "links": [],
  • "inputs": {
    },
  • "outputs": {
    }
}

List all user-defined openEO processes

Lists all user-defined processes (process graphs) of the authenticated user that are stored at the back-end.

It is strongly RECOMMENDED to keep the response size small by omitting larger optional values from the objects in processes (e.g. the exceptions, examples and links properties). To get the full metadata for a user-defined process clients MUST request GET /process_graphs/{process_graph_id}.

Authorizations:
Bearer
query Parameters
limit
integer >= 1
Example: limit=10

This parameter enables pagination for the endpoint and specifies the maximum number of elements that arrays in the top-level object (e.g. collections, processes, batch jobs, secondary services, log entries, etc.) are allowed to contain. The links array MUST NOT be paginated like the resources, but instead contain links related to the paginated resources or the pagination itself (e.g. a link to the next page). If the parameter is not provided or empty, all elements are returned.

Pagination is OPTIONAL: back-ends or clients may not support it. Therefore it MUST be implemented in a way that clients not supporting pagination get all resources regardless. Back-ends not supporting pagination MUST return all resources.

If the response is paginated, the links array MUST be used to communicate the links for browsing the pagination with predefined rel types. See the links array schema for supported rel types. Back-end implementations can, unless specified otherwise, use all kind of pagination techniques, depending on what is supported best by their infrastructure: page-based, offset-based, token-based or something else. The clients SHOULD use whatever is specified in the links with the corresponding rel types.

Responses

Response samples

Content type
application/json
{
  • "processes": [
    ],
  • "links": [ ]
}

OGC API - Processes

OPTIONAL. Data processing through OGC API - Processes - Part 1 (v1.0.0)

Supported predefined processes

Lists all predefined processes and returns detailed process descriptions, including parameters and return values.

NOTE: This endpoint may return processes from openEO and OGC API - Processes. Distinguish them via the version property (OGC API) and the parameters / returns (openEO) properties.

Authorizations:
NoneBearer
query Parameters
limit
integer >= 1
Example: limit=10

This parameter enables pagination for the endpoint and specifies the maximum number of elements that arrays in the top-level object (e.g. collections, processes, batch jobs, secondary services, log entries, etc.) are allowed to contain. The links array MUST NOT be paginated like the resources, but instead contain links related to the paginated resources or the pagination itself (e.g. a link to the next page). If the parameter is not provided or empty, all elements are returned.

Pagination is OPTIONAL: back-ends or clients may not support it. Therefore it MUST be implemented in a way that clients not supporting pagination get all resources regardless. Back-ends not supporting pagination MUST return all resources.

If the response is paginated, the links array MUST be used to communicate the links for browsing the pagination with predefined rel types. See the links array schema for supported rel types. Back-end implementations can, unless specified otherwise, use all kind of pagination techniques, depending on what is supported best by their infrastructure: page-based, offset-based, token-based or something else. The clients SHOULD use whatever is specified in the links with the corresponding rel types.

Responses

Response samples

Content type
application/json
{
  • "processes": [
    ],
  • "links": []
}

Retrieve an OGC API process description

The process description contains information about inputs and outputs and a link to the execution-endpoint for the process. The Core does not mandate the use of a specific process description to specify the interface of a process. That said, the Core requirements class makes the following recommendation:

Implementations SHOULD consider supporting the OGC process description.

For more information, see Section 7.10.

Authorizations:
NoneBearer
path Parameters
processID
required
string

ID of the OGC process

Responses

Response samples

Content type
application/json
{
  • "title": "string",
  • "description": "string",
  • "keywords": [
    ],
  • "metadata": [
    ],
  • "additionalParameters": {
    },
  • "id": "string",
  • "version": "string",
  • "jobControlOptions": [
    ],
  • "outputTransmission": [
    ],
  • "links": [],
  • "inputs": {
    },
  • "outputs": {
    }
}

OGC API / Execute a process

Create a new job.

For more information, see Section 7.11.

Authorizations:
Bearer
path Parameters
processID
required
string

ID of the OGC process

Request Body schema: application/json

Mandatory execute request JSON

object
object
response
string
Default: "raw"
Enum: "raw" "document"
object (ogc_subscriber)

Optional URIs for callbacks for this job.

Support for this parameter is not required and the parameter may be removed from the API definition, if conformance class 'callback' is not listed in the conformance declaration under /conformance.

Responses

Callbacks

Request samples

Content type
application/json
{
  • "inputs": {
    },
  • "outputs": {
    },
  • "response": "raw",
  • "subscriber": {}
}

Response samples

Content type
application/json
{
  • "processID": "string",
  • "type": "process",
  • "jobID": "string",
  • "status": "accepted",
  • "message": "string",
  • "created": "2019-08-24T14:15:22Z",
  • "started": "2019-08-24T14:15:22Z",
  • "finished": "2019-08-24T14:15:22Z",
  • "updated": "2019-08-24T14:15:22Z",
  • "progress": 100,
  • "links": []
}

Callback payload samples

Callback
POST: {$request.body#/subscriber/successUri}
Content type
application/json
{
  • "property1": "string",
  • "property2": "string"
}

List all batch jobs

Lists all batch jobs submitted by a user.

It is strongly RECOMMENDED to keep the response size small by omitting all optional non-scalar values (i.e. arrays and objects) from objects in jobs. To get the full metadata for a job clients MUST request GET /jobs/{job_id}.

NOTE: This endpoint may return jobs from openEO and OGC API - Processes. Distinguish them via the jobID (OGC API) and the id (openEO) property.

Authorizations:
Bearer
query Parameters
limit
integer >= 1
Example: limit=10

This parameter enables pagination for the endpoint and specifies the maximum number of elements that arrays in the top-level object (e.g. collections, processes, batch jobs, secondary services, log entries, etc.) are allowed to contain. The links array MUST NOT be paginated like the resources, but instead contain links related to the paginated resources or the pagination itself (e.g. a link to the next page). If the parameter is not provided or empty, all elements are returned.

Pagination is OPTIONAL: back-ends or clients may not support it. Therefore it MUST be implemented in a way that clients not supporting pagination get all resources regardless. Back-ends not supporting pagination MUST return all resources.

If the response is paginated, the links array MUST be used to communicate the links for browsing the pagination with predefined rel types. See the links array schema for supported rel types. Back-end implementations can, unless specified otherwise, use all kind of pagination techniques, depending on what is supported best by their infrastructure: page-based, offset-based, token-based or something else. The clients SHOULD use whatever is specified in the links with the corresponding rel types.

Responses

Response samples

Content type
application/json
{
  • "jobs": [
    ],
  • "links": []
}

Full metadata for a batch job

Lists information about a batch job.

NOTE: This endpoint may return a job from openEO or OGC API - Processes. Distinguish them via the jobID (OGC API) and the id (openEO) property.

Authorizations:
Bearer
path Parameters
job_id
required
string (job_id) ^[\w\-\.~]+$
Example: a3cca2b2aa1e3b5b

Identifier of the batch job.

Responses

Response samples

Content type
application/json
Example
{
  • "id": "a3cca2b2aa1e3b5b",
  • "title": "NDVI based on Sentinel 2",
  • "description": "Deriving minimum NDVI measurements over pixel time series of Sentinel 2",
  • "process": {
    },
  • "status": "running",
  • "progress": 75.5,
  • "created": "2017-01-01T09:32:12Z",
  • "updated": "2017-01-01T09:36:18Z",
  • "usage": {
    },
  • "log_level": "warning",
  • "links": []
}

Delete a batch job

Deletes all data related to this job. Computations are stopped and computed results are deleted. This job won't generate additional costs for processing.

Authorizations:
Bearer
path Parameters
job_id
required
string (job_id) ^[\w\-\.~]+$
Example: a3cca2b2aa1e3b5b

Identifier of the batch job.

Responses

Response samples

Content type
application/json
{
  • "processID": "string",
  • "type": "process",
  • "jobID": "string",
  • "status": "accepted",
  • "message": "string",
  • "created": "2019-08-24T14:15:22Z",
  • "started": "2019-08-24T14:15:22Z",
  • "finished": "2019-08-24T14:15:22Z",
  • "updated": "2019-08-24T14:15:22Z",
  • "progress": 100,
  • "links": []
}

List batch job results

NOTE: This endpoint may return a job from openEO or OGC API - Processes. Distinguish them via the assets property which is always present for openEO, but not for OGC API - Processes.

OGC API - Processes

Lists available results of a job. In case of a failure, lists exceptions instead.

For more information, see Section 7.13.

openEO

Lists signed URLs pointing to the processed files, usually after the batch job has finished. Back-ends may also point to intermediate results after the job has stopped due to an error or if the partial parameter has been set.

The response includes additional metadata. It is a valid STAC Item (if it has spatial and temporal references included) or a valid STAC Collection. The assets to download are in both cases available in the property assets and have the same structure. All additional metadata is not strictly required to download the files, but are helpful for users to understand the data.

STAC Collections can either (1) add all assets as collection-level assets or (2) link to STAC Catalogs and STAC Items with signed URLs, which will provide a full STAC catalog structure a client has to go through. Option 2 is overall the better architectural choice and allows a fine-grained description of the processed data.

Clients are RECOMMENDED to store this response and all potential sub-catalogs and items with the assets so that the downloaded data is then a self-contained STAC catalog user could publish easily with all the data and metadata.

URL signing is a way to protect files from unauthorized access with a key in the URL instead of HTTP header based authorization. The URL signing key is similar to a password and its inclusion in the URL allows to download files using simple GET requests supported by a wide range of programs, e.g. web browsers or download managers. Back-ends are responsible to generate the URL signing keys and to manage their appropriate expiration. The back-end MAY indicate an expiration time by setting the expires property in the reponse. Requesting this endpoint SHOULD always return non-expired URLs. Signed URLs that were generated for a previous request and already expired SHOULD NOT be reused, but regenerated with new expiration time. Signed URLs that expired MAY return an error.

It is strongly recommended to add a link with relation type canonical to the STAC Item or STAC Collection (see the links property for details).

If processing has not finished yet and the partial parameter is not set to true requests to this endpoint MUST be rejected an error.

Authorizations:
Bearer
path Parameters
job_id
required
string (job_id) ^[\w\-\.~]+$
Example: a3cca2b2aa1e3b5b

Identifier of the batch job.

query Parameters
partial
boolean
Default: false

openEO only: If set to true, the results endpoint returns incomplete results while still running.

Responses

Response samples

Content type
Example
{
  • "property1": "string",
  • "property2": "string"
}

openEO

OPTIONAL. Data processing through openEO (v1.2.0)

Supported file formats

Lists supported input and output file formats. Input file formats specify which file a back-end can read from. Output file formats specify which file a back-end can write to.

The response to this request is an object listing all available input and output file formats separately with their parameters and additional data. This endpoint does not include the supported secondary web services.

Note: Format names and parameters MUST be fully aligned with the GDAL codes if available, see GDAL Raster Formats and OGR Vector Formats. It is OPTIONAL to support all output format parameters supported by GDAL. Some file formats not available through GDAL may be defined centrally for the geodatacube. Custom file formats or parameters MAY be defined.

The format descriptions must describe how the file formats relate to data cubes. Input file formats must describe how the files have to be structured to be transformed into data cubes. Output file formats must describe how the data cubes are stored at the back-end and how the resulting file structure looks like.

Back-ends MUST NOT support aliases, for example it is not allowed to support geotiff instead of gtiff. Nevertheless, geodatacube clients MAY translate user input input for convenience (e.g. translate geotiff to gtiff). Also, for a better user experience the back-end can specify a title.

Format names MUST be accepted in a case insensitive manner throughout the API.

Authorizations:
NoneBearer

Responses

Response samples

Content type
application/json
{
  • "output": {
    },
  • "input": {
    }
}

Supported predefined processes

Lists all predefined processes and returns detailed process descriptions, including parameters and return values.

NOTE: This endpoint may return processes from openEO and OGC API - Processes. Distinguish them via the version property (OGC API) and the parameters / returns (openEO) properties.

Authorizations:
NoneBearer
query Parameters
limit
integer >= 1
Example: limit=10

This parameter enables pagination for the endpoint and specifies the maximum number of elements that arrays in the top-level object (e.g. collections, processes, batch jobs, secondary services, log entries, etc.) are allowed to contain. The links array MUST NOT be paginated like the resources, but instead contain links related to the paginated resources or the pagination itself (e.g. a link to the next page). If the parameter is not provided or empty, all elements are returned.

Pagination is OPTIONAL: back-ends or clients may not support it. Therefore it MUST be implemented in a way that clients not supporting pagination get all resources regardless. Back-ends not supporting pagination MUST return all resources.

If the response is paginated, the links array MUST be used to communicate the links for browsing the pagination with predefined rel types. See the links array schema for supported rel types. Back-end implementations can, unless specified otherwise, use all kind of pagination techniques, depending on what is supported best by their infrastructure: page-based, offset-based, token-based or something else. The clients SHOULD use whatever is specified in the links with the corresponding rel types.

Responses

Response samples

Content type
application/json
{
  • "processes": [
    ],
  • "links": []
}

Process and download data synchronously

Executes a user-defined process directly (synchronously) and the result will be downloaded in the format specified in the process graph. This endpoint can be used to generate small previews or test user-defined processes before starting a batch job. Timeouts on either client- or server-side are to be expected for complex computations. Back-ends MAY send the an error immediately if the computation is expected to time out. Otherwise requests MAY time-out after a certain amount of time by sending an error.

Authorizations:
Bearer
Request Body schema: application/json

Specifies the job details, e.g. the user-defined process and billing details.

required
object (Process Graph with metadata)

A process graph, optionally enriched with process metadata.

log_level
string (min_log_level_default)
Default: "info"
Enum: "error" "warning" "info" "debug"

The minimum severity level for log entries that the back-end stores for the processing request.

The order of the levels is as follows (from low to high severity): debug, info, warning, error. That means if warning is set, the back-end will only store log entries with the level warning and error.

The default minimum log level is info. Users need to specifically set this property to debug to get all log entries. It is RECOMMENDED that users set the level at least to "warning" in production workflows.

property name*
additional property
any

You can add additional back-end specific properties here.

Responses

Request samples

Content type
application/json
{
  • "process": {
    },
  • "log_level": "warning",
  • "property1": null,
  • "property2": null
}

Response samples

Content type
application/json
{}

List all batch jobs

Lists all batch jobs submitted by a user.

It is strongly RECOMMENDED to keep the response size small by omitting all optional non-scalar values (i.e. arrays and objects) from objects in jobs. To get the full metadata for a job clients MUST request GET /jobs/{job_id}.

NOTE: This endpoint may return jobs from openEO and OGC API - Processes. Distinguish them via the jobID (OGC API) and the id (openEO) property.

Authorizations:
Bearer
query Parameters
limit
integer >= 1
Example: limit=10

This parameter enables pagination for the endpoint and specifies the maximum number of elements that arrays in the top-level object (e.g. collections, processes, batch jobs, secondary services, log entries, etc.) are allowed to contain. The links array MUST NOT be paginated like the resources, but instead contain links related to the paginated resources or the pagination itself (e.g. a link to the next page). If the parameter is not provided or empty, all elements are returned.

Pagination is OPTIONAL: back-ends or clients may not support it. Therefore it MUST be implemented in a way that clients not supporting pagination get all resources regardless. Back-ends not supporting pagination MUST return all resources.

If the response is paginated, the links array MUST be used to communicate the links for browsing the pagination with predefined rel types. See the links array schema for supported rel types. Back-end implementations can, unless specified otherwise, use all kind of pagination techniques, depending on what is supported best by their infrastructure: page-based, offset-based, token-based or something else. The clients SHOULD use whatever is specified in the links with the corresponding rel types.

Responses

Response samples

Content type
application/json
{
  • "jobs": [
    ],
  • "links": []
}

Create a new batch job

Creates a new batch processing task (job) from one or more (chained) processes at the back-end.

Processing the data doesn't start yet. The job status gets initialized as created by default.

Authorizations:
Bearer
Request Body schema: application/json

Specifies the job details, e.g. the user-defined process and billing details.

title
string or null (eo_title)

A short description to easily distinguish entities.

description
string or null <commonmark> (eo_description)

Detailed multi-line description to explain the entity.

CommonMark 0.29 syntax MAY be used for rich text representation.

required
object (Process Graph with metadata)

A process graph, optionally enriched with process metadata.

log_level
string (min_log_level_default)
Default: "info"
Enum: "error" "warning" "info" "debug"

The minimum severity level for log entries that the back-end stores for the processing request.

The order of the levels is as follows (from low to high severity): debug, info, warning, error. That means if warning is set, the back-end will only store log entries with the level warning and error.

The default minimum log level is info. Users need to specifically set this property to debug to get all log entries. It is RECOMMENDED that users set the level at least to "warning" in production workflows.

property name*
additional property
any

You can add additional back-end specific properties here.

Responses

Request samples

Content type
application/json
{
  • "title": "NDVI based on Sentinel 2",
  • "description": "Deriving minimum NDVI measurements over pixel time series of Sentinel 2",
  • "process": {
    },
  • "log_level": "warning",
  • "property1": null,
  • "property2": null
}

Response samples

Content type
application/json
{}

Modify a batch job

Modifies an existing job at the back-end, but maintains the identifier. Changes can be grouped in a single request.

The job status does not change.

Jobs can only be modified when the job is not queued and not running. Otherwise, requests to this endpoint MUST be rejected with an error.

Authorizations:
Bearer
path Parameters
job_id
required
string (job_id) ^[\w\-\.~]+$
Example: a3cca2b2aa1e3b5b

Identifier of the batch job.

Request Body schema: application/json

Specifies the job details to update.

title
string or null (eo_title)

A short description to easily distinguish entities.

description
string or null <commonmark> (eo_description)

Detailed multi-line description to explain the entity.

CommonMark 0.29 syntax MAY be used for rich text representation.

object (Process Graph with metadata)

A process graph, optionally enriched with process metadata.

log_level
string (min_log_level_update)
Enum: "error" "warning" "info" "debug"

Updates the minimum severity level for log entries that the back-end stores for the processing requests.

The back-end doesn't need to update existing log entries.

Responses