API docs by Redocly

geodatacube API (1.0.0-beta)

Download OpenAPI specification:Download

OGC Testbed 19: info@ogc.org URL: https://www.ogc.org/initiatives/t-19/ License: Apache 2.0

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

Response samples

Content type
application/json
{}

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

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"
}

Response samples

Content type
application/json
{}

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": []
}

Logs for a batch job

Lists log entries for the batch job, usually for debugging purposes.

Back-ends can log any information that may be relevant for a user at any stage (status) of the batch job. Users can log information during data processing using respective processes such as inspect.

If requested consecutively, it is RECOMMENDED that clients use the offset parameter to get only the entries they have not received yet.

While pagination itself is OPTIONAL, the offset parameter is REQUIRED to be implemented by back-ends.

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

Identifier of the batch job.

query Parameters
offset
string
Example: offset=log1234

The last identifier (property id of a log entry) the client has received. If provided, the back-ends only sends the entries that occurred after the specified identifier. If not provided or empty, start with the first entry.

level
string
Default: "info"
Enum: "error" "warning" "info" "debug"
Example: level=error

The minimum severity level for log entries that the back-end returns.

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 return log entries with the level warning and error.

The default minimum log level is debug, which returns all log levels.

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
{
  • "level": "error",
  • "logs": [
    ],
  • "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"
}

Start processing a batch job

Adds a batch job to the processing queue to compute the results.

The result will be stored in the format specified in the process. To specify the format use a process such as save_result.

The job status is set to queued, if processing doesn't start instantly. The same applies if the job status is canceled, finished, or error, which restarts the job and discards previous results if the back-end doesn't reject the request with an error. Clients SHOULD warn users and ask for confirmation if results may get discarded.

  • Once the processing starts the status is set to running.
  • Once the data is available to download the status is set to finished.
  • Whenever an error occurs during processing, the status MUST be set to error.

This endpoint has no effect if the job status is already queued or running. In particular, it doesn't restart a running job. To restart a queued or running job, processing MUST have been canceled before.

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
{}

Cancel processing a batch job

Cancels all related computations for this job at the back-end. It will stop generating additional costs for processing.

A subset of processed results may be available for downloading depending on the state of the job at the time it was canceled.

Results MUST NOT be deleted until the job processing is started again or the job is completely deleted through a request to DELETE /jobs/{job_id}.

This endpoint only has an effect if the job status is queued or running.

The job status is set to canceled if the status was running beforehand and partial or preliminary results are available to be downloaded. Otherwise the status is set to created.

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
{}

openEO - User-Defined Processes

OPTIONAL. These endpoints allow to store and manage user-defined processes with their process graphs at the back-end.

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": [ ]
}

Full metadata for a user-defined process

Lists all information about a user-defined process, including its process graph.

Authorizations:
Bearer
path Parameters
process_graph_id
required
string (process_id) ^\w+$
Example: ndvi

Per-user unique identifier for a user-defined process.

Responses

Response samples

Content type
application/json

A user-defined process that computes the EVI.

{
  • "id": "evi",
  • "summary": "Enhanced Vegetation Index",
  • "description": "Computes the Enhanced Vegetation Index (EVI). It is computed with the following formula: `2.5 * (NIR - RED) / (1 + NIR + 6*RED + -7.5*BLUE)`.",
  • "parameters": [
    ],
  • "returns": {
    },
  • "process_graph": {
    }
}

Store a user-defined process

Stores a provided user-defined process with process graph that can be reused in other processes.

If a process with the specified process_graph_id exists, the process is fully replaced. The id can't be changed for existing user-defined processes. The id MUST be unique across its namespace.

Partially updating user-defined processes is not supported.

To simplify exchanging user-defined processes, the property id can be part of the request body. If the values don't match, the value for id gets replaced with the value from the process_graph_id parameter in the path.

Authorizations:
Bearer
path Parameters
process_graph_id
required
string (process_id) ^\w+$
Example: ndvi

Per-user unique identifier for a user-defined process.

Request Body schema: application/json

Specifies the process graph with its meta data.

id
string or null^\w+$

The identifier for the process. It MUST be unique across its namespace (e.g. predefined processes or user-defined processes).

Clients SHOULD warn the user if a user-defined process is added with the same identifier as one of the predefined process.

summary
string or null

A short summary of what the process does.

description
string or null <commonmark>

Detailed description to explain the entity.

CommonMark 0.29 syntax MAY be used for rich text representation. In addition to the CommonMark syntax, clients can convert process IDs that are formatted as in the following example into links instead of code blocks: ``process_id()``

Array of objects or null (Process Parameter)

A list of parameters.

The order in the array corresponds to the parameter order to be used in clients that don't support named parameters.

Note: Specifying an empty array is different from (if allowed) null or the property being absent. An empty array means the process has no parameters. null / property absent means that the parameters are unknown as the user has not specified them. There could still be parameters in the process graph, if one is specified.

object or null (Process Return Value)

Description of the data that is returned by this process.

categories
Array of strings (process_categories)

A list of categories.

deprecated
boolean (deprecated)
Default: false

Declares that the specified entity is deprecated with the potential to be removed in any of the next versions. It should be transitioned out of usage as soon as possible and users should refrain from using it in new implementations.

experimental
boolean (experimental)
Default: false

Declares that the specified entity is experimental, which means that it is likely to change or may produce unpredictable behaviour. Users should refrain from using it in production, but still feel encouraged to try it out and give feedback.

object (Process Exceptions)

Declares exceptions (errors) that might occur during execution of this process. This list is just for informative purposes and may be incomplete. This list MUST only contain exceptions that stop the execution of a process and MUST NOT contain warnings, notices or debugging messages. It is meant to primarily contain errors that have been caused by the user. It is RECOMMENDED that exceptions are referred to and explained in process or parameter descriptions.

The keys define the error code and MUST match the following pattern: ^\w+$.

Array of objects (Process Example)

Examples, may be used for unit tests.

Array of objects (Link)

Links related to this process, e.g. additional external documentation.

It is RECOMMENDED to provide links with the following rel (relation) types:

  1. latest-version: If a process has been marked as deprecated, a link SHOULD point to the preferred version of the process. The relation types predecessor-version (link to older version) and successor-version (link to newer version) can also be used to show the relation between versions.

  2. example: Links to examples of other processes that use this process.

  3. cite-as: For all DOIs associated with the process, the respective DOI links SHOULD be added.

For additional relation types see also the lists of common relation types.

required
object (Process Graph)

A process graph defines a graph-like structure as a connected set of executable processes. Each key is a unique identifier (node ID) that is used to refer to the process in the graph.

Responses

Request samples

Content type
application/json

A user-defined process that computes the EVI.

{
  • "id": "evi",
  • "summary": "Enhanced Vegetation Index",
  • "description": "Computes the Enhanced Vegetation Index (EVI). It is computed with the following formula: `2.5 * (NIR - RED) / (1 + NIR + 6*RED + -7.5*BLUE)`.",
  • "parameters": [
    ],
  • "returns": {
    },
  • "process_graph": {
    }
}

Response samples

Content type
application/json
{}

Delete a user-defined process

Deletes the data related to this user-defined process, including its process graph.

Does NOT delete jobs or services that reference this user-defined process.

Authorizations:
Bearer
path Parameters
process_graph_id
required
string (process_id) ^\w+$
Example: ndvi

Per-user unique identifier for a user-defined process.

Responses

Response samples

Content type
application/json
{}

openEO - Secondary Services (OGC APIs)

OPTIONAL. On-demand access to data using other web service protocols (e.g., OGC API - Tiles / Maps).

Supported secondary web service protocols

Lists supported secondary web service protocols such as OGC WMS, OGC WCS, OGC API - Features or XYZ tiles. The response is an object of all available secondary web service protocols with their supported configuration settings and expected process parameters.

  • The configuration settings for the service SHOULD be defined upon creation of a service and the service will be set up accordingly.
  • The process parameters SHOULD be referenced (with a from_parameter reference) in the user-defined process that is used to compute web service results. The appropriate arguments MUST be provided to the user-defined process, usually at runtime from the context of the web service, For example, a map service such as a WMS would need to inject the spatial extent into the user-defined process so that the back-end can compute the corresponding tile correctly.

To improve interoperability between back-ends common names for the services SHOULD be used, e.g. the abbreviations used in the official OGC Schema Repository for the respective services.

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

Authorizations:
NoneBearer

Responses

Response samples

Content type
application/json
{
  • "WMS": {
    },
  • "OGCAPI-FEATURES": {}
}

List all web services

Lists all secondary web services 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 services (i.e. the process, configuration and attributes properties). To get the full metadata for a secondary web service clients MUST request GET /services/{service_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
{
  • "services": [
    ],
  • "links": []
}

Publish a new service

Creates a new secondary web service such as a OGC WMS, OGC WCS, OGC API - Features or XYZ tiles.

The secondary web service SHOULD process the underlying data on demand, based on process parameters provided to the user-defined process (through from_parameter references) at run-time, for example for the spatial/temporal extent, resolution, etc. The available process parameters are specified per service type at GET /service_types.

Note: Costs incurred by shared secondary web services are usually paid by the owner, but this depends on the service type and whether it supports charging fees or not.

Authorizations:
Bearer
Request Body schema: application/json

The base data for the secondary web service to create

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.

type
required
string (service_type)

Definition of the service type to access result data. All available service types can be retrieved via GET /service_types. Service types MUST be accepted in a case insensitive manner.

enabled
boolean
Default: true

Describes whether a secondary web service is responding to requests (true) or not (false). Disabled services don't produce any costs.

configuration
object (Service Configuration)

Map of configuration settings, i.e. the setting names supported by the secondary web service combined with actual values. See GET /service_types for supported configuration settings. For example, this could specify the required version of the service, visualization details or any other service dependant configuration.

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": {
    },
  • "type": "wms",
  • "enabled": true,
  • "configuration": {
    },
  • "log_level": "warning",
  • "property1": null,
  • "property2": null
}

Response samples

Content type
application/json
{}

Modify a service

Modifies an existing secondary web service at the back-end, but maintain the identifier. Changes can be grouped in a single request.

User have to create a new service to change the service type.

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

Identifier of the secondary web service.

Request Body schema: application/json

The data to change for the specified secondary web service.

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.

enabled
boolean (service_enabled)

Describes whether a secondary web service is responding to requests (true) or not (false). Disabled services don't produce any costs.

configuration
object (Service Configuration)

Map of configuration settings, i.e. the setting names supported by the secondary web service combined with actual values. See GET /service_types for supported configuration settings. For example, this could specify the required version of the service, visualization details or any other service dependant configuration.

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

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": {
    },
  • "enabled": true,
  • "configuration": {
    },
  • "log_level": "warning"
}

Response samples

Content type
application/json
{}

Full metadata for a service

Lists all information about a secondary web service.

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

Identifier of the secondary web service.

Responses

Response samples

Content type
application/json
{
  • "id": "wms-a3cca9",
  • "title": "NDVI based on Sentinel 2",
  • "description": "Deriving minimum NDVI measurements over pixel time series of Sentinel 2",
  • "url": "https://geodatacube.example/wms/wms-a3cca9",
  • "type": "wms",
  • "enabled": true,
  • "process": {
    },
  • "configuration": {
    },
  • "attributes": {
    },
  • "created": "2017-01-01T09:32:12Z",
  • "usage": {
    },
  • "log_level": "warning"
}

Delete a service

Deletes all data related to this secondary web service. Computations are stopped, computed results are deleted and access to this is not possible any more. This service won't generate additional costs.

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

Identifier of the secondary web service.

Responses

Response samples

Content type
application/json
{}

Logs for a secondary service

Lists log entries for the secondary service, usually for debugging purposes. Back-ends can log any information that may be relevant for a user. Users can log information during data processing using respective processes such as inspect. If requested consecutively while the secondary service is enabled, it is RECOMMENDED that clients use the offset parameter to get only the entries they have not received yet. While pagination itself is OPTIONAL, the offset parameter is REQUIRED to be implemented by back-ends.

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

Identifier of the secondary web service.

query Parameters
offset
string
Example: offset=log1234

The last identifier (property id of a log entry) the client has received. If provided, the back-ends only sends the entries that occurred after the specified identifier. If not provided or empty, start with the first entry.

level
string
Default: "info"
Enum: "error" "warning" "info" "debug"
Example: level=error

The minimum severity level for log entries that the back-end returns.

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 return log entries with the level warning and error.

The default minimum log level is debug, which returns all log levels.

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
{
  • "level": "error",
  • "logs": [
    ],
  • "links": []
}