Download OpenAPI specification:Download
The openEO API specification for interoperable cloud-based processing of large Earth observation datasets.
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 follow their respective casing conventions, e.g. Content-Type
or OpenEO-Costs
, despite being case-insensitive according to RFC 7230.
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 uses JSON for request and response bodies whenever feasible. Services use JSON as the default encoding. Other encodings can be requested using Content Negotiation. Clients and servers MUST NOT rely on the order in which properties appears in JSON. Collections usually don't include nested JSON objects if those information can be requested from the individual resources.
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:
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.
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.
about
: A resource that is related or further explains the resource, e.g. a user guide.
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.
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://example.openeo.org/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 either one of the standardized textual openEO error codes or a proprietary 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.
The openEO API usually uses the following HTTP status codes for successful requests:
Location
header to the newly created resource without a response body.The openEO 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 MUST use 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.
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 openEO error code in addition to the most used status codes mentioned here. Responding with openEO error codes 400 and 500 SHOULD be avoided in favor of any more specific standardized or proprietary openEO error code.
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.
The openEO API offers two forms of authentication by default:
GET /credentials/oidc
GET /credentials/basic
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.
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`." |
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
openEO-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.
All endpoints must respond to the OPTIONS
HTTP method. This is a response for the preflight requests made by the browsers. It needs to respond with a status code of 204
and send the HTTP headers shown in the table below. No body needs to be provided.
Name | Description | Example |
---|---|---|
Access-Control-Allow-Origin | Allowed origin for the request, including protocol, host and port. It is RECOMMENDED to return the value of the request's origin header. If no Origin is sent to the back-end CORS headers SHOULD NOT be sent at all. |
http://client.isp.com:80 |
Access-Control-Allow-Credentials | If authorization is implemented by the back-end the value MUST be true . |
true |
Access-Control-Allow-Headers | Comma-separated list of HTTP headers allowed to be send. MUST contain at least Authorization if 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 here. | OPTIONS, GET, POST, PATCH, PUT, DELETE |
Access-Control-Expose-Headers | Some endpoints send non-safelisted HTTP response headers such as OpenEO-Identifier and OpenEO-Costs . All headers except Cache-Control , Content-Language , Content-Type , Expires , Last-Modified and Pragma must be listed in this header. Currently, the openEO API requires at least the following headers to be listed: Location, OpenEO-Identifier, OpenEO-Costs . |
Location, OpenEO-Identifier, OpenEO-Costs |
Content-Type | SHOULD return the content type delivered by the request that the permission is requested for. | application/json |
Request:
OPTIONS /api/v1/jobs HTTP/1.1
Host: openeo.cloudprovider.com
Origin: http://client.org:8080
Access-Control-Request-Method: POST
Access-Control-Request-Headers: Authorization, Content-Type
Response:
HTTP/1.1 204 No Content
Access-Control-Allow-Origin: http://client.org:8080
Access-Control-Allow-Credentials: true
Access-Control-Allow-Methods: OPTIONS, GET, POST, PATCH, PUT, DELETE
Access-Control-Allow-Headers: Authorization, Content-Type
Content-Type: application/json
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. It is RECOMMENDED to return the value of the request's origin header. If no Origin is sent to the back-end CORS headers SHOULD NOT be sent at all. |
http://client.isp.com:80 |
Access-Control-Allow-Credentials | If authorization is implemented by the back-end the value MUST be true . |
true |
Access-Control-Expose-Headers | Some endpoints send non-safelisted HTTP response headers such as OpenEO-Identifier and OpenEO-Costs . All headers except Cache-Control , Content-Language , Content-Type , Expires , Last-Modified and Pragma must be listed in this header. Currently, the openEO API requires at least the following headers to be listed: Location, OpenEO-Identifier, OpenEO-Costs . |
Location, OpenEO-Identifier, OpenEO-Costs |
Tip: Most server can send the required headers and the responses to the OPTIONS requests globally. Otherwise you may want to use a proxy server to add the headers and OPTIONS responses.
A process is an operation that performs a specific task on a set of parameters and returns a result. An example is computing a statistical operation, such as mean or median, on selected EO data. A process is similar to a function or method in programming languages. In openEO, processes are used to build a chain of processes (process graph), which can be applied to EO data to derive your own findings from the data.
A pre-defined process is a process provided by the back-end. There is a set of predefined processes by openEO to improve interoperability between back-ends. Back-ends SHOULD follow these specifications whenever possible. Not all processes need to be implemented by all back-ends. See the process reference for pre-defined processes.
A user-defined process is a process defined by the user. It can directly be part of another process graph or be stored as custom process on a back-end. Internally it is a process graph with optional additional metadata.
A process graph chains specific process calls from the set of pre-defined and user-defined processes together. A process graph itself can be stored as a (user-defined) process again. Similarly to scripts in the context of programming, process graphs organize and automate the execution of one or more processes that could alternatively be executed individually. In a process graph, processes need to be specific, i.e. concrete values or "placeholders" for input parameters need to be specified. These values can be scalars, arrays, objects, references to parameters or previous computations or other process graphs.
Back-ends and users MAY define new proprietary processes for their domain.
Back-end providers MUST follow the schema for predefined processes as in GET /processes
to define new processes. This includes:
Users MUST follow the schema for user-defined processes as in GET /process_graphs
to define new processes. This includes:
If new process are potentially useful for other back-ends the openEO consortium is happily accepting pull requests to include them in the list of pre-defined processes.
Each process parameter and the return values of a process define a schema that the value MUST comply to. The schemas are based on JSON Schema draft-07.
Two custom keywords have been defined:
subtype
for more fine-grained data-types than JSON Schema supports.parameters
to specify parameters that processes can pass to other process graphs.JSON Schema allows to specify only a small set of native data types (string, boolean, number, integer, array, object, null).
To support more fine grained data types, a custom JSON Schema keyword has been defined: subtype
.
It works similarly as the JSON Schema keyword format
and defines a number of subtypes for the native data types.
These should be re-used in process schema definitions whenever suitable.
If a general data type such as string
or number
is used in a schema, all subtypes with the same parent data type can be passed, too.
Clients should offer make passing subtypes as easy as passing a general data type.
For example, a parameter accepting strings must also allow passing a string with subtype date
and thus clients should encourage this by also providing a date-picker.
A list of predefined subtypes is available as JSON Schema in openeo-processes.
As defined above, a process graph is a chain of processes with explicit values for their parameters. Technically, a process graph is defined to be a graph of connected processes with exactly one node returning the final result:
<ProcessGraph> := {
"<ProcessNodeIdentifier>": <ProcessNode>,
...
}
<ProcessNodeIdentifier>
is a unique key within the process graph that is used to reference (the return value of) this process in arguments of other processes. The identifier is unique only strictly within itself, excluding any parent and child process graphs. Process node identifiers are also strictly scoped and can not be referenced from child or parent process graphs. Circular references are not allowed.
Note: We provide a non-binding JSON Schema for basic process graph validation.
A single node in a process graph (i.e. a specific instance of a process) is defined as follows:
<ProcessNode> := {
"process_id": <string>,
"namespace": <string> / null,
"description": <string>,
"arguments": <Arguments>,
"result": true / false
}
A process node MUST always contain key-value-pairs named process_id
and arguments
. It MAY contain a description
.
One of the nodes in a map of processes (the final one) MUST have the result
flag set to true
, all the other nodes can omit it as the default value is false
. Having such a node is important as multiple end nodes are possible, but in most use cases it is important to exactly specify the return value to be used by other processes. Each child process graph must also specify a result node similar to the "main" process graph.
process_id
MUST be a valid process ID in the namespace
given. Clients SHOULD warn the user if a user-defined process is added with the same identifier as one of the pre-defined process.
A process can have an arbitrary number of arguments. Their name and value are specified in the process specification as an object of key-value pairs:
<Arguments> := {
"<ParameterName>": <string|number|boolean|null|array|object|ResultReference|UserDefinedProcess|ParameterReference>
}
Notes:
The specified data types are the native data types supported by JSON, except for ResultReference
, UserDefinedProcess
and ParameterReference
.
Objects are not allowed to have keys with the following reserved names:
from_node
, except for objects of type ResultReference
process_graph
, except for objects of type UserDefinedProcess
from_parameter
, except for objects of type ParameterReference
Arrays and objects can also contain a ResultReference
, a UserDefinedProcess
or a ParameterReference
. So back-ends must fully traverse the process graphs, including all children.
A value of type <ResultReference>
is an object with a key from_node
and a <ProcessNodeIdentifier>
as corresponding value:
<ResultReference> := {
"from_node": "<ProcessNodeIdentifier>"
}
This tells the back-end that the process expects the result (i.e. the return value) from another process node to be passed as argument.
The <ProcessNodeIdentifier>
is strictly scoped and can only reference nodes from within the same process graph, not child or parent process graphs.
A user-defined process in a process graph is a child process graph, to be evaluated as part of another process.
Example: You want to calculate the absolute value of each pixel in a data cube.
This can be achieved in openeEO by executing the apply
process and pass it
a user-defined process as the "operator" to apply to each pixel.
In this simple example, the "child" process graph defining the user-defined process
consists of a single process absolute
, but it can be arbitrairy complex in general.
A <UserDefinedProcess>
argument MUST at least consist of an object with a key process_graph
.
Optionally, it can also be described with the same additional properties available for pre-defined processes such as an id, parameters, return values etc.
When embedded in a process graph, these additional properties of a user-defined process are usually not used, except for validation purposes.
<UserDefinedProcess> := {
"process_graph": <ProcessGraph>,
...
}
A "parent" process that works with a user-defined process can make so called process graph parameters
available to the "child" logic.
Processes in the "child" process graph can access these parameters by passing a ParameterReference
object as argument.
It is an object with key from_parameter
specifying the name of the process graph parameter:
<ParameterReference> := {
"from_parameter": "<ParameterReferenceName>"
}
The parameter names made available for <ParameterReferenceName>
are defined and passed to the process graph by one of the parent entities.
The parent could be a process (such as apply
or reduce_dimension
) or something else that executes a process graph (a secondary web service for example).
If the parent is a process, the parameter are defined in the parameters
property of the corresponding JSON Schema.
In case of the example given above, the parameter process
in the process apply
defines two process graph parameters: x
(the value of each pixel that will be processed) and context
(additional data passed through from the user).
The process absolute
expects an argument with the same name x
.
The process graph for the example would look as follows:
{
"process_id": "apply",
"arguments": {
"data": {"from_node": "loadcollection1"}
"process": {
"process_graph": {
"abs1": {
"process_id": "absolute",
"arguments": {
"x": {"from_parameter": "x"}
},
"result": true
}
}
}
}
}
loadcollection1
would be a result from another process, which is not part of this example.
Important: <ParameterReferenceName>
is less strictly scoped than <ProcessNodeIdentifier>
.
<ParameterReferenceName>
can be any parameter from the process graph or any of its parents.
The value for the parameter MUST be resolved as follows:
ProcessParameterMissing
must be thrown.Deriving minimum EVI (Enhanced Vegetation Index) measurements over pixel time series of Sentinel 2 imagery. The main process graph in blue, child process graphs in yellow:
The process graph for the algorithm: pg-evi-example.json
Processes can run in three different ways:
Results can be pre-computed by creating a batch job. They are submitted to the back-end's processing system, but will remain inactive until explicitly put into the processing queue. They will run only once and store results after execution. Results can be downloaded. Batch jobs are typically time consuming and user interaction is not possible although log files are generated for them. This is the only mode that allows to get an estimate about time, volume and costs beforehand.
A more dynamic way of processing and accessing data is to create a secondary web service. They allow web-based access using different protocols such as OGC WMS, OGC WCS, OGC API - Features or XYZ tiles. Some protocols such as the OGC WMS or XYZ tiles allow users to change the viewing extent or level of detail (zoom level). Therefore, computations often run on demand so that the requested data is calculated during the request. Back-ends should make sure to cache processed data to avoid additional/high costs and reduce waiting times for the user.
Processes can also be executed on-demand (i.e. synchronously). Results are delivered with the request itself and no job is created. Only lightweight computations, for example previews, should be executed using this approach as timeouts are to be expected for long-polling HTTP requests.
Process graph validation is a quite complex task. There's a JSON schema for basic process graph validation. It checks the general structure of a process graph, but only checking against the schema is not fully validating a process graph. Note that this JSON Schema is probably good enough for a first version, but should be revised and improved for production. There are further steps to do:
result: true
per process graph.process_id
are actually available in the corresponding namespace
.from_node
have a corresponding node in the same process graph.from_node
are compatible.from_node
, from_parameter
etc.).To process the process graph on the back-end you need to go through all nodes/processes in the list and set for each node to which node it passes data and from which it expects data. In another iteration the back-end can find all start nodes for processing by checking for zero dependencies.
You can now start and execute the start nodes (in parallel, if possible). Results can be passed to the nodes that were identified beforehand. For each node that depends on multiple inputs you need to check whether all dependencies have already finished and only execute once the last dependency is ready.
Please be aware that the result node (result
set to true
) is not necessarily the last node that is executed. The author of the process graph may choose to set a non-end node to the result node!
General information about the API implementation and other supported capabilities at the back-end.
The URL of the API MAY freely be chosen by the back-end providers. The path, including API versioning, is a recommendation only. Nevertheless, all servers MUST support HTTPS as the authentication methods are not secure with HTTP only!
Returns general information about the back-end, including which version and endpoints of the openEO API are supported. May also include billing information.
Information about the API version and supported endpoints / features.
This endpoint MUST always be available for the API to be valid.
api_version required | string Value: "1.0.0" Version number of the openEO specification this back-end implements. |
backend_version required | string Version number of the back-end implementation. Every change on back-end side MUST cause a change of the version number. |
stac_version required | string (stac_version) The version of the STAC specification, which MAY not be equal to the STAC API version. Supports versions 0.9.x and 1.x.x. |
id required | string Identifier for the service.
This field originates from STAC and is used as unique identifier for the STAC catalog available at |
title required | string The name of the service. |
description required | string <commonmark> A description of the service, which allows the service provider to introduce the user to its service. CommonMark 0.29 syntax MAY be used for rich text representation. |
production | boolean (production) Default: false Specifies whether the implementation is ready to be used in production use ( |
endpoints required | Array of objects (Endpoint) Lists all supported endpoints. Supported are all endpoints, which are implemented, return a 2XX or 3XX HTTP status code and are fully compatible to the API specification. An entry for this endpoint (path |
billing | object (Billing) Billing related data, e.g. the currency used or available plans to process jobs. This property MUST be specified if the back-end uses any billing related API functionalities, e.g. budgeting or estimates. The absence of this property doesn't mean the back-end is necessarily free to use for all. Providers may choose to bill users outside of the API, e.g. with a monthly fee that is not depending on individual API interactions. |
links required | Array of objects (Link) Links related to this service, e.g. the homepage of the service provider or the terms of service. It is highly RECOMMENDED to provide links with the
following
For additional relation types see also the lists of common relation types in openEO. |
The request can't be fulfilled due to an error on client-side, i.e. the request is invalid. The client SHOULD NOT repeat the request without modifications.
The response body SHOULD contain a JSON error object. MUST be any HTTP status code specified in RFC 7231. This request usually does not respond with HTTP status codes 401 and 403 due to missing authorization. HTTP status code 404 SHOULD be used if the value of a path parameter is invalid.
See also:
The request can't be fulfilled due to an error at the back-end. The error is never the client’s fault and therefore it is reasonable for the client to retry the exact same request that triggered this response.
The response body SHOULD contain a JSON error object. MUST be any HTTP status code specified in RFC 7231.
See also:
{- "api_version": "1.0.0",
- "backend_version": "1.1.2",
- "stac_version": "string",
- "id": "cool-eo-cloud",
- "title": "Cool EO Cloud",
- "description": "This service is provided to you by [Cool EO Cloud Corp.](http://cool-eo-cloud-corp.com). It implements the full openEO API and allows to process a range of 999 EO data sets, including \n\n* Sentinel 1/2/3 and 5\n* Landsat 7/8\n\nA free plan is available to test the service. For further information please contact our customer service at [support@cool-eo-cloud-corp.com](mailto:support@cool-eo-cloud-corp.com).",
- "production": false,
- "endpoints": [
- {
- "path": "/collections",
- "methods": [
- "GET"
]
}, - {
- "path": "/collections/{collection_id}",
- "methods": [
- "GET"
]
}, - {
- "path": "/processes",
- "methods": [
- "GET"
]
}, - {
- "path": "/jobs",
- "methods": [
- "GET",
- "POST"
]
}, - {
- "path": "/jobs/{job_id}",
- "methods": [
- "GET",
- "DELETE",
- "PATCH"
]
}
], - "billing": {
- "currency": "USD",
- "default_plan": "free",
- "plans": [
- {
- "name": "free",
- "description": "Free plan. Calculates one tile per second and a maximum amount of 100 tiles per hour.",
- "paid": false
}, - {
- "name": "premium",
- "description": "Premium plan. Calculates unlimited tiles and each calculated tile costs 0.003 USD.",
- "paid": true
}
]
}, - "links": [
- {
- "rel": "about",
- "type": "text/html",
- "title": "Homepage of the service provider"
}, - {
- "rel": "terms-of-service",
- "type": "text/html",
- "title": "Terms of Service"
}, - {
- "rel": "privacy-policy",
- "type": "text/html",
- "title": "Privacy Policy"
}, - {
- "rel": "version-history",
- "type": "application/json",
- "title": "List of supported openEO versions"
}, - {
- "rel": "conformance",
- "type": "application/json",
- "title": "OGC Conformance Classes"
}, - {
- "rel": "data",
- "type": "application/json",
- "title": "List of Datasets"
}
]
}
The Well-Known URI SHOULD be available directly at https://{{domain}}/.well-known/openeo
in contrast to the other endpoints, which may be versioned and can run on other hosts, ports, ... etc.
Well-Known URI (see RFC 5785) for openEO, listing all implemented openEO versions supported by the service provider.
This allows a client to easily identify the most recent openEO implementation it supports. By default, a client SHOULD connect to the most recent production-ready version it supports. If not available, the most recent supported version of all versions SHOULD be connected to. Clients MAY let users choose to connect to versions that are not production-ready or outdated. The most recent version is determined by comparing the version numbers according to rules from Semantic Versioning, especially §11. Any pair of API versions in this list MUST NOT be equal according to Semantic Versioning.
The Well-Known URI is the entry point for clients and users, so make
sure it is permanent and easy to use and remember. Clients MUST NOT
require the well-known path (./well-known/openeo
) in the URL that is
specified by a user to connect to the back-end. A client MUST request
https://example.com/.well-known/openeo
if a user tries to connect to
https://example.com
. If the request to the well-known URI fails, the
client SHOULD try to request the capabilities at /
from
https://example.com
.
This URI MUST NOT be versioned as the other endpoints. If your API
is available at https://example.com/api/v1.0
, the Well-Known URI
SHOULD be located at https://example.com/.well-known/openeo
and the
URI users connect to SHOULD be https://example.com
.
Clients MAY get additional information (e.g. title or description) about
a back-end from the most recent version that has the production
flag
set to true
.
List of all available API instances, each with URL and the implemented openEO API version.
versions required | Array of objects (API Instance) |
The request can't be fulfilled due to an error on client-side, i.e. the request is invalid. The client SHOULD NOT repeat the request without modifications.
The response body SHOULD contain a JSON error object. MUST be any HTTP status code specified in RFC 7231. This request usually does not respond with HTTP status codes 401 and 403 due to missing authorization. HTTP status code 404 SHOULD be used if the value of a path parameter is invalid.
See also:
The request can't be fulfilled due to an error at the back-end. The error is never the client’s fault and therefore it is reasonable for the client to retry the exact same request that triggered this response.
The response body SHOULD contain a JSON error object. MUST be any HTTP status code specified in RFC 7231.
See also:
{- "versions": [
]
}
The URL of the API MAY freely be chosen by the back-end providers. The path, including API versioning, is a recommendation only. Nevertheless, all servers MUST support HTTPS as the authentication methods are not secure with HTTP only!
The request will ask the back-end for 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 openEO. 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, openEO 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 are allowed to be case insensitive throughout the API.
An object with containing all input and output format separately. For each property input
and output
an object is defined where the file format names are the property keys and the property values are objects that define a title, supported parameters and related links.
input required | object (Input File Formats) Map of supported input file formats, i.e. file formats a back-end can read from. The property keys are the file format names that are used by clients and users, for example in process graphs. |
output required | object (Output File Formats) Map of supported output file formats, i.e. file formats a back-end can write to. The property keys are the file format names that are used by clients and users, for example in process graphs. |
The request can't be fulfilled due to an error on client-side, i.e. the request is invalid. The client SHOULD NOT repeat the request without modifications.
The response body SHOULD contain a JSON error object. MUST be any HTTP status code specified in RFC 7231. This request usually does not respond with HTTP status codes 401 and 403 due to missing authorization. HTTP status code 404 SHOULD be used if the value of a path parameter is invalid.
See also:
The request can't be fulfilled due to an error at the back-end. The error is never the client’s fault and therefore it is reasonable for the client to retry the exact same request that triggered this response.
The response body SHOULD contain a JSON error object. MUST be any HTTP status code specified in RFC 7231.
See also:
{- "output": {
- "GTiff": {
- "title": "GeoTiff",
- "description": "Export to GeoTiff. Doesn't support cloud-optimized GeoTiffs (COGs) yet.",
- "gis_data_types": [
- "raster"
], - "parameters": {
- "tiled": {
- "type": "boolean",
- "description": "This option can be used to force creation of tiled TIFF files [true]. By default [false] stripped TIFF files are created.",
- "default": false
}, - "compress": {
- "type": "string",
- "description": "Set the compression to use.",
- "default": "none",
- "enum": [
- "JPEG",
- "LZW",
- "DEFLATE",
- "NONE"
]
}, - "jpeg_quality": {
- "type": "integer",
- "description": "Set the JPEG quality when using JPEG.",
- "minimum": 1,
- "maximum": 100,
- "default": 75
}
}, - "links": [
- {
- "rel": "about",
- "title": "GDAL on the GeoTiff file format and storage options"
}
]
}, - "GPKG": {
- "title": "OGC GeoPackage",
- "gis_data_types": [
- "raster",
- "vector"
], - "parameters": {
- "version": {
- "type": "string",
- "description": "Set GeoPackage version. In AUTO mode, this will be equivalent to 1.2 starting with GDAL 2.3.",
- "enum": [
- "auto",
- "1",
- "1.1",
- "1.2"
], - "default": "auto"
}
}, - "links": [
- {
- "rel": "about",
- "title": "GDAL on GeoPackage for raster data"
}, - {
- "rel": "about",
- "title": "GDAL on GeoPackage for vector data"
}
]
}
}, - "input": {
- "GPKG": {
- "title": "OGC GeoPackage",
- "gis_data_types": [
- "raster",
- "vector"
], - "parameters": {
- "table": {
- "type": "string",
- "description": "**RASTER ONLY.** Name of the table containing the tiles. If the GeoPackage dataset only contains one table, this option is not necessary. Otherwise, it is required."
}
}, - "links": [
- {
- "rel": "about",
- "title": "GDAL on GeoPackage for raster data"
}, - {
- "rel": "about",
- "title": "GDAL on GeoPackage for vector data"
}
]
}
}
}
The URL of the API MAY freely be chosen by the back-end providers. The path, including API versioning, is a recommendation only. Nevertheless, all servers MUST support HTTPS as the authentication methods are not secure with HTTP only!
A list of all conformance classes specified in OGC standards that the server conforms to. This endpoint is only required if full compliance with OGC API standards is desired. Therefore, openEO back-ends MAY implement it for compatibility with OGC API clients and openEO clients don't need to request it.
The URIs of all conformance classes supported by the server.
conformsTo required | Array of strings <uri> |
The request can't be fulfilled due to an error at the back-end. The error is never the client’s fault and therefore it is reasonable for the client to retry the exact same request that triggered this response.
The response body SHOULD contain a JSON error object. MUST be any HTTP status code specified in RFC 7231.
See also:
{
}
The URL of the API MAY freely be chosen by the back-end providers. The path, including API versioning, is a recommendation only. Nevertheless, all servers MUST support HTTPS as the authentication methods are not secure with HTTP only!
Returns the supported runtimes for user-defined functions (UDFs), which includes either the programming languages including version numbers and available libraries including version numbers or docker containers.
Description of UDF runtime support
UDF Runtime name* | object |
The request can't be fulfilled due to an error on client-side, i.e. the request is invalid. The client SHOULD NOT repeat the request without modifications.
The response body SHOULD contain a JSON error object. MUST be any HTTP status code specified in RFC 7231. This request MUST respond with HTTP status codes 401 if authorization is required or 403 if the authorization failed or access is forbidden in general to the authenticated user. HTTP status code 404 SHOULD be used if the value of a path parameter is invalid.
See also:
The request can't be fulfilled due to an error at the back-end. The error is never the client’s fault and therefore it is reasonable for the client to retry the exact same request that triggered this response.
The response body SHOULD contain a JSON error object. MUST be any HTTP status code specified in RFC 7231.
See also:
{- "PHP7": {
- "title": "PHP v7.x",
- "description": "Just an example how to reference a docker image.",
- "type": "docker",
- "docker": "openeo/udf-php7",
- "default": "latest",
- "tags": [
- "latest",
- "7.3.1",
- "7.3",
- "7.2"
],
}, - "R": {
- "title": "R v3.x for Statistical Computing",
- "description": "R programming language with `Rcpp` and `rmarkdown` extensions installed.",
- "type": "language",
- "default": "3.5.2",
- "versions": {
- "3.1.0": {
- "libraries": {
- "Rcpp": {
- "version": "1.0.10",
}, - "rmarkdown": {
- "version": "1.7.0",
}
}
}, - "3.5.2": {
- "libraries": {
- "Rcpp": {
- "version": "1.2.0",
}, - "rmarkdown": {
- "version": "1.7.0",
}
}
}
}
}
}
The URL of the API MAY freely be chosen by the back-end providers. The path, including API versioning, is a recommendation only. Nevertheless, all servers MUST support HTTPS as the authentication methods are not secure with HTTP only!
The request will ask the back-end for 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.
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 are allowed to be case insensitive throughout the API.
An object with a map containing all service names as keys and an object that defines supported configuration settings and process parameters.
Service Name* | object (Service Type) |
The request can't be fulfilled due to an error on client-side, i.e. the request is invalid. The client SHOULD NOT repeat the request without modifications.
The response body SHOULD contain a JSON error object. MUST be any HTTP status code specified in RFC 7231. This request usually does not respond with HTTP status codes 401 and 403 due to missing authorization. HTTP status code 404 SHOULD be used if the value of a path parameter is invalid.
See also:
The request can't be fulfilled due to an error at the back-end. The error is never the client’s fault and therefore it is reasonable for the client to retry the exact same request that triggered this response.
The response body SHOULD contain a JSON error object. MUST be any HTTP status code specified in RFC 7231.
See also:
{- "WMS": {
- "title": "OGC Web Map Service",
- "configuration": {
- "version": {
- "type": "string",
- "description": "The WMS version offered to consumers of the service.",
- "default": "1.3.0",
- "enum": [
- "1.1.1",
- "1.3.0"
]
}
}, - "process_parameters": [
- {
- "name": "layer",
- "description": "The layer name.",
- "schema": {
- "type": "string"
}, - "default": "roads"
}, - {
- "name": "spatial_extent_west",
- "description": "The lower left corner for coordinate axis 1 of the extent currently shown to the consumer.",
- "schema": {
- "type": "number"
}
}, - {
- "name": "spatial_extent_south",
- "description": "The lower left corner for coordinate axis 2 of the extent currently shown to the consumer.",
- "schema": {
- "type": "number"
}
}, - {
- "name": "spatial_extent_east",
- "description": "The upper right corner for coordinate axis 1 of the extent currently shown to the consumer.",
- "schema": {
- "type": "number"
}
}, - {
- "name": "spatial_extent_north",
- "description": "The upper right corner for coordinate axis 2 of the extent currently shown to the consumer.",
- "schema": {
- "type": "number"
}
}
], - "links": [
- {
- "rel": "about",
- "title": "OGC Web Map Service Standard"
}
]
}, - "OGCAPI-FEATURES": {
- "title": "OGC API - Features",
- "description": "Exposes a OGC API - Features in version 1.0 of the specification (successor of OGC WFS 3.0).",
- "configuration": {
- "title": {
- "type": "string",
- "description": "The title for the OGC API - Features landing page"
}, - "description": {
- "type": "string",
- "description": "The description for the OGC API - Features landing page"
}, - "conformsTo": {
- "type": "array",
- "description": "The OGC API - Features conformance classes to enable for this service.\n\n`http://www.opengis.net/spec/ogcapi-features-1/1.0/conf/core` is always enabled.",
}
}, - "process_parameters": [ ],
- "links": [
- {
- "rel": "about",
- "title": "OGC Web Feature Service Standard"
}
]
}
}
The following endpoints handle user profiles, accounting and authentication. See also Authentication. In general, the openEO API only defines a minimum subset of user management and accounting functionality. It allows to
Therefore, the API leaves some aspects open that have to be handled by the back-ends separately, including
The URL of the API MAY freely be chosen by the back-end providers. The path, including API versioning, is a recommendation only. Nevertheless, all servers MUST support HTTPS as the authentication methods are not secure with HTTP only!
This endpoint lists the supported OpenID Connect providers (OP). OpenID Providers MUST support OpenID Connect Discovery.
It is highly RECOMMENDED to implement OpenID Connect for public services in favor of Basic authentication.
openEO 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 Provider does not necessarily provide information about the issuer (i.e. the OpenID 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 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 Provider.
Lists the the OpenID Providers.
providers required | Array of objects (OpenID Provider) non-empty |
The request can't be fulfilled due to an error on client-side, i.e. the request is invalid. The client SHOULD NOT repeat the request without modifications.
The response body SHOULD contain a JSON error object. MUST be any HTTP status code specified in RFC 7231. This request MUST respond with HTTP status codes 401 if authorization is required or 403 if the authorization failed or access is forbidden in general to the authenticated user. HTTP status code 404 SHOULD be used if the value of a path parameter is invalid.
See also:
The request can't be fulfilled due to an error at the back-end. The error is never the client’s fault and therefore it is reasonable for the client to retry the exact same request that triggered this response.
The response body SHOULD contain a JSON error object. MUST be any HTTP status code specified in RFC 7231.
See also:
{- "providers": [
- {
- "id": "google",
- "title": "Google",
- "description": "Login with your Google Account.",
- "scopes": [
- "openid",
- "profile",
- "email",
- "earthengine"
]
}, - {
- "id": "ms",
- "title": "Microsoft",
- "description": "Login with your Microsoft or Skype Account.",
- "scopes": [ ]
}
]
}
The URL of the API MAY freely be chosen by the back-end providers. The path, including API versioning, is a recommendation only. Nevertheless, all servers MUST support HTTPS as the authentication methods are not secure with HTTP only!
This request 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.
Credentials are correct and authentication succeeded.
access_token required | string The access token (without |
The request can't be fulfilled due to an error on client-side, i.e. the request is invalid. The client SHOULD NOT repeat the request without modifications.
The response body SHOULD contain a JSON error object. MUST be any HTTP status code specified in RFC 7231. This request MUST respond with HTTP status codes 401 if authorization is required or 403 if the authorization failed or access is forbidden in general to the authenticated user. HTTP status code 404 SHOULD be used if the value of a path parameter is invalid.
See also:
The request can't be fulfilled due to an error at the back-end. The error is never the client’s fault and therefore it is reasonable for the client to retry the exact same request that triggered this response.
The response body SHOULD contain a JSON error object. MUST be any HTTP status code specified in RFC 7231.
See also:
{- "access_token": "b34ba2bdf9ac9ee1"
}
The URL of the API MAY freely be chosen by the back-end providers. The path, including API versioning, is a recommendation only. Nevertheless, all servers MUST support HTTPS as the authentication methods are not secure with HTTP only!
This endpoint always returns the user id and MAY return the disk quota available to the user. It 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. For back-ends that involve accounting, this service MAY also return the currently available money or credits in the currency the back-end is working with. This endpoint MAY be extended to fulfil the specification of the OpenID Connect UserInfo Endpoint.
Information about the logged in user.
user_id required | string (user_id) ^[\w\-\.~]+$ Unique identifier of the user. MUST match the specified pattern. This is usually a randomly generated internal identifier from the provider not meant for displaying purposes. |
name | string The user name, a human-friendly displayable name. Could be the user's real name or a nickname. |
storage | object (User Storage) Nullable Information about the storage space available to the user. |
budget | number (budget) Nullable Default: null Maximum amount of costs the request is allowed to produce. The value MUST be specified in the currency the back-end is working with. The currency can be retrieved by calling If possible, back-ends SHOULD reject jobs with openEO error Setting the budget to |
links | Array of objects (Link) Links related to the user profile, e.g. where payments are handled or the user profile could be edited. It is RECOMMENDED to provide links with the following
For additional relation types see also the lists of common relation types in openEO. |
The request can't be fulfilled due to an error on client-side, i.e. the request is invalid. The client SHOULD NOT repeat the request without modifications.
The response body SHOULD contain a JSON error object. MUST be any HTTP status code specified in RFC 7231. This request MUST respond with HTTP status codes 401 if authorization is required or 403 if the authorization failed or access is forbidden in general to the authenticated user. HTTP status code 404 SHOULD be used if the value of a path parameter is invalid.
See also:
The request can't be fulfilled due to an error at the back-end. The error is never the client’s fault and therefore it is reasonable for the client to retry the exact same request that triggered this response.
The response body SHOULD contain a JSON error object. MUST be any HTTP status code specified in RFC 7231.
See also:
{- "user_id": "john_doe",
- "name": "string",
- "storage": {
- "free": 536870912,
- "quota": 1073741824
}, - "budget": 100,
- "links": [
- {
- "rel": "alternate",
- "type": "text/html",
- "title": "User profile"
}, - {
- "rel": "alternate",
- "type": "text/vcard",
- "title": "vCard of John Doe"
}
]
}
These endpoints allow to list the collections that are available at the back-end and can be used as data cubes for data processing.
For data discovery of Earth Observation Collections at the back-ends, openEO strives for compatibility with the specifications SpatioTemporal Asset Catalog (STAC) and OGC API - Features - Part 1: Core as far as possible. Implementing the data discovery endpoints of openEO should also produce valid STAC API 0.9.0 and OGC API - Features 1.0 responses, including (partial) compatibility with their APIs.
The data discovery endpoints GET /collections
and GET /collections/{collection_id}
are compatible with OGC API - Features and STAC. Both specifications define additional endpoints that need to be implemented to be fully compatible. The additional endpoints can easily be integrated into an openEO API implementation. A rough list of actions for compatibility is available below, but please refer to their specifications to find out the full details.
Important: STAC specification and STAC API are different specifications and have different version numbers after version 0.9.0.
The openEO API only implements STAC API version 0.9.0, which allows to serve all STAC specification versions in the range of 0.9.x and 1.x.x (see the stac_version
property).
STAC has several extensions that can be used to better describe your data. Clients and server are not required to implement all of them, so be aware that some clients may not be able to read all your metadata.
Some commonly used extensions that are relevant for datasets exposed through the openEO API are:
If you'd like to provide your data for download in addition to offering the cloud processing service, you can implement the full STAC API. Therefore you can implement the endpoints GET /collections/{collectionId}/items
and GET /collections/{collectionId}/items/{featureId}
to support retrieval of individual items. To benefit from the STAC ecosystem and allow searching for items you can also implement POST /search
and GET /search
. Further information can be found in the STAC API repository.
The URL of the API MAY freely be chosen by the back-end providers. The path, including API versioning, is a recommendation only. Nevertheless, all servers MUST support HTTPS as the authentication methods are not secure with HTTP only!
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
summaries
and cube:dimensions
properties).
To get the full metadata for a collection clients MUST
request GET /collections/{collection_id}
.
This endpoint is compatible with STAC 0.9.0 and OGC API - Features. STAC API features / extensions and STAC extensions can be implemented in addition to what is documented here.
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 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 |
Lists of collections and related links.
collections required | Array of objects (Collection) |
links required | Array of objects (links_pagination) Links related to this list of resources, for example links for pagination or alternative formats such as a human-readable HTML version. The links array MUST NOT be paginated. If pagination is implemented, the following
For additional relation types see also the lists of common relation types in openEO. |
The request can't be fulfilled due to an error on client-side, i.e. the request is invalid. The client SHOULD NOT repeat the request without modifications.
The response body SHOULD contain a JSON error object. MUST be any HTTP status code specified in RFC 7231. This request MUST respond with HTTP status codes 401 if authorization is required or 403 if the authorization failed or access is forbidden in general to the authenticated user. HTTP status code 404 SHOULD be used if the value of a path parameter is invalid.
See also:
The request can't be fulfilled due to an error at the back-end. The error is never the client’s fault and therefore it is reasonable for the client to retry the exact same request that triggered this response.
The response body SHOULD contain a JSON error object. MUST be any HTTP status code specified in RFC 7231.
See also:
{- "collections": [
- {
- "stac_version": "0.9.0",
- "id": "Sentinel-2A",
- "title": "Sentinel-2A MSI L1C",
- "description": "Sentinel-2A is a wide-swath, high-resolution, multi-spectral imaging mission supporting Copernicus Land Monitoring studies, including the monitoring of vegetation, soil and water cover, as well as observation of inland waterways and coastal areas.",
- "license": "proprietary",
- "extent": {
- "spatial": {
- "bbox": [
- [
- -180,
- -56,
- 180,
- 83
]
]
}, - "temporal": {
- "interval": [
- [
- "2015-06-23T00:00:00Z",
- "2019-01-01T00:00:00Z"
]
]
}
}, - "keywords": [
- "copernicus",
- "esa",
- "msi",
- "sentinel"
], - "providers": [
- {
- "name": "European Space Agency (ESA)",
- "roles": [
- "producer",
- "licensor"
],
}, - {
- "name": "openEO",
- "roles": [
- "host"
],
}
], - "links": [
- {
- "rel": "license",
}
]
}, - {
- "stac_version": "0.9.0",
- "id": "MOD09Q1",
- "title": "MODIS/Terra Surface Reflectance 8-Day L3 Global 250m SIN Grid V006",
- "description": "The MOD09Q1 Version 6 product provides an estimate of the surface spectral reflectance of Terra MODIS Bands 1-2 corrected for atmospheric conditions such as gasses, aerosols, and Rayleigh scattering. Provided along with the two 250 m MODIS bands is one additional layer, the Surface Reflectance QC 250 m band. For each pixel, a value is selected from all the acquisitions within the 8-day composite period. The criteria for the pixel choice include cloud and solar zenith. When several acquisitions meet the criteria the pixel with the minimum channel 3 (blue) value is used. Validation at stage 3 has been achieved for all MODIS Surface Reflectance products.",
- "license": "proprietary",
- "extent": {
- "spatial": {
- "bbox": [
- [
- -180,
- -90,
- 180,
- 90
]
]
}, - "temporal": {
- "interval": [
- [
- "2000-02-01T00:00:00Z",
- null
]
]
}
},
}
], - "links": [
- {
- "rel": "alternate",
- "title": "openEO catalog (OGC Catalogue Services 3.0)"
}
]
}
The URL of the API MAY freely be chosen by the back-end providers. The path, including API versioning, is a recommendation only. Nevertheless, all servers MUST support HTTPS as the authentication methods are not secure with HTTP only!
Lists all information about a specific collection specified by the
identifier collection_id
.
This endpoint is compatible with STAC 0.9.0 and OGC API - Features. STAC API features / extensions and STAC extensions can be implemented in addition to what is documented here.
collection_id required | string (collection_id) ^[\w\-\.~\/]+$ Example: Sentinel-2A Collection identifier |
JSON object with the full collection metadata.
stac_version required | string (stac_version) The version of the STAC specification, which MAY not be equal to the STAC API version. Supports versions 0.9.x and 1.x.x. |
stac_extensions | Array of Reference to a JSON Schema (string) or Reference to a core extension (string) (stac_extensions) A list of implemented STAC extensions. The list contains URLs to the JSON Schema files it can be validated against. For official extensions, a "shortcut" can be used. This means you can specify the folder name of the extension in the STAC repository, for example |
id required | string (collection_id) ^[\w\-\.~\/]+$ A unique identifier for the collection, which MUST match the specified pattern. |
title | string A short descriptive one-line title for the collection. |
description required | string <commonmark> Detailed multi-line description to explain the collection. CommonMark 0.29 syntax MAY be used for rich text representation. |
keywords | Array of strings List of keywords describing the collection. |
version | string Version of the collection. This property REQUIRES to add |
deprecated | boolean Default: false Specifies that the collection is deprecated with the potential to be removed. It should be transitioned out of usage as soon as possible and users should refrain from using it in new projects. A link with relation type This property REQUIRES to add |
license required | string (stac_license) License(s) of the data as a SPDX License identifier.
Alternatively, use Non-SPDX licenses SHOULD add a link to the license text with the
|
providers | Array of objects (stac_providers) A list of providers, which MAY include all organizations capturing or processing the data or the hosting provider. Providers SHOULD be listed in chronological order with the most recent provider being the last element of the list. |
extent required | object (Collection Extent) The extent of the features in the collection. Additional members MAY be added to represent other extents, for example, thermal or pressure ranges. |
links required | Array of objects (Link) Links related to this collection. Could reference to licensing information, other meta data formats with additional information or a preview image.
It is RECOMMENDED to provide links with the following
|
cube:dimensions required | object (STAC Collection Cube Dimensions) Uniquely named dimensions of the data cube. The keys of the object are the dimension names. For interoperability, it is RECOMMENDED to use the following dimension names if there is only a single dimension with the specified criteria:
This property REQUIRES to add |
summaries required | object (STAC Summaries (Collection Properties)) Collection properties from STAC extensions (e.g. EO, SAR, Satellite or Scientific) or even custom extensions. Summaries are either a unique set of all available
values or statistics. Statistics by default only
specify the range (minimum and maximum values), but
can optionally be accompanied by additional
statistical values. The range can specify the
potential range of values, but it is recommended to be
as precise as possible. The set of values MUST contain
at least one element and it is strongly RECOMMENDED to
list all values. It is recommended to list as many
properties as reasonable so that consumers get a full
overview of the Collection. Properties that are
covered by the Collection specification (e.g.
Potential fields for the summaries can be found here:
|
assets | object (Assets) Dictionary of asset objects for data that can be downloaded, each with a unique key. The keys MAY be used by clients as file names.
Implementing this property REQUIRES to add |
The request can't be fulfilled due to an error on client-side, i.e. the request is invalid. The client SHOULD NOT repeat the request without modifications.
The response body SHOULD contain a JSON error object. MUST be any HTTP status code specified in RFC 7231. This request MUST respond with HTTP status codes 401 if authorization is required or 403 if the authorization failed or access is forbidden in general to the authenticated user. HTTP status code 404 SHOULD be used if the value of a path parameter is invalid.
See also:
The request can't be fulfilled due to an error at the back-end. The error is never the client’s fault and therefore it is reasonable for the client to retry the exact same request that triggered this response.
The response body SHOULD contain a JSON error object. MUST be any HTTP status code specified in RFC 7231.
See also:
{- "stac_version": "0.9.0",
- "stac_extensions": [
- "collection-assets",
- "datacube",
- "scientific",
- "version"
], - "id": "Sentinel-2",
- "title": "Sentinel-2 MSI L2A",
- "description": "Sentinel-2A is a wide-swath, high-resolution, multi-spectral imaging mission supporting Copernicus Land Monitoring studies.",
- "license": "proprietary",
- "keywords": [
- "copernicus",
- "esa",
- "msi",
- "sentinel"
], - "version": "20200106A",
- "providers": [
- {
- "name": "European Space Agency (ESA)",
- "roles": [
- "producer",
- "licensor"
],
}, - {
- "name": "Google",
- "roles": [
- "host"
],
}
], - "extent": {
- "spatial": {
- "bbox": [
- [
- -180,
- -56,
- 180,
- 83
]
]
}, - "temporal": {
- "interval": [
- [
- "2015-06-23T00:00:00Z",
- null
]
]
}
}, - "links": [
- {
- "rel": "license",
- "type": "application/pdf"
}, - {
- "rel": "about",
- "type": "text/html",
- "title": "ESA Sentinel-2 MSI Level-1C User Guide"
}, - {
- "rel": "example",
- "type": "application/json",
- "title": "Example Process for True-Color Visualization"
}, - {
- "rel": "example",
- "type": "application/json",
- "title": "Example Process for NDVI Calculation and Visualization"
}
], - "cube:dimensions": {
- "x": {
- "type": "spatial",
- "axis": "x",
- "extent": [
- -180,
- 180
], - "reference_system": 4326
}, - "y": {
- "type": "spatial",
- "axis": "y",
- "extent": [
- -56,
- 83
], - "reference_system": 4326
}, - "t": {
- "type": "temporal",
- "extent": [
- "2015-06-23T00:00:00Z",
- null
], - "step": null
}, - "bands": {
- "type": "bands",
- "values": [
- "B1",
- "B2",
- "B3",
- "B4",
- "B5",
- "B6",
- "B7",
- "B8",
- "B8A",
- "B9",
- "B10",
- "B11",
- "B12"
]
}
}, - "sci:citation": "Copernicus Sentinel data [Year]",
- "summaries": {
- "constellation": [
- "Sentinel-2"
], - "platform": [
- "Sentinel-2A",
- "Sentinel-2B"
], - "instruments": [
- "MSI"
], - "eo:cloud_cover": {
- "min": 0,
- "max": 75
}, - "sat:orbit_state": [
- "ascending",
- "descending"
], - "eo:gsd": [
- 10,
- 20,
- 60
], - "eo:bands": [
- {
- "name": "B1",
- "common_name": "coastal",
- "center_wavelength": 0.4439,
- "gsd": 60
}, - {
- "name": "B2",
- "common_name": "blue",
- "center_wavelength": 0.4966,
- "gsd": 10
}, - {
- "name": "B3",
- "common_name": "green",
- "center_wavelength": 0.56,
- "gsd": 10
}, - {
- "name": "B4",
- "common_name": "red",
- "center_wavelength": 0.6645,
- "gsd": 10
}, - {
- "name": "B5",
- "center_wavelength": 0.7039,
- "gsd": 20
}, - {
- "name": "B6",
- "center_wavelength": 0.7402,
- "gsd": 20
}, - {
- "name": "B7",
- "center_wavelength": 0.7825,
- "gsd": 20
}, - {
- "name": "B8",
- "common_name": "nir",
- "center_wavelength": 0.8351,
- "gsd": 10
}, - {
- "name": "B8A",
- "common_name": "nir08",
- "center_wavelength": 0.8648,
- "gsd": 20
}, - {
- "name": "B9",
- "common_name": "nir09",
- "center_wavelength": 0.945,
- "gsd": 60
}, - {
- "name": "B10",
- "common_name": "cirrus",
- "center_wavelength": 1.3735,
- "gsd": 60
}, - {
- "name": "B11",
- "common_name": "swir16",
- "center_wavelength": 1.6137,
- "gsd": 20
}, - {
- "name": "B12",
- "common_name": "swir22",
- "center_wavelength": 2.2024,
- "gsd": 20
}
], - "proj:epsg": {
- "min": 32601,
- "max": 32660
}
}, - "assets": {
- "thumbnail": {
- "type": "image/png",
- "title": "Preview",
- "roles": [
- "thumbnail"
]
}, - "inspire": {
- "type": "application/xml",
- "title": "INSPIRE metadata",
- "description": "INSPIRE compliant XML metadata",
- "roles": [
- "metadata"
]
}
}
}
These endpoints allow to list the predefined processes that are available at the back-end. To list user-defined processes see 'User-Defined Processes'.
The URL of the API MAY freely be chosen by the back-end providers. The path, including API versioning, is a recommendation only. Nevertheless, all servers MUST support HTTPS as the authentication methods are not secure with HTTP only!
The request asks the back-end for available predefined processes and returns detailed process descriptions, including parameters and return values.
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 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 |
Formal specification describing the supported predefined processes.
processes required | Array of objects (Pre-Defined Process) |
links required | Array of objects (links_pagination) Links related to this list of resources, for example links for pagination or alternative formats such as a human-readable HTML version. The links array MUST NOT be paginated. If pagination is implemented, the following
For additional relation types see also the lists of common relation types in openEO. |
The request can't be fulfilled due to an error on client-side, i.e. the request is invalid. The client SHOULD NOT repeat the request without modifications.
The response body SHOULD contain a JSON error object. MUST be any HTTP status code specified in RFC 7231. This request MUST respond with HTTP status codes 401 if authorization is required or 403 if the authorization failed or access is forbidden in general to the authenticated user. HTTP status code 404 SHOULD be used if the value of a path parameter is invalid.
See also:
The request can't be fulfilled due to an error at the back-end. The error is never the client’s fault and therefore it is reasonable for the client to retry the exact same request that triggered this response.
The response body SHOULD contain a JSON error object. MUST be any HTTP status code specified in RFC 7231.
See also:
{- "processes": [
- {
- "id": "apply",
- "summary": "Apply a process to each pixel",
- "description": "Applies a *unary* process to each pixel value in the data cube (i.e. a local operation). A unary process takes a single value and returns a single value, for example ``abs()`` or ``linear_scale_range()``.",
- "categories": [
- "cubes"
], - "parameters": [
- {
- "name": "data",
- "description": "A data cube.",
- "schema": {
- "type": "object",
- "subtype": "raster-cube"
}
}, - {
- "name": "process",
- "description": "A unary process to be applied on each value, may consist of multiple sub-processes.",
- "schema": {
- "type": "object",
- "subtype": "process-graph",
- "parameters": [
- {
- "name": "x",
- "description": "The value to process.",
- "schema": {
- "description": "Any data type."
}
}
]
}
}
], - "returns": {
- "description": "A data cube with the newly computed values. The resolution, cardinality and the number of dimensions are the same as for the original data cube.",
- "schema": {
- "type": "object",
- "subtype": "raster-cube"
}
}
}, - {
- "id": "multiply",
- "summary": "Multiplication of two numbers",
- "description": "Multiplies the two numbers `x` and `y` (*x * y*) and returns the computed product.\n\nNo-data values are taken into account so that `null` is returned if any element is such a value.\n\nThe computations follow [IEEE Standard 754](https://ieeexplore.ieee.org/document/8766229) whenever the processing environment supports it.",
- "categories": [
- "math"
], - "parameters": [
- {
- "name": "x",
- "description": "The multiplier.",
- "schema": {
- "type": [
- "number",
- "null"
]
}
}, - {
- "name": "y",
- "description": "The multiplicand.",
- "schema": {
- "type": [
- "number",
- "null"
]
}
}
], - "returns": {
- "description": "The computed product of the two numbers.",
- "schema": {
- "type": [
- "number",
- "null"
]
}
}, - "exceptions": {
- "MultiplicandMissing": {
- "message": "Multiplication requires at least two numbers."
}
}, - "examples": [
- {
- "arguments": {
- "x": 5,
- "y": 2.5
}, - "returns": 12.5
}, - {
- "arguments": {
- "x": -2,
- "y": -4
}, - "returns": 8
}, - {
- "arguments": {
- "x": 1,
- "y": null
}, - "returns": null
}
], - "links": [
- {
- "rel": "about",
- "title": "Product explained by Wolfram MathWorld"
}, - {
- "rel": "about",
- "title": "IEEE Standard 754-2019 for Floating-Point Arithmetic"
}
]
}
], - "links": [
- {
- "rel": "alternate",
- "type": "text/html",
- "title": "HTML version of the processes"
}
]
}
The URL of the API MAY freely be chosen by the back-end providers. The path, including API versioning, is a recommendation only. Nevertheless, all servers MUST support HTTPS as the authentication methods are not secure with HTTP only!
This service 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 secondary web service clients MUST
request GET /services/{service_id}
.
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 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 |
JSON array with user-defined processes.
processes required | Array of objects (User-defined Process Metadata) Array of user-defined processes |
links required | Array of objects (links_pagination) Links related to this list of resources, for example links for pagination or alternative formats such as a human-readable HTML version. The links array MUST NOT be paginated. If pagination is implemented, the following
For additional relation types see also the lists of common relation types in openEO. |
The request can't be fulfilled due to an error on client-side, i.e. the request is invalid. The client SHOULD NOT repeat the request without modifications.
The response body SHOULD contain a JSON error object. MUST be any HTTP status code specified in RFC 7231. This request MUST respond with HTTP status codes 401 if authorization is required or 403 if the authorization failed or access is forbidden in general to the authenticated user. HTTP status code 404 SHOULD be used if the value of a path parameter is invalid.
See also:
The request can't be fulfilled due to an error at the back-end. The error is never the client’s fault and therefore it is reasonable for the client to retry the exact same request that triggered this response.
The response body SHOULD contain a JSON error object. MUST be any HTTP status code specified in RFC 7231.
See also:
{- "processes": [
- {
- "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": [
- {
- "name": "red",
- "description": "Value from the red band.",
- "schema": {
- "type": "number"
}
}, - {
- "name": "blue",
- "description": "Value from the blue band.",
- "schema": {
- "type": "number"
}
}, - {
- "name": "nir",
- "description": "Value from the near infrared band.",
- "schema": {
- "type": "number"
}
}
], - "returns": {
- "description": "Computed EVI.",
- "schema": {
- "type": "number"
}
}
}, - {
- "id": "ndsi",
- "summary": "Normalized-Difference Snow Index",
- "parameters": [
- {
- "name": "green",
- "description": "Value from the Visible Green (0.53 - 0.61 micrometers) band.",
- "schema": {
- "type": "number"
}
}, - {
- "name": "swir",
- "description": "Value from the Short Wave Infrared (1.55 - 1.75 micrometers) band.",
- "schema": {
- "type": "number"
}
}
], - "returns": {
- "schema": {
- "type": "number"
}
}
}, - {
- "id": "my_custom_process"
}
], - "links": [ ]
}
The URL of the API MAY freely be chosen by the back-end providers. The path, including API versioning, is a recommendation only. Nevertheless, all servers MUST support HTTPS as the authentication methods are not secure with HTTP only!
Returns all information about a user-defined process, including its process graph.
process_graph_id required | string (process_id) ^\w+$ Example: ndvi Unique identifier for a user-defined process. |
The user-defined process with process graph.
summary | string Nullable A short summary of what the process does. |
description | string <commonmark> Nullable 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: |
parameters | Array of objects Nullable 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)
|
returns | object Nullable The data that is returned from this process. |
id required | string (process_id) ^\w+$ The identifier for the process. It MUST be unique across its namespace (e.g. pre-defined 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 pre-defined process. |
categories | Array of strings (process_categories) A list of categories. |
deprecated | boolean (process_deprecated) Default: false Specifies that the process or parameter 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. For processes a link with relation type |
experimental | boolean (process_experimental) Default: false Declares the process or parameter to be 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. |
exceptions | object (Process Exceptions) Declares any 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. The keys define the error code and MUST match the following pattern:
This schema follows the schema of the general openEO error list (see errors.json). |
examples | Array of objects (Process Example) Examples, may be used for unit tests. |
links | Array of objects (Link) Links related to this process, e.g. additional external documentation.
It is RECOMMENDED to provide links with the following
|
process_graph 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. |
The request can't be fulfilled due to an error on client-side, i.e. the request is invalid. The client SHOULD NOT repeat the request without modifications.
The response body SHOULD contain a JSON error object. MUST be any HTTP status code specified in RFC 7231. This request MUST respond with HTTP status codes 401 if authorization is required or 403 if the authorization failed or access is forbidden in general to the authenticated user. HTTP status code 404 SHOULD be used if the value of a path parameter is invalid.
See also:
The request can't be fulfilled due to an error at the back-end. The error is never the client’s fault and therefore it is reasonable for the client to retry the exact same request that triggered this response.
The response body SHOULD contain a JSON error object. MUST be any HTTP status code specified in RFC 7231.
See also:
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": [
- {
- "name": "red",
- "description": "Value from the red band.",
- "schema": {
- "type": "number"
}
}, - {
- "name": "blue",
- "description": "Value from the blue band.",
- "schema": {
- "type": "number"
}
}, - {
- "name": "nir",
- "description": "Value from the near infrared band.",
- "schema": {
- "type": "number"
}
}
], - "returns": {
- "description": "Computed EVI.",
- "schema": {
- "type": "number"
}
}, - "process_graph": {
- "sub": {
- "process_id": "subtract",
- "arguments": {
- "x": {
- "from_parameter": "nir"
}, - "y": {
- "from_parameter": "red"
}
}
}, - "p1": {
- "process_id": "multiply",
- "arguments": {
- "x": 6,
- "y": {
- "from_parameter": "red"
}
}
}, - "p2": {
- "process_id": "multiply",
- "arguments": {
- "x": -7.5,
- "y": {
- "from_parameter": "blue"
}
}
}, - "sum": {
- "process_id": "sum",
- "arguments": {
- "data": [
- 1,
- {
- "from_parameter": "nir"
}, - {
- "from_node": "p1"
}, - {
- "from_node": "p2"
}
]
}
}, - "div": {
- "process_id": "divide",
- "arguments": {
- "x": {
- "from_node": "sub"
}, - "y": {
- "from_node": "sum"
}
}
}, - "p3": {
- "process_id": "multiply",
- "arguments": {
- "x": 2.5,
- "y": {
- "from_node": "div"
}
}, - "result": true
}
}
}
These endpoints allow to store and manage user-defined processes with their process graphs at the back-end.
The URL of the API MAY freely be chosen by the back-end providers. The path, including API versioning, is a recommendation only. Nevertheless, all servers MUST support HTTPS as the authentication methods are not secure with HTTP only!
Validates a user-defined process without executing it. A user-defined process is
considered valid unless the errors
array in the response contains at
least one error.
Checks whether the process graph is schematically correct and the processes are supported by the back-end. It MUST also check the arguments against the schema, but checking whether the arguments are adequate in the context of data is OPTIONAL. For example, a non-existing band name may get rejected only by a few back-ends. The validation MUST NOT throw an error for unresolvable process parameters.
Back-ends MUST validate the process graph. Validating the corresponding metadata is OPTIONAL.
Errors that usually occur during processing MAY NOT get reported, e.g. if a referenced file is accessible at the time of execution.
Back-ends can either report all errors at once or stop the validation once they found the first error.
Please note that a validation always returns with HTTP status code 200. Error codes in the 4xx and 5xx ranges MUST be returned only when the general validation request is invalid (e.g. server is busy or properties in the request body are missing), but never if an error was found during validation of the user-defined process (e.g. an unsupported process).
Specifies the user-defined process to be validated.
id | string Nullable ^\w+$ The identifier for the process. It MUST be unique across its namespace (e.g. pre-defined 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 pre-defined process. |
summary | string Nullable A short summary of what the process does. |
description | string <commonmark> Nullable 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: |
parameters | Array of objects Nullable 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)
|
returns | object Nullable The data that is returned from this process. |
categories | Array of strings (process_categories) A list of categories. |
deprecated | boolean (process_deprecated) Default: false Specifies that the process or parameter 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. For processes a link with relation type |
experimental | boolean (process_experimental) Default: false Declares the process or parameter to be 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. |
exceptions | object (Process Exceptions) Declares any 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. The keys define the error code and MUST match the following pattern:
This schema follows the schema of the general openEO error list (see errors.json). |
examples | Array of objects (Process Example) Examples, may be used for unit tests. |
links | Array of objects (Link) Links related to this process, e.g. additional external documentation.
It is RECOMMENDED to provide links with the following
|
process_graph 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. |
Returns the validation result as a list of errors. An empty list indicates a successful validation.
errors required | Array of objects (General Error) A list of validation errors. |
The request can't be fulfilled due to an error on client-side, i.e. the request is invalid. The client SHOULD NOT repeat the request without modifications.
The response body SHOULD contain a JSON error object. MUST be any HTTP status code specified in RFC 7231. This request MUST respond with HTTP status codes 401 if authorization is required or 403 if the authorization failed or access is forbidden in general to the authenticated user. HTTP status code 404 SHOULD be used if the value of a path parameter is invalid.
See also:
The request can't be fulfilled due to an error at the back-end. The error is never the client’s fault and therefore it is reasonable for the client to retry the exact same request that triggered this response.
The response body SHOULD contain a JSON error object. MUST be any HTTP status code specified in RFC 7231.
See also:
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": [
- {
- "name": "red",
- "description": "Value from the red band.",
- "schema": {
- "type": "number"
}
}, - {
- "name": "blue",
- "description": "Value from the blue band.",
- "schema": {
- "type": "number"
}
}, - {
- "name": "nir",
- "description": "Value from the near infrared band.",
- "schema": {
- "type": "number"
}
}
], - "returns": {
- "description": "Computed EVI.",
- "schema": {
- "type": "number"
}
}, - "process_graph": {
- "sub": {
- "process_id": "subtract",
- "arguments": {
- "x": {
- "from_parameter": "nir"
}, - "y": {
- "from_parameter": "red"
}
}
}, - "p1": {
- "process_id": "multiply",
- "arguments": {
- "x": 6,
- "y": {
- "from_parameter": "red"
}
}
}, - "p2": {
- "process_id": "multiply",
- "arguments": {
- "x": -7.5,
- "y": {
- "from_parameter": "blue"
}
}
}, - "sum": {
- "process_id": "sum",
- "arguments": {
- "data": [
- 1,
- {
- "from_parameter": "nir"
}, - {
- "from_node": "p1"
}, - {
- "from_node": "p2"
}
]
}
}, - "div": {
- "process_id": "divide",
- "arguments": {
- "x": {
- "from_node": "sub"
}, - "y": {
- "from_node": "sum"
}
}
}, - "p3": {
- "process_id": "multiply",
- "arguments": {
- "x": 2.5,
- "y": {
- "from_node": "div"
}
}, - "result": true
}
}
}
{- "errors": [
- {
- "id": "550e8400-e29b-11d4-a716-446655440000",
- "code": "SampleError",
- "message": "Parameter 'sample' is missing.",
}
]
}
The URL of the API MAY freely be chosen by the back-end providers. The path, including API versioning, is a recommendation only. Nevertheless, all servers MUST support HTTPS as the authentication methods are not secure with HTTP only!
This service 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 secondary web service clients MUST
request GET /services/{service_id}
.
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 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 |
JSON array with user-defined processes.
processes required | Array of objects (User-defined Process Metadata) Array of user-defined processes |
links required | Array of objects (links_pagination) Links related to this list of resources, for example links for pagination or alternative formats such as a human-readable HTML version. The links array MUST NOT be paginated. If pagination is implemented, the following
For additional relation types see also the lists of common relation types in openEO. |
The request can't be fulfilled due to an error on client-side, i.e. the request is invalid. The client SHOULD NOT repeat the request without modifications.
The response body SHOULD contain a JSON error object. MUST be any HTTP status code specified in RFC 7231. This request MUST respond with HTTP status codes 401 if authorization is required or 403 if the authorization failed or access is forbidden in general to the authenticated user. HTTP status code 404 SHOULD be used if the value of a path parameter is invalid.
See also:
The request can't be fulfilled due to an error at the back-end. The error is never the client’s fault and therefore it is reasonable for the client to retry the exact same request that triggered this response.
The response body SHOULD contain a JSON error object. MUST be any HTTP status code specified in RFC 7231.
See also:
{- "processes": [
- {
- "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": [
- {
- "name": "red",
- "description": "Value from the red band.",
- "schema": {
- "type": "number"
}
}, - {
- "name": "blue",
- "description": "Value from the blue band.",
- "schema": {
- "type": "number"
}
}, - {
- "name": "nir",
- "description": "Value from the near infrared band.",
- "schema": {
- "type": "number"
}
}
], - "returns": {
- "description": "Computed EVI.",
- "schema": {
- "type": "number"
}
}
}, - {
- "id": "ndsi",
- "summary": "Normalized-Difference Snow Index",
- "parameters": [
- {
- "name": "green",
- "description": "Value from the Visible Green (0.53 - 0.61 micrometers) band.",
- "schema": {
- "type": "number"
}
}, - {
- "name": "swir",
- "description": "Value from the Short Wave Infrared (1.55 - 1.75 micrometers) band.",
- "schema": {
- "type": "number"
}
}
], - "returns": {
- "schema": {
- "type": "number"
}
}
}, - {
- "id": "my_custom_process"
}
], - "links": [ ]
}
The URL of the API MAY freely be chosen by the back-end providers. The path, including API versioning, is a recommendation only. Nevertheless, all servers MUST support HTTPS as the authentication methods are not secure with HTTP only!
Returns all information about a user-defined process, including its process graph.
process_graph_id required | string (process_id) ^\w+$ Example: ndvi Unique identifier for a user-defined process. |
The user-defined process with process graph.
summary | string Nullable A short summary of what the process does. |
description | string <commonmark> Nullable 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: |
parameters | Array of objects Nullable 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)
|
returns | object Nullable The data that is returned from this process. |
id required | string (process_id) ^\w+$ The identifier for the process. It MUST be unique across its namespace (e.g. pre-defined 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 pre-defined process. |
categories | Array of strings (process_categories) A list of categories. |
deprecated | boolean (process_deprecated) Default: false Specifies that the process or parameter 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. For processes a link with relation type |
experimental | boolean (process_experimental) Default: false Declares the process or parameter to be 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. |
exceptions | object (Process Exceptions) Declares any 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. The keys define the error code and MUST match the following pattern:
This schema follows the schema of the general openEO error list (see errors.json). |
examples | Array of objects (Process Example) Examples, may be used for unit tests. |
links | Array of objects (Link) Links related to this process, e.g. additional external documentation.
It is RECOMMENDED to provide links with the following
|
process_graph 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. |
The request can't be fulfilled due to an error on client-side, i.e. the request is invalid. The client SHOULD NOT repeat the request without modifications.
The response body SHOULD contain a JSON error object. MUST be any HTTP status code specified in RFC 7231. This request MUST respond with HTTP status codes 401 if authorization is required or 403 if the authorization failed or access is forbidden in general to the authenticated user. HTTP status code 404 SHOULD be used if the value of a path parameter is invalid.
See also:
The request can't be fulfilled due to an error at the back-end. The error is never the client’s fault and therefore it is reasonable for the client to retry the exact same request that triggered this response.
The response body SHOULD contain a JSON error object. MUST be any HTTP status code specified in RFC 7231.
See also:
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": [
- {
- "name": "red",
- "description": "Value from the red band.",
- "schema": {
- "type": "number"
}
}, - {
- "name": "blue",
- "description": "Value from the blue band.",
- "schema": {
- "type": "number"
}
}, - {
- "name": "nir",
- "description": "Value from the near infrared band.",
- "schema": {
- "type": "number"
}
}
], - "returns": {
- "description": "Computed EVI.",
- "schema": {
- "type": "number"
}
}, - "process_graph": {
- "sub": {
- "process_id": "subtract",
- "arguments": {
- "x": {
- "from_parameter": "nir"
}, - "y": {
- "from_parameter": "red"
}
}
}, - "p1": {
- "process_id": "multiply",
- "arguments": {
- "x": 6,
- "y": {
- "from_parameter": "red"
}
}
}, - "p2": {
- "process_id": "multiply",
- "arguments": {
- "x": -7.5,
- "y": {
- "from_parameter": "blue"
}
}
}, - "sum": {
- "process_id": "sum",
- "arguments": {
- "data": [
- 1,
- {
- "from_parameter": "nir"
}, - {
- "from_node": "p1"
}, - {
- "from_node": "p2"
}
]
}
}, - "div": {
- "process_id": "divide",
- "arguments": {
- "x": {
- "from_node": "sub"
}, - "y": {
- "from_node": "sum"
}
}
}, - "p3": {
- "process_id": "multiply",
- "arguments": {
- "x": 2.5,
- "y": {
- "from_node": "div"
}
}, - "result": true
}
}
}
The URL of the API MAY freely be chosen by the back-end providers. The path, including API versioning, is a recommendation only. Nevertheless, all servers MUST support HTTPS as the authentication methods are not secure with HTTP only!
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 stored user-defined processes.
The id MUST be unique for the authenticated user, including all pre-defined processes by the back-end.
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.
process_graph_id required | string (process_id) ^\w+$ Example: ndvi Unique identifier for a user-defined process. |
Specifies the process graph with its meta data.
id | string Nullable ^\w+$ The identifier for the process. It MUST be unique across its namespace (e.g. pre-defined 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 pre-defined process. |
summary | string Nullable A short summary of what the process does. |
description | string <commonmark> Nullable 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: |
parameters | Array of objects Nullable 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)
|
returns | object Nullable The data that is returned from this process. |
categories | Array of strings (process_categories) A list of categories. |
deprecated | boolean (process_deprecated) Default: false Specifies that the process or parameter 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. For processes a link with relation type |
experimental | boolean (process_experimental) Default: false Declares the process or parameter to be 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. |
exceptions | object (Process Exceptions) Declares any 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. The keys define the error code and MUST match the following pattern:
This schema follows the schema of the general openEO error list (see errors.json). |
examples | Array of objects (Process Example) Examples, may be used for unit tests. |
links | Array of objects (Link) Links related to this process, e.g. additional external documentation.
It is RECOMMENDED to provide links with the following
|
process_graph 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. |
The user-defined process has been stored successfully.
The request can't be fulfilled due to an error on client-side, i.e. the request is invalid. The client SHOULD NOT repeat the request without modifications.
The response body SHOULD contain a JSON error object. MUST be any HTTP status code specified in RFC 7231. This request MUST respond with HTTP status codes 401 if authorization is required or 403 if the authorization failed or access is forbidden in general to the authenticated user. HTTP status code 404 SHOULD be used if the value of a path parameter is invalid.
See also:
The request can't be fulfilled due to an error at the back-end. The error is never the client’s fault and therefore it is reasonable for the client to retry the exact same request that triggered this response.
The response body SHOULD contain a JSON error object. MUST be any HTTP status code specified in RFC 7231.
See also:
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": [
- {
- "name": "red",
- "description": "Value from the red band.",
- "schema": {
- "type": "number"
}
}, - {
- "name": "blue",
- "description": "Value from the blue band.",
- "schema": {
- "type": "number"
}
}, - {
- "name": "nir",
- "description": "Value from the near infrared band.",
- "schema": {
- "type": "number"
}
}
], - "returns": {
- "description": "Computed EVI.",
- "schema": {
- "type": "number"
}
}, - "process_graph": {
- "sub": {
- "process_id": "subtract",
- "arguments": {
- "x": {
- "from_parameter": "nir"
}, - "y": {
- "from_parameter": "red"
}
}
}, - "p1": {
- "process_id": "multiply",
- "arguments": {
- "x": 6,
- "y": {
- "from_parameter": "red"
}
}
}, - "p2": {
- "process_id": "multiply",
- "arguments": {
- "x": -7.5,
- "y": {
- "from_parameter": "blue"
}
}
}, - "sum": {
- "process_id": "sum",
- "arguments": {
- "data": [
- 1,
- {
- "from_parameter": "nir"
}, - {
- "from_node": "p1"
}, - {
- "from_node": "p2"
}
]
}
}, - "div": {
- "process_id": "divide",
- "arguments": {
- "x": {
- "from_node": "sub"
}, - "y": {
- "from_node": "sum"
}
}
}, - "p3": {
- "process_id": "multiply",
- "arguments": {
- "x": 2.5,
- "y": {
- "from_node": "div"
}
}, - "result": true
}
}
}
{- "id": "550e8400-e29b-11d4-a716-446655440000",
- "code": "SampleError",
- "message": "Parameter 'sample' is missing.",
}
The URL of the API MAY freely be chosen by the back-end providers. The path, including API versioning, is a recommendation only. Nevertheless, all servers MUST support HTTPS as the authentication methods are not secure with HTTP only!
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.
process_graph_id required | string (process_id) ^\w+$ Example: ndvi Unique identifier for a user-defined process. |
The user-defined process has been successfully deleted
The request can't be fulfilled due to an error on client-side, i.e. the request is invalid. The client SHOULD NOT repeat the request without modifications.
The response body SHOULD contain a JSON error object. MUST be any HTTP status code specified in RFC 7231. This request MUST respond with HTTP status codes 401 if authorization is required or 403 if the authorization failed or access is forbidden in general to the authenticated user. HTTP status code 404 SHOULD be used if the value of a path parameter is invalid.
See also:
The request can't be fulfilled due to an error at the back-end. The error is never the client’s fault and therefore it is reasonable for the client to retry the exact same request that triggered this response.
The response body SHOULD contain a JSON error object. MUST be any HTTP status code specified in RFC 7231.
See also:
{- "id": "550e8400-e29b-11d4-a716-446655440000",
- "code": "SampleError",
- "message": "Parameter 'sample' is missing.",
}
Organizes and manages data processing on the back-end, either as synchronous on-demand computation or batch jobs.
The URL of the API MAY freely be chosen by the back-end providers. The path, including API versioning, is a recommendation only. Nevertheless, all servers MUST support HTTPS as the authentication methods are not secure with HTTP only!
The request will ask the back-end for 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 openEO. 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, openEO 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 are allowed to be case insensitive throughout the API.
An object with containing all input and output format separately. For each property input
and output
an object is defined where the file format names are the property keys and the property values are objects that define a title, supported parameters and related links.
input required | object (Input File Formats) Map of supported input file formats, i.e. file formats a back-end can read from. The property keys are the file format names that are used by clients and users, for example in process graphs. |
output required | object (Output File Formats) Map of supported output file formats, i.e. file formats a back-end can write to. The property keys are the file format names that are used by clients and users, for example in process graphs. |
The request can't be fulfilled due to an error on client-side, i.e. the request is invalid. The client SHOULD NOT repeat the request without modifications.
The response body SHOULD contain a JSON error object. MUST be any HTTP status code specified in RFC 7231. This request usually does not respond with HTTP status codes 401 and 403 due to missing authorization. HTTP status code 404 SHOULD be used if the value of a path parameter is invalid.
See also:
The request can't be fulfilled due to an error at the back-end. The error is never the client’s fault and therefore it is reasonable for the client to retry the exact same request that triggered this response.
The response body SHOULD contain a JSON error object. MUST be any HTTP status code specified in RFC 7231.
See also:
{- "output": {
- "GTiff": {
- "title": "GeoTiff",
- "description": "Export to GeoTiff. Doesn't support cloud-optimized GeoTiffs (COGs) yet.",
- "gis_data_types": [
- "raster"
], - "parameters": {
- "tiled": {
- "type": "boolean",
- "description": "This option can be used to force creation of tiled TIFF files [true]. By default [false] stripped TIFF files are created.",
- "default": false
}, - "compress": {
- "type": "string",
- "description": "Set the compression to use.",
- "default": "none",
- "enum": [
- "JPEG",
- "LZW",
- "DEFLATE",
- "NONE"
]
}, - "jpeg_quality": {
- "type": "integer",
- "description": "Set the JPEG quality when using JPEG.",
- "minimum": 1,
- "maximum": 100,
- "default": 75
}
}, - "links": [
- {
- "rel": "about",
- "title": "GDAL on the GeoTiff file format and storage options"
}
]
}, - "GPKG": {
- "title": "OGC GeoPackage",
- "gis_data_types": [
- "raster",
- "vector"
], - "parameters": {
- "version": {
- "type": "string",
- "description": "Set GeoPackage version. In AUTO mode, this will be equivalent to 1.2 starting with GDAL 2.3.",
- "enum": [
- "auto",
- "1",
- "1.1",
- "1.2"
], - "default": "auto"
}
}, - "links": [
- {
- "rel": "about",
- "title": "GDAL on GeoPackage for raster data"
}, - {
- "rel": "about",
- "title": "GDAL on GeoPackage for vector data"
}
]
}
}, - "input": {
- "GPKG": {
- "title": "OGC GeoPackage",
- "gis_data_types": [
- "raster",
- "vector"
], - "parameters": {
- "table": {
- "type": "string",
- "description": "**RASTER ONLY.** Name of the table containing the tiles. If the GeoPackage dataset only contains one table, this option is not necessary. Otherwise, it is required."
}
}, - "links": [
- {
- "rel": "about",
- "title": "GDAL on GeoPackage for raster data"
}, - {
- "rel": "about",
- "title": "GDAL on GeoPackage for vector data"
}
]
}
}
}
The URL of the API MAY freely be chosen by the back-end providers. The path, including API versioning, is a recommendation only. Nevertheless, all servers MUST support HTTPS as the authentication methods are not secure with HTTP only!
Validates a user-defined process without executing it. A user-defined process is
considered valid unless the errors
array in the response contains at
least one error.
Checks whether the process graph is schematically correct and the processes are supported by the back-end. It MUST also check the arguments against the schema, but checking whether the arguments are adequate in the context of data is OPTIONAL. For example, a non-existing band name may get rejected only by a few back-ends. The validation MUST NOT throw an error for unresolvable process parameters.
Back-ends MUST validate the process graph. Validating the corresponding metadata is OPTIONAL.
Errors that usually occur during processing MAY NOT get reported, e.g. if a referenced file is accessible at the time of execution.
Back-ends can either report all errors at once or stop the validation once they found the first error.
Please note that a validation always returns with HTTP status code 200. Error codes in the 4xx and 5xx ranges MUST be returned only when the general validation request is invalid (e.g. server is busy or properties in the request body are missing), but never if an error was found during validation of the user-defined process (e.g. an unsupported process).
Specifies the user-defined process to be validated.
id | string Nullable ^\w+$ The identifier for the process. It MUST be unique across its namespace (e.g. pre-defined 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 pre-defined process. |
summary | string Nullable A short summary of what the process does. |
description | string <commonmark> Nullable 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: |
parameters | Array of objects Nullable 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)
|
returns | object Nullable The data that is returned from this process. |
categories | Array of strings (process_categories) A list of categories. |
deprecated | boolean (process_deprecated) Default: false Specifies that the process or parameter 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. For processes a link with relation type |
experimental | boolean (process_experimental) Default: false Declares the process or parameter to be 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. |
exceptions | object (Process Exceptions) Declares any 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. The keys define the error code and MUST match the following pattern:
This schema follows the schema of the general openEO error list (see errors.json). |
examples | Array of objects (Process Example) Examples, may be used for unit tests. |
links | Array of objects (Link) Links related to this process, e.g. additional external documentation.
It is RECOMMENDED to provide links with the following
|
process_graph 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. |
Returns the validation result as a list of errors. An empty list indicates a successful validation.
errors required | Array of objects (General Error) A list of validation errors. |
The request can't be fulfilled due to an error on client-side, i.e. the request is invalid. The client SHOULD NOT repeat the request without modifications.
The response body SHOULD contain a JSON error object. MUST be any HTTP status code specified in RFC 7231. This request MUST respond with HTTP status codes 401 if authorization is required or 403 if the authorization failed or access is forbidden in general to the authenticated user. HTTP status code 404 SHOULD be used if the value of a path parameter is invalid.
See also:
The request can't be fulfilled due to an error at the back-end. The error is never the client’s fault and therefore it is reasonable for the client to retry the exact same request that triggered this response.
The response body SHOULD contain a JSON error object. MUST be any HTTP status code specified in RFC 7231.
See also:
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": [
- {
- "name": "red",
- "description": "Value from the red band.",
- "schema": {
- "type": "number"
}
}, - {
- "name": "blue",
- "description": "Value from the blue band.",
- "schema": {
- "type": "number"
}
}, - {
- "name": "nir",
- "description": "Value from the near infrared band.",
- "schema": {
- "type": "number"
}
}
], - "returns": {
- "description": "Computed EVI.",
- "schema": {
- "type": "number"
}
}, - "process_graph": {
- "sub": {
- "process_id": "subtract",
- "arguments": {
- "x": {
- "from_parameter": "nir"
}, - "y": {
- "from_parameter": "red"
}
}
}, - "p1": {
- "process_id": "multiply",
- "arguments": {
- "x": 6,
- "y": {
- "from_parameter": "red"
}
}
}, - "p2": {
- "process_id": "multiply",
- "arguments": {
- "x": -7.5,
- "y": {
- "from_parameter": "blue"
}
}
}, - "sum": {
- "process_id": "sum",
- "arguments": {
- "data": [
- 1,
- {
- "from_parameter": "nir"
}, - {
- "from_node": "p1"
}, - {
- "from_node": "p2"
}
]
}
}, - "div": {
- "process_id": "divide",
- "arguments": {
- "x": {
- "from_node": "sub"
}, - "y": {
- "from_node": "sum"
}
}
}, - "p3": {
- "process_id": "multiply",
- "arguments": {
- "x": 2.5,
- "y": {
- "from_node": "div"
}
}, - "result": true
}
}
}
{- "errors": [
- {
- "id": "550e8400-e29b-11d4-a716-446655440000",
- "code": "SampleError",
- "message": "Parameter 'sample' is missing.",
}
]
}
The URL of the API MAY freely be chosen by the back-end providers. The path, including API versioning, is a recommendation only. Nevertheless, all servers MUST support HTTPS as the authentication methods are not secure with HTTP only!
A user-defined process will be executed directly 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 openEO error ProcessGraphComplexity
immediately if the computation is expected to time out. Otherwise requests MAY time-out after a certain amount of time by sending openEO error RequestTimeout
.
A header named OpenEO-Costs
MAY be sent with all responses, which MUST include the costs for processing and downloading the data. Additionally, a link to a log file MAY be sent in the header.
Specifies the job details, e.g. the user-defined process and billing details.
process required | object (Process Graph with metadata) A process graph, optionally enriched with process metadata. |
budget | number (budget) Nullable Default: null Maximum amount of costs the request is allowed to produce. The value MUST be specified in the currency the back-end is working with. The currency can be retrieved by calling If possible, back-ends SHOULD reject jobs with openEO error Setting the budget to |
plan | string (billing_plan_defaultable) Nullable The billing plan to process and charge the job with. The plans and the default plan can be retrieved by calling Billing plans MUST be accepted case insensitive. Billing plans not on the list of available plans MUST be rejected with openEO error If no billing plan is specified by the client, the server MUST default to the default billing plan in |
Result data in the requested output format
Content-Type | string The appropriate media (MIME) type for the requested output format MUST be sent. |
OpenEO-Costs | number (money) Nullable Default: null Example: 12.98 MAY include the costs for processing and downloading the data. |
Link | string ^<[^>]+>;\s?rel="monitor" Example: "<https://example.openeo.org/api/logs/258489231>; rel=\"monitor\"" The header MAY indicate a link to a log file generated by the request. If provided, the link MUST be serialized according to RFC 8288 and MUST use the relation type |
The request can't be fulfilled due to an error on client-side, i.e. the request is invalid. The client SHOULD NOT repeat the request without modifications.
The response body SHOULD contain a JSON error object. MUST be any HTTP status code specified in RFC 7231. This request MUST respond with HTTP status codes 401 if authorization is required or 403 if the authorization failed or access is forbidden in general to the authenticated user. HTTP status code 404 SHOULD be used if the value of a path parameter is invalid.
See also:
The request can't be fulfilled due to an error at the back-end. The error is never the client’s fault and therefore it is reasonable for the client to retry the exact same request that triggered this response.
The response body SHOULD contain a JSON error object. MUST be any HTTP status code specified in RFC 7231.
See also:
{- "process": {
- "id": "ndvi",
- "summary": "string",
- "description": "string",
- "parameters": [
- {
- "schema": {
- "parameters": [
- {
- "schema": {
- "type": "array",
- "subtype": "string",
- "pattern": "string",
- "enum": [
- null
], - "minimum": 0,
- "maximum": 0,
- "minItems": 0,
- "maxItems": 0,
- "items": [
- { }
]
}, - "name": "string",
- "description": "string",
- "optional": false,
- "deprecated": false,
- "experimental": false,
- "default": null
}
], - "type": "array",
- "subtype": "string",
- "pattern": "string",
- "enum": [
- null
], - "minimum": 0,
- "maximum": 0,
- "minItems": 0,
- "maxItems": 0,
- "items": [
- { }
]
}, - "name": "string",
- "description": "string",
- "optional": false,
- "deprecated": false,
- "experimental": false,
- "default": null
}
], - "returns": {
- "description": "string",
- "schema": {
- "type": "array",
- "subtype": "string",
- "pattern": "string",
- "enum": [
- null
], - "minimum": 0,
- "maximum": 0,
- "minItems": 0,
- "maxItems": 0,
- "items": [
- { }
]
}
}, - "categories": [
- "string"
], - "deprecated": false,
- "experimental": false,
- "exceptions": {
- "property1": {
- "description": "string",
- "message": "The value specified for the process argument '{argument}' in process '{process}' is invalid: {reason}",
- "http": 400
}, - "property2": {
- "description": "string",
- "message": "The value specified for the process argument '{argument}' in process '{process}' is invalid: {reason}",
- "http": 400
}
}, - "examples": [
- {
- "title": "string",
- "description": "string",
- "arguments": {
- "property1": {
- "from_parameter": null,
- "from_node": null,
- "process_graph": null
}, - "property2": {
- "from_parameter": null,
- "from_node": null,
- "process_graph": null
}
}, - "returns": null
}
], - "links": [
], - "process_graph": {
- "dc": {
- "process_id": "load_collection",
- "arguments": {
- "id": "Sentinel-2",
- "spatial_extent": {
- "west": 16.1,
- "east": 16.6,
- "north": 48.6,
- "south": 47.2
}, - "temporal_extent": [
- "2018-01-01",
- "2018-02-01"
]
}
}, - "bands": {
- "process_id": "filter_bands",
- "description": "Filter and order the bands. The order is important for the following reduce operation.",
- "arguments": {
- "data": {
- "from_node": "dc"
}, - "bands": [
- "B08",
- "B04",
- "B02"
]
}
}, - "evi": {
- "process_id": "reduce",
- "description": "Compute the EVI. Formula: 2.5 * (NIR - RED) / (1 + NIR + 6*RED + -7.5*BLUE)",
- "arguments": {
- "data": {
- "from_node": "bands"
}, - "dimension": "bands",
- "reducer": {
- "process_graph": {
- "nir": {
- "process_id": "array_element",
- "arguments": {
- "data": {
- "from_parameter": "data"
}, - "index": 0
}
}, - "red": {
- "process_id": "array_element",
- "arguments": {
- "data": {
- "from_parameter": "data"
}, - "index": 1
}
}, - "blue": {
- "process_id": "array_element",
- "arguments": {
- "data": {
- "from_parameter": "data"
}, - "index": 2
}
}, - "sub": {
- "process_id": "subtract",
- "arguments": {
- "data": [
- {
- "from_node": "nir"
}, - {
- "from_node": "red"
}
]
}
}, - "p1": {
- "process_id": "product",
- "arguments": {
- "data": [
- 6,
- {
- "from_node": "red"
}
]
}
}, - "p2": {
- "process_id": "product",
- "arguments": {
- "data": [
- -7.5,
- {
- "from_node": "blue"
}
]
}
}, - "sum": {
- "process_id": "sum",
- "arguments": {
- "data": [
- 1,
- {
- "from_node": "nir"
}, - {
- "from_node": "p1"
}, - {
- "from_node": "p2"
}
]
}
}, - "div": {
- "process_id": "divide",
- "arguments": {
- "data": [
- {
- "from_node": "sub"
}, - {
- "from_node": "sum"
}
]
}
}, - "p3": {
- "process_id": "product",
- "arguments": {
- "data": [
- 2.5,
- {
- "from_node": "div"
}
]
}, - "result": true
}
}
}
}
}, - "mintime": {
- "process_id": "reduce",
- "description": "Compute a minimum time composite by reducing the temporal dimension",
- "arguments": {
- "data": {
- "from_node": "evi"
}, - "dimension": "temporal",
- "reducer": {
- "process_graph": {
- "min": {
- "process_id": "min",
- "arguments": {
- "data": {
- "from_parameter": "data"
}
}, - "result": true
}
}
}
}
}, - "save": {
- "process_id": "save_result",
- "arguments": {
- "data": {
- "from_node": "mintime"
}, - "format": "GTiff"
}, - "result": true
}
}
}, - "budget": 100,
- "plan": "free"
}
{- "id": "550e8400-e29b-11d4-a716-446655440000",
- "code": "SampleError",
- "message": "Parameter 'sample' is missing.",
}
The URL of the API MAY freely be chosen by the back-end providers. The path, including API versioning, is a recommendation only. Nevertheless, all servers MUST support HTTPS as the authentication methods are not secure with HTTP only!
Requests to this endpoint will list all batch jobs submitted by a user.
It is strongly RECOMMENDED to keep the response size small by
omitting all optional non-scalar values from objects in jobs
(i.e. the process
property).
To get the full metadata for a job clients MUST request GET /jobs/{job_id}
.
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 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 |
Array of job descriptions
jobs required | Array of objects (Batch Job) |
links required | Array of objects (links_pagination) Links related to this list of resources, for example links for pagination or alternative formats such as a human-readable HTML version. The links array MUST NOT be paginated. If pagination is implemented, the following
For additional relation types see also the lists of common relation types in openEO. |
The request can't be fulfilled due to an error on client-side, i.e. the request is invalid. The client SHOULD NOT repeat the request without modifications.
The response body SHOULD contain a JSON error object. MUST be any HTTP status code specified in RFC 7231. This request MUST respond with HTTP status codes 401 if authorization is required or 403 if the authorization failed or access is forbidden in general to the authenticated user. HTTP status code 404 SHOULD be used if the value of a path parameter is invalid.
See also:
The request can't be fulfilled due to an error at the back-end. The error is never the client’s fault and therefore it is reasonable for the client to retry the exact same request that triggered this response.
The response body SHOULD contain a JSON error object. MUST be any HTTP status code specified in RFC 7231.
See also:
{- "jobs": [
- {
- "id": "a3cca2b2aa1e3b5b",
- "title": "NDVI based on Sentinel 2",
- "description": "Deriving minimum NDVI measurements over pixel time series of Sentinel 2",
- "process": {
- "id": "ndvi",
- "summary": "string",
- "description": "string",
- "parameters": [
- {
- "schema": {
- "parameters": [
- {
- "schema": {
- "type": "array",
- "subtype": "string",
- "pattern": "string",
- "enum": [
- null
], - "minimum": 0,
- "maximum": 0,
- "minItems": 0,
- "maxItems": 0,
- "items": [
- { }
]
}, - "name": "string",
- "description": "string",
- "optional": false,
- "deprecated": false,
- "experimental": false,
- "default": null
}
], - "type": "array",
- "subtype": "string",
- "pattern": "string",
- "enum": [
- null
], - "minimum": 0,
- "maximum": 0,
- "minItems": 0,
- "maxItems": 0,
- "items": [
- { }
]
}, - "name": "string",
- "description": "string",
- "optional": false,
- "deprecated": false,
- "experimental": false,
- "default": null
}
], - "returns": {
- "description": "string",
- "schema": {
- "type": "array",
- "subtype": "string",
- "pattern": "string",
- "enum": [
- null
], - "minimum": 0,
- "maximum": 0,
- "minItems": 0,
- "maxItems": 0,
- "items": [
- { }
]
}
}, - "categories": [
- "string"
], - "deprecated": false,
- "experimental": false,
- "exceptions": {
- "property1": {
- "description": "string",
- "message": "The value specified for the process argument '{argument}' in process '{process}' is invalid: {reason}",
- "http": 400
}, - "property2": {
- "description": "string",
- "message": "The value specified for the process argument '{argument}' in process '{process}' is invalid: {reason}",
- "http": 400
}
}, - "examples": [
- {
- "title": "string",
- "description": "string",
- "arguments": {
- "property1": {
- "from_parameter": null,
- "from_node": null,
- "process_graph": null
}, - "property2": {
- "from_parameter": null,
- "from_node": null,
- "process_graph": null
}
}, - "returns": null
}
], - "links": [
], - "process_graph": {
- "dc": {
- "process_id": "load_collection",
- "arguments": {
- "id": "Sentinel-2",
- "spatial_extent": {
- "west": 16.1,
- "east": 16.6,
- "north": 48.6,
- "south": 47.2
}, - "temporal_extent": [
- "2018-01-01",
- "2018-02-01"
]
}
}, - "bands": {
- "process_id": "filter_bands",
- "description": "Filter and order the bands. The order is important for the following reduce operation.",
- "arguments": {
- "data": {
- "from_node": "dc"
}, - "bands": [
- "B08",
- "B04",
- "B02"
]
}
}, - "evi": {
- "process_id": "reduce",
- "description": "Compute the EVI. Formula: 2.5 * (NIR - RED) / (1 + NIR + 6*RED + -7.5*BLUE)",
- "arguments": {
- "data": {
- "from_node": "bands"
}, - "dimension": "bands",
- "reducer": {
- "process_graph": {
- "nir": {
- "process_id": "array_element",
- "arguments": {
- "data": {
- "from_parameter": "data"
}, - "index": 0
}
}, - "red": {
- "process_id": "array_element",
- "arguments": {
- "data": {
- "from_parameter": "data"
}, - "index": 1
}
}, - "blue": {
- "process_id": "array_element",
- "arguments": {
- "data": {
- "from_parameter": "data"
}, - "index": 2
}
}, - "sub": {
- "process_id": "subtract",
- "arguments": {
- "data": [
- {
- "from_node": "nir"
}, - {
- "from_node": "red"
}
]
}
}, - "p1": {
- "process_id": "product",
- "arguments": {
- "data": [
- 6,
- {
- "from_node": "red"
}
]
}
}, - "p2": {
- "process_id": "product",
- "arguments": {
- "data": [
- -7.5,
- {
- "from_node": "blue"
}
]
}
}, - "sum": {
- "process_id": "sum",
- "arguments": {
- "data": [
- 1,
- {
- "from_node": "nir"
}, - {
- "from_node": "p1"
}, - {
- "from_node": "p2"
}
]
}
}, - "div": {
- "process_id": "divide",
- "arguments": {
- "data": [
- {
- "from_node": "sub"
}, - {
- "from_node": "sum"
}
]
}
}, - "p3": {
- "process_id": "product",
- "arguments": {
- "data": [
- 2.5,
- {
- "from_node": "div"
}
]
}, - "result": true
}
}
}
}
}, - "mintime": {
- "process_id": "reduce",
- "description": "Compute a minimum time composite by reducing the temporal dimension",
- "arguments": {
- "data": {
- "from_node": "evi"
}, - "dimension": "temporal",
- "reducer": {
- "process_graph": {
- "min": {
- "process_id": "min",
- "arguments": {
- "data": {
- "from_parameter": "data"
}
}, - "result": true
}
}
}
}
}, - "save": {
- "process_id": "save_result",
- "arguments": {
- "data": {
- "from_node": "mintime"
}, - "format": "GTiff"
}, - "result": true
}
}
}, - "status": "running",
- "progress": 75.5,
- "created": "2017-01-01T09:32:12Z",
- "updated": "2017-01-01T09:36:18Z",
- "plan": "free",
- "costs": 12.98,
- "budget": 100
}
], - "links": [
]
}
The URL of the API MAY freely be chosen by the back-end providers. The path, including API versioning, is a recommendation only. Nevertheless, all servers MUST support HTTPS as the authentication methods are not secure with HTTP only!
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.
Specifies the job details, e.g. the user-defined process and billing details.
title | string (eo_title) Nullable A short description to easily distinguish entities. |
description | string <commonmark> (eo_description) Nullable Detailed multi-line description to explain the entity. CommonMark 0.29 syntax MAY be used for rich text representation. |
process required | object (Process Graph with metadata) A process graph, optionally enriched with process metadata. |
plan | string (billing_plan_defaultable) Nullable The billing plan to process and charge the job with. The plans and the default plan can be retrieved by calling Billing plans MUST be accepted case insensitive. Billing plans not on the list of available plans MUST be rejected with openEO error If no billing plan is specified by the client, the server MUST default to the default billing plan in |
budget | number (budget) Nullable Default: null Maximum amount of costs the request is allowed to produce. The value MUST be specified in the currency the back-end is working with. The currency can be retrieved by calling If possible, back-ends SHOULD reject jobs with openEO error Setting the budget to |
The batch job has been created successfully.
Location required | string <uri> Example: "https://example.openeo.org/api/jobs/123" Absolute URL to the newly created batch job. The URL points to the metadata endpoint
|
OpenEO-Identifier required | string (job_id) ^[\w\-\.~]+$ Example: "a3cca2b2aa1e3b5b" Unique identifier of the batch job, generated by the back-end during creation. MUST match the specified pattern. |
The request can't be fulfilled due to an error on client-side, i.e. the request is invalid. The client SHOULD NOT repeat the request without modifications.
The response body SHOULD contain a JSON error object. MUST be any HTTP status code specified in RFC 7231. This request MUST respond with HTTP status codes 401 if authorization is required or 403 if the authorization failed or access is forbidden in general to the authenticated user. HTTP status code 404 SHOULD be used if the value of a path parameter is invalid.
See also:
The request can't be fulfilled due to an error at the back-end. The error is never the client’s fault and therefore it is reasonable for the client to retry the exact same request that triggered this response.
The response body SHOULD contain a JSON error object. MUST be any HTTP status code specified in RFC 7231.
See also:
{- "title": "NDVI based on Sentinel 2",
- "description": "Deriving minimum NDVI measurements over pixel time series of Sentinel 2",
- "process": {
- "id": "ndvi",
- "summary": "string",
- "description": "string",
- "parameters": [
- {
- "schema": {
- "parameters": [
- {
- "schema": {
- "type": "array",
- "subtype": "string",
- "pattern": "string",
- "enum": [
- null
], - "minimum": 0,
- "maximum": 0,
- "minItems": 0,
- "maxItems": 0,
- "items": [
- { }
]
}, - "name": "string",
- "description": "string",
- "optional": false,
- "deprecated": false,
- "experimental": false,
- "default": null
}
], - "type": "array",
- "subtype": "string",
- "pattern": "string",
- "enum": [
- null
], - "minimum": 0,
- "maximum": 0,
- "minItems": 0,
- "maxItems": 0,
- "items": [
- { }
]
}, - "name": "string",
- "description": "string",
- "optional": false,
- "deprecated": false,
- "experimental": false,
- "default": null
}
], - "returns": {
- "description": "string",
- "schema": {
- "type": "array",
- "subtype": "string",
- "pattern": "string",
- "enum": [
- null
], - "minimum": 0,
- "maximum": 0,
- "minItems": 0,
- "maxItems": 0,
- "items": [
- { }
]
}
}, - "categories": [
- "string"
], - "deprecated": false,
- "experimental": false,
- "exceptions": {
- "property1": {
- "description": "string",
- "message": "The value specified for the process argument '{argument}' in process '{process}' is invalid: {reason}",
- "http": 400
}, - "property2": {
- "description": "string",
- "message": "The value specified for the process argument '{argument}' in process '{process}' is invalid: {reason}",
- "http": 400
}
}, - "examples": [
- {
- "title": "string",
- "description": "string",
- "arguments": {
- "property1": {
- "from_parameter": null,
- "from_node": null,
- "process_graph": null
}, - "property2": {
- "from_parameter": null,
- "from_node": null,
- "process_graph": null
}
}, - "returns": null
}
], - "links": [
], - "process_graph": {
- "dc": {
- "process_id": "load_collection",
- "arguments": {
- "id": "Sentinel-2",
- "spatial_extent": {
- "west": 16.1,
- "east": 16.6,
- "north": 48.6,
- "south": 47.2
}, - "temporal_extent": [
- "2018-01-01",
- "2018-02-01"
]
}
}, - "bands": {
- "process_id": "filter_bands",
- "description": "Filter and order the bands. The order is important for the following reduce operation.",
- "arguments": {
- "data": {
- "from_node": "dc"
}, - "bands": [
- "B08",
- "B04",
- "B02"
]
}
}, - "evi": {
- "process_id": "reduce",
- "description": "Compute the EVI. Formula: 2.5 * (NIR - RED) / (1 + NIR + 6*RED + -7.5*BLUE)",
- "arguments": {
- "data": {
- "from_node": "bands"
}, - "dimension": "bands",
- "reducer": {
- "process_graph": {
- "nir": {
- "process_id": "array_element",
- "arguments": {
- "data": {
- "from_parameter": "data"
}, - "index": 0
}
}, - "red": {
- "process_id": "array_element",
- "arguments": {
- "data": {
- "from_parameter": "data"
}, - "index": 1
}
}, - "blue": {
- "process_id": "array_element",
- "arguments": {
- "data": {
- "from_parameter": "data"
}, - "index": 2
}
}, - "sub": {
- "process_id": "subtract",
- "arguments": {
- "data": [
- {
- "from_node": "nir"
}, - {
- "from_node": "red"
}
]
}
}, - "p1": {
- "process_id": "product",
- "arguments": {
- "data": [
- 6,
- {
- "from_node": "red"
}
]
}
}, - "p2": {
- "process_id": "product",
- "arguments": {
- "data": [
- -7.5,
- {
- "from_node": "blue"
}
]
}
}, - "sum": {
- "process_id": "sum",
- "arguments": {
- "data": [
- 1,
- {
- "from_node": "nir"
}, - {
- "from_node": "p1"
}, - {
- "from_node": "p2"
}
]
}
}, - "div": {
- "process_id": "divide",
- "arguments": {
- "data": [
- {
- "from_node": "sub"
}, - {
- "from_node": "sum"
}
]
}
}, - "p3": {
- "process_id": "product",
- "arguments": {
- "data": [
- 2.5,
- {
- "from_node": "div"
}
]
}, - "result": true
}
}
}
}
}, - "mintime": {
- "process_id": "reduce",
- "description": "Compute a minimum time composite by reducing the temporal dimension",
- "arguments": {
- "data": {
- "from_node": "evi"
}, - "dimension": "temporal",
- "reducer": {
- "process_graph": {
- "min": {
- "process_id": "min",
- "arguments": {
- "data": {
- "from_parameter": "data"
}
}, - "result": true
}
}
}
}
}, - "save": {
- "process_id": "save_result",
- "arguments": {
- "data": {
- "from_node": "mintime"
}, - "format": "GTiff"
}, - "result": true
}
}
}, - "plan": "free",
- "budget": 100
}
{- "id": "550e8400-e29b-11d4-a716-446655440000",
- "code": "SampleError",
- "message": "Parameter 'sample' is missing.",
}
The URL of the API MAY freely be chosen by the back-end providers. The path, including API versioning, is a recommendation only. Nevertheless, all servers MUST support HTTPS as the authentication methods are not secure with HTTP only!
Modifies an existing job at the back-end but maintains the identifier. Changes can be grouped in a single request.
Jobs can only be modified when the job is not queued or running. Otherwise requests to this endpoint MUST be rejected with openEO error JobLocked
.
job_id required | string (job_id) ^[\w\-\.~]+$ Example: a3cca2b2aa1e3b5b Unique job identifier. |
Specifies the job details to update.
title | string (eo_title) Nullable A short description to easily distinguish entities. |
description | string <commonmark> (eo_description) Nullable Detailed multi-line description to explain the entity. CommonMark 0.29 syntax MAY be used for rich text representation. |
process | object (Process Graph with metadata) A process graph, optionally enriched with process metadata. |
plan | string (billing_plan_defaultable) Nullable The billing plan to process and charge the job with. The plans and the default plan can be retrieved by calling Billing plans MUST be accepted case insensitive. Billing plans not on the list of available plans MUST be rejected with openEO error If no billing plan is specified by the client, the server MUST default to the default billing plan in |
budget | number (budget) Nullable Default: null Maximum amount of costs the request is allowed to produce. The value MUST be specified in the currency the back-end is working with. The currency can be retrieved by calling If possible, back-ends SHOULD reject jobs with openEO error Setting the budget to |
Changes to the job applied successfully.
The request can't be fulfilled due to an error on client-side, i.e. the request is invalid. The client SHOULD NOT repeat the request without modifications.
The response body SHOULD contain a JSON error object. MUST be any HTTP status code specified in RFC 7231. This request MUST respond with HTTP status codes 401 if authorization is required or 403 if the authorization failed or access is forbidden in general to the authenticated user. HTTP status code 404 SHOULD be used if the value of a path parameter is invalid.
See also:
The request can't be fulfilled due to an error at the back-end. The error is never the client’s fault and therefore it is reasonable for the client to retry the exact same request that triggered this response.
The response body SHOULD contain a JSON error object. MUST be any HTTP status code specified in RFC 7231.
See also:
{- "title": "NDVI based on Sentinel 2",
- "description": "Deriving minimum NDVI measurements over pixel time series of Sentinel 2",
- "process": {
- "id": "ndvi",
- "summary": "string",
- "description": "string",
- "parameters": [
- {
- "schema": {
- "parameters": [
- {
- "schema": {
- "type": "array",
- "subtype": "string",
- "pattern": "string",
- "enum": [
- null
], - "minimum": 0,
- "maximum": 0,
- "minItems": 0,
- "maxItems": 0,
- "items": [
- { }
]
}, - "name": "string",
- "description": "string",
- "optional": false,
- "deprecated": false,
- "experimental": false,
- "default": null
}
], - "type": "array",
- "subtype": "string",
- "pattern": "string",
- "enum": [
- null
], - "minimum": 0,
- "maximum": 0,
- "minItems": 0,
- "maxItems": 0,
- "items": [
- { }
]
}, - "name": "string",
- "description": "string",
- "optional": false,
- "deprecated": false,
- "experimental": false,
- "default": null
}
], - "returns": {
- "description": "string",
- "schema": {
- "type": "array",
- "subtype": "string",
- "pattern": "string",
- "enum": [
- null
], - "minimum": 0,
- "maximum": 0,
- "minItems": 0,
- "maxItems": 0,
- "items": [
- { }
]
}
}, - "categories": [
- "string"
], - "deprecated": false,
- "experimental": false,
- "exceptions": {
- "property1": {
- "description": "string",
- "message": "The value specified for the process argument '{argument}' in process '{process}' is invalid: {reason}",
- "http": 400
}, - "property2": {
- "description": "string",
- "message": "The value specified for the process argument '{argument}' in process '{process}' is invalid: {reason}",
- "http": 400
}
}, - "examples": [
- {
- "title": "string",
- "description": "string",
- "arguments": {
- "property1": {
- "from_parameter": null,
- "from_node": null,
- "process_graph": null
}, - "property2": {
- "from_parameter": null,
- "from_node": null,
- "process_graph": null
}
}, - "returns": null
}
], - "links": [
], - "process_graph": {
- "dc": {
- "process_id": "load_collection",
- "arguments": {
- "id": "Sentinel-2",
- "spatial_extent": {
- "west": 16.1,
- "east": 16.6,
- "north": 48.6,
- "south": 47.2
}, - "temporal_extent": [
- "2018-01-01",
- "2018-02-01"
]
}
}, - "bands": {
- "process_id": "filter_bands",
- "description": "Filter and order the bands. The order is important for the following reduce operation.",
- "arguments": {
- "data": {
- "from_node": "dc"
}, - "bands": [
- "B08",
- "B04",
- "B02"
]
}
}, - "evi": {
- "process_id": "reduce",
- "description": "Compute the EVI. Formula: 2.5 * (NIR - RED) / (1 + NIR + 6*RED + -7.5*BLUE)",
- "arguments": {
- "data": {
- "from_node": "bands"
}, - "dimension": "bands",
- "reducer": {
- "process_graph": {
- "nir": {
- "process_id": "array_element",
- "arguments": {
- "data": {
- "from_parameter": "data"
}, - "index": 0
}
}, - "red": {
- "process_id": "array_element",
- "arguments": {
- "data": {
- "from_parameter": "data"
}, - "index": 1
}
}, - "blue": {
- "process_id": "array_element",
- "arguments": {
- "data": {
- "from_parameter": "data"
}, - "index": 2
}
}, - "sub": {
- "process_id": "subtract",
- "arguments": {
- "data": [
- {
- "from_node": "nir"
}, - {
- "from_node": "red"
}
]
}
}, - "p1": {
- "process_id": "product",
- "arguments": {
- "data": [
- 6,
- {
- "from_node": "red"
}
]
}
}, - "p2": {
- "process_id": "product",
- "arguments": {
- "data": [
- -7.5,
- {
- "from_node": "blue"
}
]
}
}, - "sum": {
- "process_id": "sum",
- "arguments": {
- "data": [
- 1,
- {
- "from_node": "nir"
}, - {
- "from_node": "p1"
}, - {
- "from_node": "p2"
}
]
}
}, - "div": {
- "process_id": "divide",
- "arguments": {
- "data": [
- {
- "from_node": "sub"
}, - {
- "from_node": "sum"
}
]
}
}, - "p3": {
- "process_id": "product",
- "arguments": {
- "data": [
- 2.5,
- {
- "from_node": "div"
}
]
}, - "result": true
}
}
}
}
}, - "mintime": {
- "process_id": "reduce",
- "description": "Compute a minimum time composite by reducing the temporal dimension",
- "arguments": {
- "data": {
- "from_node": "evi"
}, - "dimension": "temporal",
- "reducer": {
- "process_graph": {
- "min": {
- "process_id": "min",
- "arguments": {
- "data": {
- "from_parameter": "data"
}
}, - "result": true
}
}
}
}
}, - "save": {
- "process_id": "save_result",
- "arguments": {
- "data": {
- "from_node": "mintime"
}, - "format": "GTiff"
}, - "result": true
}
}
}, - "plan": "free",
- "budget": 100
}
{- "id": "550e8400-e29b-11d4-a716-446655440000",
- "code": "SampleError",
- "message": "Parameter 'sample' is missing.",
}
The URL of the API MAY freely be chosen by the back-end providers. The path, including API versioning, is a recommendation only. Nevertheless, all servers MUST support HTTPS as the authentication methods are not secure with HTTP only!
Returns all information about a submitted batch job.
job_id required | string (job_id) ^[\w\-\.~]+$ Example: a3cca2b2aa1e3b5b Unique job identifier. |
Full job information.
id required | string (job_id) ^[\w\-\.~]+$ Unique identifier of the batch job, generated by the back-end during creation. MUST match the specified pattern. |
title | string (eo_title) Nullable A short description to easily distinguish entities. |
description | string <commonmark> (eo_description) Nullable Detailed multi-line description to explain the entity. CommonMark 0.29 syntax MAY be used for rich text representation. |
process required | object (Process Graph with metadata) A process graph, optionally enriched with process metadata. |
status required | string Default: "created" Enum: "created" "queued" "running" "canceled" "finished" "error" The current status of a batch job. The following status changes can occur:
|
progress | number [ 0 .. 100 ] Indicates the process of a running batch job in percent.
Can also be set for a job which stopped due to an error or was canceled by the user. In this case, the value indicates the progress at which the job stopped. The Property may not be available for the status codes |
created required | string <date-time> (created) Date and time of creation, formatted as a RFC 3339 date-time. |
updated | string <date-time> (updated) Date and time of last status change, formatted as a RFC 3339 date-time. |
plan | string (billing_plan) The billing plan to process and charge the job with. The plans can be retrieved by calling |
costs | number (money) Nullable Default: null An amount of money or credits. The value MUST be specified in the currency the back-end is working with. The currency can be retrieved by calling |
budget | number (budget) Nullable Default: null Maximum amount of costs the request is allowed to produce. The value MUST be specified in the currency the back-end is working with. The currency can be retrieved by calling If possible, back-ends SHOULD reject jobs with openEO error Setting the budget to |
The request can't be fulfilled due to an error on client-side, i.e. the request is invalid. The client SHOULD NOT repeat the request without modifications.
The response body SHOULD contain a JSON error object. MUST be any HTTP status code specified in RFC 7231. This request MUST respond with HTTP status codes 401 if authorization is required or 403 if the authorization failed or access is forbidden in general to the authenticated user. HTTP status code 404 SHOULD be used if the value of a path parameter is invalid.
See also:
The request can't be fulfilled due to an error at the back-end. The error is never the client’s fault and therefore it is reasonable for the client to retry the exact same request that triggered this response.
The response body SHOULD contain a JSON error object. MUST be any HTTP status code specified in RFC 7231.
See also:
{- "id": "a3cca2b2aa1e3b5b",
- "title": "NDVI based on Sentinel 2",
- "description": "Deriving minimum NDVI measurements over pixel time series of Sentinel 2",
- "process": {
- "id": "ndvi",
- "summary": "string",
- "description": "string",
- "parameters": [
- {
- "schema": {
- "parameters": [
- {
- "schema": {
- "type": "array",
- "subtype": "string",
- "pattern": "string",
- "enum": [
- null
], - "minimum": 0,
- "maximum": 0,
- "minItems": 0,
- "maxItems": 0,
- "items": [
- { }
]
}, - "name": "string",
- "description": "string",
- "optional": false,
- "deprecated": false,
- "experimental": false,
- "default": null
}
], - "type": "array",
- "subtype": "string",
- "pattern": "string",
- "enum": [
- null
], - "minimum": 0,
- "maximum": 0,
- "minItems": 0,
- "maxItems": 0,
- "items": [
- { }
]
}, - "name": "string",
- "description": "string",
- "optional": false,
- "deprecated": false,
- "experimental": false,
- "default": null
}
], - "returns": {
- "description": "string",
- "schema": {
- "type": "array",
- "subtype": "string",
- "pattern": "string",
- "enum": [
- null
], - "minimum": 0,
- "maximum": 0,
- "minItems": 0,
- "maxItems": 0,
- "items": [
- { }
]
}
}, - "categories": [
- "string"
], - "deprecated": false,
- "experimental": false,
- "exceptions": {
- "property1": {
- "description": "string",
- "message": "The value specified for the process argument '{argument}' in process '{process}' is invalid: {reason}",
- "http": 400
}, - "property2": {
- "description": "string",
- "message": "The value specified for the process argument '{argument}' in process '{process}' is invalid: {reason}",
- "http": 400
}
}, - "examples": [
- {
- "title": "string",
- "description": "string",
- "arguments": {
- "property1": {
- "from_parameter": null,
- "from_node": null,
- "process_graph": null
}, - "property2": {
- "from_parameter": null,
- "from_node": null,
- "process_graph": null
}
}, - "returns": null
}
], - "links": [
], - "process_graph": {
- "dc": {
- "process_id": "load_collection",
- "arguments": {
- "id": "Sentinel-2",
- "spatial_extent": {
- "west": 16.1,
- "east": 16.6,
- "north": 48.6,
- "south": 47.2
}, - "temporal_extent": [
- "2018-01-01",
- "2018-02-01"
]
}
}, - "bands": {
- "process_id": "filter_bands",
- "description": "Filter and order the bands. The order is important for the following reduce operation.",
- "arguments": {
- "data": {
- "from_node": "dc"
}, - "bands": [
- "B08",
- "B04",
- "B02"
]
}
}, - "evi": {
- "process_id": "reduce",
- "description": "Compute the EVI. Formula: 2.5 * (NIR - RED) / (1 + NIR + 6*RED + -7.5*BLUE)",
- "arguments": {
- "data": {
- "from_node": "bands"
}, - "dimension": "bands",
- "reducer": {
- "process_graph": {
- "nir": {
- "process_id": "array_element",
- "arguments": {
- "data": {
- "from_parameter": "data"
}, - "index": 0
}
}, - "red": {
- "process_id": "array_element",
- "arguments": {
- "data": {
- "from_parameter": "data"
}, - "index": 1
}
}, - "blue": {
- "process_id": "array_element",
- "arguments": {
- "data": {
- "from_parameter": "data"
}, - "index": 2
}
}, - "sub": {
- "process_id": "subtract",
- "arguments": {
- "data": [
- {
- "from_node": "nir"
}, - {
- "from_node": "red"
}
]
}
}, - "p1": {
- "process_id": "product",
- "arguments": {
- "data": [
- 6,
- {
- "from_node": "red"
}
]
}
}, - "p2": {
- "process_id": "product",
- "arguments": {
- "data": [
- -7.5,
- {
- "from_node": "blue"
}
]
}
}, - "sum": {
- "process_id": "sum",
- "arguments": {
- "data": [
- 1,
- {
- "from_node": "nir"
}, - {
- "from_node": "p1"
}, - {
- "from_node": "p2"
}
]
}
}, - "div": {
- "process_id": "divide",
- "arguments": {
- "data": [
- {
- "from_node": "sub"
}, - {
- "from_node": "sum"
}
]
}
}, - "p3": {
- "process_id": "product",
- "arguments": {
- "data": [
- 2.5,
- {
- "from_node": "div"
}
]
}, - "result": true
}
}
}
}
}, - "mintime": {
- "process_id": "reduce",
- "description": "Compute a minimum time composite by reducing the temporal dimension",
- "arguments": {
- "data": {
- "from_node": "evi"
}, - "dimension": "temporal",
- "reducer": {
- "process_graph": {
- "min": {
- "process_id": "min",
- "arguments": {
- "data": {
- "from_parameter": "data"
}
}, - "result": true
}
}
}
}
}, - "save": {
- "process_id": "save_result",
- "arguments": {
- "data": {
- "from_node": "mintime"
}, - "format": "GTiff"
}, - "result": true
}
}
}, - "status": "running",
- "progress": 75.5,
- "created": "2017-01-01T09:32:12Z",
- "updated": "2017-01-01T09:36:18Z",
- "plan": "free",
- "costs": 12.98,
- "budget": 100
}
The URL of the API MAY freely be chosen by the back-end providers. The path, including API versioning, is a recommendation only. Nevertheless, all servers MUST support HTTPS as the authentication methods are not secure with HTTP only!
Deletes all data related to this job. Computations are stopped and computed results are deleted. This job won't generate additional costs for processing.
job_id required | string (job_id) ^[\w\-\.~]+$ Example: a3cca2b2aa1e3b5b Unique job identifier. |
The job has been successfully deleted.
The request can't be fulfilled due to an error on client-side, i.e. the request is invalid. The client SHOULD NOT repeat the request without modifications.
The response body SHOULD contain a JSON error object. MUST be any HTTP status code specified in RFC 7231. This request MUST respond with HTTP status codes 401 if authorization is required or 403 if the authorization failed or access is forbidden in general to the authenticated user. HTTP status code 404 SHOULD be used if the value of a path parameter is invalid.
See also:
The request can't be fulfilled due to an error at the back-end. The error is never the client’s fault and therefore it is reasonable for the client to retry the exact same request that triggered this response.
The response body SHOULD contain a JSON error object. MUST be any HTTP status code specified in RFC 7231.
See also:
{- "id": "550e8400-e29b-11d4-a716-446655440000",
- "code": "SampleError",
- "message": "Parameter 'sample' is missing.",
}
The URL of the API MAY freely be chosen by the back-end providers. The path, including API versioning, is a recommendation only. Nevertheless, all servers MUST support HTTPS as the authentication methods are not secure with HTTP only!
Clients can ask for an estimate for a batch job. Back-ends can decide to either calculate the duration, the costs, the size or a combination of them. This MUST be the upper limit of the incurring costs. Clients can be charged less than specified, but never more. Back-end providers MAY specify an expiry time for the estimate. Starting to process data afterwards MAY be charged at a higher cost. Costs MAY NOT include downloading costs. This can be indicated with the downloads_included
flag.
job_id required | string (job_id) ^[\w\-\.~]+$ Example: a3cca2b2aa1e3b5b Unique job identifier. |
The estimated costs with regard to money, processing time and storage capacity. At least one of costs
, duration
or size
MUST be provided.
costs | number (money) Nullable Default: null An amount of money or credits. The value MUST be specified in the currency the back-end is working with. The currency can be retrieved by calling |
duration | string Estimated duration for the operation. Duration MUST be specified as a ISO 8601 duration. |
size | integer Estimated required storage capacity, i.e. the size of the generated files. Size MUST be specified in bytes. |
downloads_included | integer Nullable Default: null Specifies how many full downloads of the processed data are included in the estimate. Set to |
expires | string <date-time> Time until which the estimate is valid, formatted as a RFC 3339 date-time. |
The request can't be fulfilled due to an error on client-side, i.e. the request is invalid. The client SHOULD NOT repeat the request without modifications.
The response body SHOULD contain a JSON error object. MUST be any HTTP status code specified in RFC 7231. This request MUST respond with HTTP status codes 401 if authorization is required or 403 if the authorization failed or access is forbidden in general to the authenticated user. HTTP status code 404 SHOULD be used if the value of a path parameter is invalid.
See also:
The request can't be fulfilled due to an error at the back-end. The error is never the client’s fault and therefore it is reasonable for the client to retry the exact same request that triggered this response.
The response body SHOULD contain a JSON error object. MUST be any HTTP status code specified in RFC 7231.
See also:
{- "costs": 12.98,
- "duration": "P1Y2M10DT2H30M",
- "size": 157286400,
- "downloads_included": 5,
- "expires": "2020-11-01T00:00:00Z"
}
The URL of the API MAY freely be chosen by the back-end providers. The path, including API versioning, is a recommendation only. Nevertheless, all servers MUST support HTTPS as the authentication methods are not secure with HTTP only!
Shows 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 debug
.
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.
job_id required | string (job_id) ^[\w\-\.~]+$ Example: a3cca2b2aa1e3b5b Unique job identifier. |
offset | string Example: offset=log1234 The last identifier (property |
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 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 |
Lists the requested log entries.
logs required | Array of objects (Log Entry) |
links required | Array of objects (links_pagination) Links related to this list of resources, for example links for pagination or alternative formats such as a human-readable HTML version. The links array MUST NOT be paginated. If pagination is implemented, the following
For additional relation types see also the lists of common relation types in openEO. |
The request can't be fulfilled due to an error on client-side, i.e. the request is invalid. The client SHOULD NOT repeat the request without modifications.
The response body SHOULD contain a JSON error object. MUST be any HTTP status code specified in RFC 7231. This request MUST respond with HTTP status codes 401 if authorization is required or 403 if the authorization failed or access is forbidden in general to the authenticated user. HTTP status code 404 SHOULD be used if the value of a path parameter is invalid.
See also:
The request can't be fulfilled due to an error at the back-end. The error is never the client’s fault and therefore it is reasonable for the client to retry the exact same request that triggered this response.
The response body SHOULD contain a JSON error object. MUST be any HTTP status code specified in RFC 7231.
See also:
{- "logs": [
- {
- "id": "1",
- "code": "SampleError",
- "level": "error",
- "message": "Can't load the UDF file from the URL `https://example.com/invalid/file.txt`. Server responded with error 404.",
- "data": null,
- "path": [
- {
- "node_id": "runudf1",
- "process_id": "ndvi",
- "namespace": null,
- "parameter": "udf"
}
],
}
], - "links": [
]
}
The URL of the API MAY freely be chosen by the back-end providers. The path, including API versioning, is a recommendation only. Nevertheless, all servers MUST support HTTPS as the authentication methods are not secure with HTTP only!
After finishing processing, this request will provide signed URLs to the processed files of the batch job with some additional metadata. The response is a STAC Item (version 0.9.0) if it has spatial and temporal references included.
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.
If processing has not finished yet requests to this endpoint MUST be rejected with openEO error JobNotFinished
.
job_id required | string (job_id) ^[\w\-\.~]+$ Example: a3cca2b2aa1e3b5b Unique job identifier. |
Valid download links have been returned. The download links doesn't necessarily need to be located under the API base url.
OpenEO-Costs | number (money) Nullable Default: null Example: 12.98 Specifies the costs for fully downloading the data once, i.e. this header MAY change in subsequent calls. It MUST be set to |
stac_version required | string (stac_version) The version of the STAC specification, which MAY not be equal to the STAC API version. Supports versions 0.9.x and 1.x.x. |
stac_extensions | Array of Reference to a JSON Schema (string) or Reference to a core extension (string) (stac_extensions) A list of implemented STAC extensions. The list contains URLs to the JSON Schema files it can be validated against. For official extensions, a "shortcut" can be used. This means you can specify the folder name of the extension in the STAC repository, for example |
id required | string (job_id) ^[\w\-\.~]+$ Unique identifier of the batch job, generated by the back-end during creation. MUST match the specified pattern. |
type required | string Value: "Feature" |
bbox | Array of 4 elements (numbers) or Array of 6 elements (numbers) Potential spatial extent covered by the data. The bounding box is provided as four or six numbers. Six numbers are specified, if the coordinate reference system includes a vertical axis (height or depth). The order of the elements in the array:
The coordinate reference system of the values is WGS84 longitude/latitude. Specifying the |
geometry required | object Nullable Defines the full footprint of the asset represented by this item as GeoJSON Geometry. Results without a known location can set this value to |
properties required | object (Item Properties) MAY contain any additional properties, e.g. other STAC Item properties, properties from STAC extensions or custom properties. |
assets required | object (Assets) Dictionary of asset objects for data that can be downloaded, each with a unique key. The keys MAY be used by clients as file names. It is RECOMMENDED to link to a copy of this STAC Item with relative links in the assets, which allows users to easily publish their processed data with a basic set of metadata. |
links required | Array of objects (Link) Links related to this batch job result, e.g. a link to an invoice, additional log files or external documentation.
The links MUST NOT contain links to the processed and downloadable data. Instead specify these in the |
The request can't be fulfilled as the batch job failed. This request will deliver the last error message that was produced by the batch job.
This HTTP code MUST be sent only when the job status
is error
.
The request can't be fulfilled due to an error on client-side, i.e. the request is invalid. The client SHOULD NOT repeat the request without modifications.
The response body SHOULD contain a JSON error object. MUST be any HTTP status code specified in RFC 7231. This request MUST respond with HTTP status codes 401 if authorization is required or 403 if the authorization failed or access is forbidden in general to the authenticated user. HTTP status code 404 SHOULD be used if the value of a path parameter is invalid.
See also:
The request can't be fulfilled due to an error at the back-end. The error is never the client’s fault and therefore it is reasonable for the client to retry the exact same request that triggered this response.
The response body SHOULD contain a JSON error object. MUST be any HTTP status code specified in RFC 7231.
See also:
{- "stac_version": "string",
- "id": "a3cca2b2aa1e3b5b",
- "type": "Feature",
- "bbox": [
- -180,
- -90,
- 180,
- 90
], - "geometry": {
- "type": "Polygon",
- "coordinates": [
- [
- [
- -180,
- -90
], - [
- 180,
- -90
], - [
- 180,
- 90
], - [
- -180,
- 90
], - [
- -180,
- -90
]
]
]
}, - "properties": {
- "datetime": "2020-07-17T12:18:31Z",
- "start_datetime": "2020-07-17T12:18:31Z",
- "end_datetime": "2020-07-17T12:18:31Z",
- "title": "NDVI based on Sentinel 2",
- "description": "Deriving minimum NDVI measurements over pixel time series of Sentinel 2",
- "license": "Apache-2.0",
- "providers": [
- {
- "name": "Cool EO Cloud Corp",
- "description": "No further processing applied.",
- "roles": [
- "producer",
- "licensor",
- "host"
],
}
], - "created": "2017-01-01T09:32:12Z",
- "updated": "2017-01-01T09:36:18Z",
- "expires": "2020-11-01T00:00:00Z"
}, - "assets": {
- "preview.png": {
- "type": "image/png",
- "title": "Thumbnail",
- "roles": [
- "thumbnail"
]
}, - "process.json": {
- "type": "application/json",
- "title": "Original Process",
- "roles": [
- "process",
- "reproduction"
]
}, - "1.tif": {
- "type": "image/tiff; application=geotiff",
- "title": "Band 1",
- "roles": [
- "data"
]
}, - "2.tif": {
- "type": "image/tiff; application=geotiff",
- "title": "Band 2",
- "roles": [
- "data"
]
}, - "inspire.xml": {
- "type": "application/xml",
- "title": "INSPIRE metadata",
- "description": "INSPIRE compliant XML metadata",
- "roles": [
- "metadata"
]
}
}, - "links": [
]
}
The URL of the API MAY freely be chosen by the back-end providers. The path, including API versioning, is a recommendation only. Nevertheless, all servers MUST support HTTPS as the authentication methods are not secure with HTTP only!
Adds a batch job to the processing queue to compute the results.
The result will be stored in the format specified in the process graph. To specify the format use a process such as save_result
.
This endpoint has no effect if the job status is already queued
or running
. In particular, it doesn't restart a running job. Processing MUST be canceled before to restart it.
The job status is set to queued
, if processing doesn't start instantly.
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
.
job_id required | string (job_id) ^[\w\-\.~]+$ Example: a3cca2b2aa1e3b5b Unique job identifier. |
The creation of the resource has been queued successfully.
The request can't be fulfilled due to an error on client-side, i.e. the request is invalid. The client SHOULD NOT repeat the request without modifications.
The response body SHOULD contain a JSON error object. MUST be any HTTP status code specified in RFC 7231. This request MUST respond with HTTP status codes 401 if authorization is required or 403 if the authorization failed or access is forbidden in general to the authenticated user. HTTP status code 404 SHOULD be used if the value of a path parameter is invalid.
See also:
The request can't be fulfilled due to an error at the back-end. The error is never the client’s fault and therefore it is reasonable for the client to retry the exact same request that triggered this response.
The response body SHOULD contain a JSON error object. MUST be any HTTP status code specified in RFC 7231.
See also:
{- "id": "550e8400-e29b-11d4-a716-446655440000",
- "code": "SampleError",
- "message": "Parameter 'sample' is missing.",
}
The URL of the API MAY freely be chosen by the back-end providers. The path, including API versioning, is a recommendation only. Nevertheless, all servers MUST support HTTPS as the authentication methods are not secure with HTTP only!
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 as it was canceled. Finished results MUST NOT be deleted until the job is deleted or job processing is started again.
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
.
job_id required | string (job_id) ^[\w\-\.~]+$ Example: a3cca2b2aa1e3b5b Unique job identifier. |
Processing the job has been successfully canceled.
The request can't be fulfilled due to an error on client-side, i.e. the request is invalid. The client SHOULD NOT repeat the request without modifications.
The response body SHOULD contain a JSON error object. MUST be any HTTP status code specified in RFC 7231. This request MUST respond with HTTP status codes 401 if authorization is required or 403 if the authorization failed or access is forbidden in general to the authenticated user. HTTP status code 404 SHOULD be used if the value of a path parameter is invalid.
See also:
The request can't be fulfilled due to an error at the back-end. The error is never the client’s fault and therefore it is reasonable for the client to retry the exact same request that triggered this response.
The response body SHOULD contain a JSON error object. MUST be any HTTP status code specified in RFC 7231.
See also:
{- "id": "550e8400-e29b-11d4-a716-446655440000",
- "code": "SampleError",
- "message": "Parameter 'sample' is missing.",
}
The URL of the API MAY freely be chosen by the back-end providers. The path, including API versioning, is a recommendation only. Nevertheless, all servers MUST support HTTPS as the authentication methods are not secure with HTTP only!
Requests to this endpoint will list all batch jobs submitted by a user.
It is strongly RECOMMENDED to keep the response size small by
omitting all optional non-scalar values from objects in jobs
(i.e. the process
property).
To get the full metadata for a job clients MUST request GET /jobs/{job_id}
.
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 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 |
Array of job descriptions
jobs required | Array of objects (Batch Job) |
links required | Array of objects (links_pagination) Links related to this list of resources, for example links for pagination or alternative formats such as a human-readable HTML version. The links array MUST NOT be paginated. If pagination is implemented, the following
For additional relation types see also the lists of common relation types in openEO. |
The request can't be fulfilled due to an error on client-side, i.e. the request is invalid. The client SHOULD NOT repeat the request without modifications.
The response body SHOULD contain a JSON error object. MUST be any HTTP status code specified in RFC 7231. This request MUST respond with HTTP status codes 401 if authorization is required or 403 if the authorization failed or access is forbidden in general to the authenticated user. HTTP status code 404 SHOULD be used if the value of a path parameter is invalid.
See also:
The request can't be fulfilled due to an error at the back-end. The error is never the client’s fault and therefore it is reasonable for the client to retry the exact same request that triggered this response.
The response body SHOULD contain a JSON error object. MUST be any HTTP status code specified in RFC 7231.
See also:
{- "jobs": [
- {
- "id": "a3cca2b2aa1e3b5b",
- "title": "NDVI based on Sentinel 2",
- "description": "Deriving minimum NDVI measurements over pixel time series of Sentinel 2",
- "process": {
- "id": "ndvi",
- "summary": "string",
- "description": "string",
- "parameters": [
- {
- "schema": {
- "parameters": [
- {
- "schema": {
- "type": "array",
- "subtype": "string",
- "pattern": "string",
- "enum": [
- null
], - "minimum": 0,
- "maximum": 0,
- "minItems": 0,
- "maxItems": 0,
- "items": [
- { }
]
}, - "name": "string",
- "description": "string",
- "optional": false,
- "deprecated": false,
- "experimental": false,
- "default": null
}
], - "type": "array",
- "subtype": "string",
- "pattern": "string",
- "enum": [
- null
], - "minimum": 0,
- "maximum": 0,
- "minItems": 0,
- "maxItems": 0,
- "items": [
- { }
]
}, - "name": "string",
- "description": "string",
- "optional": false,
- "deprecated": false,
- "experimental": false,
- "default": null
}
], - "returns": {
- "description": "string",
- "schema": {
- "type": "array",
- "subtype": "string",
- "pattern": "string",
- "enum": [
- null
], - "minimum": 0,
- "maximum": 0,
- "minItems": 0,
- "maxItems": 0,
- "items": [
- { }
]
}
}, - "categories": [
- "string"
], - "deprecated": false,
- "experimental": false,
- "exceptions": {
- "property1": {
- "description": "string",
- "message": "The value specified for the process argument '{argument}' in process '{process}' is invalid: {reason}",
- "http": 400
}, - "property2": {
- "description": "string",
- "message": "The value specified for the process argument '{argument}' in process '{process}' is invalid: {reason}",
- "http": 400
}
}, - "examples": [
- {
- "title": "string",
- "description": "string",
- "arguments": {
- "property1": {
- "from_parameter": null,
- "from_node": null,
- "process_graph": null
}, - "property2": {
- "from_parameter": null,
- "from_node": null,
- "process_graph": null
}
}, - "returns": null
}
], - "links": [
], - "process_graph": {
- "dc": {
- "process_id": "load_collection",
- "arguments": {
- "id": "Sentinel-2",
- "spatial_extent": {
- "west": 16.1,
- "east": 16.6,
- "north": 48.6,
- "south": 47.2
}, - "temporal_extent": [
- "2018-01-01",
- "2018-02-01"
]
}
}, - "bands": {
- "process_id": "filter_bands",
- "description": "Filter and order the bands. The order is important for the following reduce operation.",
- "arguments": {
- "data": {
- "from_node": "dc"
}, - "bands": [
- "B08",
- "B04",
- "B02"
]
}
}, - "evi": {
- "process_id": "reduce",
- "description": "Compute the EVI. Formula: 2.5 * (NIR - RED) / (1 + NIR + 6*RED + -7.5*BLUE)",
- "arguments": {
- "data": {
- "from_node": "bands"
}, - "dimension": "bands",
- "reducer": {
- "process_graph": {
- "nir": {
- "process_id": "array_element",
- "arguments": {
- "data": {
- "from_parameter": "data"
}, - "index": 0
}
}, - "red": {
- "process_id": "array_element",
- "arguments": {
- "data": {
- "from_parameter": "data"
}, - "index": 1
}
}, - "blue": {
- "process_id": "array_element",
- "arguments": {
- "data": {
- "from_parameter": "data"
}, - "index": 2
}
}, - "sub": {
- "process_id": "subtract",
- "arguments": {
- "data": [
- {
- "from_node": "nir"
}, - {
- "from_node": "red"
}
]
}
}, - "p1": {
- "process_id": "product",
- "arguments": {
- "data": [
- 6,
- {
- "from_node": "red"
}
]
}
}, - "p2": {
- "process_id": "product",
- "arguments": {
- "data": [
- -7.5,
- {
- "from_node": "blue"
}
]
}
}, - "sum": {
- "process_id": "sum",
- "arguments": {
- "data": [
- 1,
- {
- "from_node": "nir"
}, - {
- "from_node": "p1"
}, - {
- "from_node": "p2"
}
]
}
}, - "div": {
- "process_id": "divide",
- "arguments": {
- "data": [
- {
- "from_node": "sub"
}, - {
- "from_node": "sum"
}
]
}
}, - "p3": {
- "process_id": "product",
- "arguments": {
- "data": [
- 2.5,
- {
- "from_node": "div"
}
]
}, - "result": true
}
}
}
}
}, - "mintime": {
- "process_id": "reduce",
- "description": "Compute a minimum time composite by reducing the temporal dimension",
- "arguments": {
- "data": {
- "from_node": "evi"
}, - "dimension": "temporal",
- "reducer": {
- "process_graph": {
- "min": {
- "process_id": "min",
- "arguments": {
- "data": {
- "from_parameter": "data"
}
}, - "result": true
}
}
}
}
}, - "save": {
- "process_id": "save_result",
- "arguments": {
- "data": {
- "from_node": "mintime"
}, - "format": "GTiff"
}, - "result": true
}
}
}, - "status": "running",
- "progress": 75.5,
- "created": "2017-01-01T09:32:12Z",
- "updated": "2017-01-01T09:36:18Z",
- "plan": "free",
- "costs": 12.98,
- "budget": 100
}
], - "links": [
]
}
The URL of the API MAY freely be chosen by the back-end providers. The path, including API versioning, is a recommendation only. Nevertheless, all servers MUST support HTTPS as the authentication methods are not secure with HTTP only!
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.
Specifies the job details, e.g. the user-defined process and billing details.
title | string (eo_title) Nullable A short description to easily distinguish entities. |
description | string <commonmark> (eo_description) Nullable Detailed multi-line description to explain the entity. CommonMark 0.29 syntax MAY be used for rich text representation. |
process required | object (Process Graph with metadata) A process graph, optionally enriched with process metadata. |
plan | string (billing_plan_defaultable) Nullable The billing plan to process and charge the job with. The plans and the default plan can be retrieved by calling Billing plans MUST be accepted case insensitive. Billing plans not on the list of available plans MUST be rejected with openEO error If no billing plan is specified by the client, the server MUST default to the default billing plan in |
budget | number (budget) Nullable Default: null Maximum amount of costs the request is allowed to produce. The value MUST be specified in the currency the back-end is working with. The currency can be retrieved by calling If possible, back-ends SHOULD reject jobs with openEO error Setting the budget to |
The batch job has been created successfully.
Location required | string <uri> Example: "https://example.openeo.org/api/jobs/123" Absolute URL to the newly created batch job. The URL points to the metadata endpoint
|
OpenEO-Identifier required | string (job_id) ^[\w\-\.~]+$ Example: "a3cca2b2aa1e3b5b" Unique identifier of the batch job, generated by the back-end during creation. MUST match the specified pattern. |
The request can't be fulfilled due to an error on client-side, i.e. the request is invalid. The client SHOULD NOT repeat the request without modifications.
The response body SHOULD contain a JSON error object. MUST be any HTTP status code specified in RFC 7231. This request MUST respond with HTTP status codes 401 if authorization is required or 403 if the authorization failed or access is forbidden in general to the authenticated user. HTTP status code 404 SHOULD be used if the value of a path parameter is invalid.
See also:
The request can't be fulfilled due to an error at the back-end. The error is never the client’s fault and therefore it is reasonable for the client to retry the exact same request that triggered this response.
The response body SHOULD contain a JSON error object. MUST be any HTTP status code specified in RFC 7231.
See also:
{- "title": "NDVI based on Sentinel 2",
- "description": "Deriving minimum NDVI measurements over pixel time series of Sentinel 2",
- "process": {
- "id": "ndvi",
- "summary": "string",
- "description": "string",
- "parameters": [
- {
- "schema": {
- "parameters": [
- {
- "schema": {
- "type": "array",
- "subtype": "string",
- "pattern": "string",
- "enum": [
- null
], - "minimum": 0,
- "maximum": 0,
- "minItems": 0,
- "maxItems": 0,
- "items": [
- { }
]
}, - "name": "string",
- "description": "string",
- "optional": false,
- "deprecated": false,
- "experimental": false,
- "default": null
}
], - "type": "array",
- "subtype": "string",
- "pattern": "string",
- "enum": [
- null
], - "minimum": 0,
- "maximum": 0,
- "minItems": 0,
- "maxItems": 0,
- "items": [
- { }
]
}, - "name": "string",
- "description": "string",
- "optional": false,
- "deprecated": false,
- "experimental": false,
- "default": null
}
], - "returns": {
- "description": "string",
- "schema": {
- "type": "array",
- "subtype": "string",
- "pattern": "string",
- "enum": [
- null
], - "minimum": 0,
- "maximum": 0,
- "minItems": 0,
- "maxItems": 0,
- "items": [
- { }
]
}
}, - "categories": [
- "string"
], - "deprecated": false,
- "experimental": false,
- "exceptions": {
- "property1": {
- "description": "string",
- "message": "The value specified for the process argument '{argument}' in process '{process}' is invalid: {reason}",
- "http": 400
}, - "property2": {
- "description": "string",
- "message": "The value specified for the process argument '{argument}' in process '{process}' is invalid: {reason}",
- "http": 400
}
}, - "examples": [
- {
- "title": "string",
- "description": "string",
- "arguments": {
- "property1": {
- "from_parameter": null,
- "from_node": null,
- "process_graph": null
}, - "property2": {
- "from_parameter": null,
- "from_node": null,
- "process_graph": null
}
}, - "returns": null
}
], - "links": [
], - "process_graph": {
- "dc": {
- "process_id": "load_collection",
- "arguments": {
- "id": "Sentinel-2",
- "spatial_extent": {
- "west": 16.1,
- "east": 16.6,
- "north": 48.6,
- "south": 47.2
}, - "temporal_extent": [
- "2018-01-01",
- "2018-02-01"
]
}
}, - "bands": {
- "process_id": "filter_bands",
- "description": "Filter and order the bands. The order is important for the following reduce operation.",
- "arguments": {
- "data": {
- "from_node": "dc"
}, - "bands": [
- "B08",
- "B04",
- "B02"
]
}
}, - "evi": {
- "process_id": "reduce",
- "description": "Compute the EVI. Formula: 2.5 * (NIR - RED) / (1 + NIR + 6*RED + -7.5*BLUE)",
- "arguments": {
- "data": {
- "from_node": "bands"
}, - "dimension": "bands",
- "reducer": {
- "process_graph": {
- "nir": {
- "process_id": "array_element",
- "arguments": {
- "data": {
- "from_parameter": "data"
}, - "index": 0
}
}, - "red": {
- "process_id": "array_element",
- "arguments": {
- "data": {
- "from_parameter": "data"
}, - "index": 1
}
}, - "blue": {
- "process_id": "array_element",
- "arguments": {
- "data": {
- "from_parameter": "data"
}, - "index": 2
}
}, - "sub": {
- "process_id": "subtract",
- "arguments": {
- "data": [
- {
- "from_node": "nir"
}, - {
- "from_node": "red"
}
]
}
}, - "p1": {
- "process_id": "product",
- "arguments": {
- "data": [
- 6,
- {
- "from_node": "red"
}
]
}
}, - "p2": {
- "process_id": "product",
- "arguments": {
- "data": [
- -7.5,
- {
- "from_node": "blue"
}
]
}
}, - "sum": {
- "process_id": "sum",
- "arguments": {
- "data": [
- 1,
- {
- "from_node": "nir"
}, - {
- "from_node": "p1"
}, - {
- "from_node": "p2"
}
]
}
}, - "div": {
- "process_id": "divide",
- "arguments": {
- "data": [
- {
- "from_node": "sub"
}, - {
- "from_node": "sum"
}
]
}
}, - "p3": {
- "process_id": "product",
- "arguments": {
- "data": [
- 2.5,
- {
- "from_node": "div"
}
]
}, - "result": true
}
}
}
}
}, - "mintime": {
- "process_id": "reduce",
- "description": "Compute a minimum time composite by reducing the temporal dimension",
- "arguments": {
- "data": {
- "from_node": "evi"
}, - "dimension": "temporal",
- "reducer": {
- "process_graph": {
- "min": {
- "process_id": "min",
- "arguments": {
- "data": {
- "from_parameter": "data"
}
}, - "result": true
}
}
}
}
}, - "save": {
- "process_id": "save_result",
- "arguments": {
- "data": {
- "from_node": "mintime"
}, - "format": "GTiff"
}, - "result": true
}
}
}, - "plan": "free",
- "budget": 100
}
{- "id": "550e8400-e29b-11d4-a716-446655440000",
- "code": "SampleError",
- "message": "Parameter 'sample' is missing.",
}
The URL of the API MAY freely be chosen by the back-end providers. The path, including API versioning, is a recommendation only. Nevertheless, all servers MUST support HTTPS as the authentication methods are not secure with HTTP only!
Modifies an existing job at the back-end but maintains the identifier. Changes can be grouped in a single request.
Jobs can only be modified when the job is not queued or running. Otherwise requests to this endpoint MUST be rejected with openEO error JobLocked
.
job_id required | string (job_id) ^[\w\-\.~]+$ Example: a3cca2b2aa1e3b5b Unique job identifier. |
Specifies the job details to update.
title | string (eo_title) Nullable A short description to easily distinguish entities. |
description | string <commonmark> (eo_description) Nullable Detailed multi-line description to explain the entity. CommonMark 0.29 syntax MAY be used for rich text representation. |
process | object (Process Graph with metadata) A process graph, optionally enriched with process metadata. |
plan | string (billing_plan_defaultable) Nullable The billing plan to process and charge the job with. The plans and the default plan can be retrieved by calling Billing plans MUST be accepted case insensitive. Billing plans not on the list of available plans MUST be rejected with openEO error If no billing plan is specified by the client, the server MUST default to the default billing plan in |
budget | number (budget) Nullable Default: null Maximum amount of costs the request is allowed to produce. The value MUST be specified in the currency the back-end is working with. The currency can be retrieved by calling If possible, back-ends SHOULD reject jobs with openEO error Setting the budget to |
Changes to the job applied successfully.
The request can't be fulfilled due to an error on client-side, i.e. the request is invalid. The client SHOULD NOT repeat the request without modifications.
The response body SHOULD contain a JSON error object. MUST be any HTTP status code specified in RFC 7231. This request MUST respond with HTTP status codes 401 if authorization is required or 403 if the authorization failed or access is forbidden in general to the authenticated user. HTTP status code 404 SHOULD be used if the value of a path parameter is invalid.
See also:
The request can't be fulfilled due to an error at the back-end. The error is never the client’s fault and therefore it is reasonable for the client to retry the exact same request that triggered this response.
The response body SHOULD contain a JSON error object. MUST be any HTTP status code specified in RFC 7231.
See also:
{- "title": "NDVI based on Sentinel 2",
- "description": "Deriving minimum NDVI measurements over pixel time series of Sentinel 2",
- "process": {
- "id": "ndvi",
- "summary": "string",
- "description": "string",
- "parameters": [
- {
- "schema": {
- "parameters": [
- {
- "schema": {
- "type": "array",
- "subtype": "string",
- "pattern": "string",
- "enum": [
- null
], - "minimum": 0,
- "maximum": 0,
- "minItems": 0,
- "maxItems": 0,
- "items": [
- { }
]
}, - "name": "string",
- "description": "string",
- "optional": false,
- "deprecated": false,
- "experimental": false,
- "default": null
}
], - "type": "array",
- "subtype": "string",
- "pattern": "string",
- "enum": [
- null
], - "minimum": 0,
- "maximum": 0,
- "minItems": 0,
- "maxItems": 0,
- "items": [
- { }
]
}, - "name": "string",
- "description": "string",
- "optional": false,
- "deprecated": false,
- "experimental": false,
- "default": null
}
], - "returns": {
- "description": "string",
- "schema": {
- "type": "array",
- "subtype": "string",
- "pattern": "string",
- "enum": [
- null
], - "minimum": 0,
- "maximum": 0,
- "minItems": 0,
- "maxItems": 0,
- "items": [
- { }
]
}
}, - "categories": [
- "string"
], - "deprecated": false,
- "experimental": false,
- "exceptions": {
- "property1": {
- "description": "string",
- "message": "The value specified for the process argument '{argument}' in process '{process}' is invalid: {reason}",
- "http": 400
}, - "property2": {
- "description": "string",
- "message": "The value specified for the process argument '{argument}' in process '{process}' is invalid: {reason}",
- "http": 400
}
}, - "examples": [
- {
- "title": "string",
- "description": "string",
- "arguments": {
- "property1": {
- "from_parameter": null,
- "from_node": null,
- "process_graph": null
}, - "property2": {
- "from_parameter": null,
- "from_node": null,
- "process_graph": null
}
}, - "returns": null
}
], - "links": [
], - "process_graph": {
- "dc": {
- "process_id": "load_collection",
- "arguments": {
- "id": "Sentinel-2",
- "spatial_extent": {
- "west": 16.1,
- "east": 16.6,
- "north": 48.6,
- "south": 47.2
}, - "temporal_extent": [
- "2018-01-01",
- "2018-02-01"
]
}
}, - "bands": {
- "process_id": "filter_bands",
- "description": "Filter and order the bands. The order is important for the following reduce operation.",
- "arguments": {
- "data": {
- "from_node": "dc"
}, - "bands": [
- "B08",
- "B04",
- "B02"
]
}
}, - "evi": {
- "process_id": "reduce",
- "description": "Compute the EVI. Formula: 2.5 * (NIR - RED) / (1 + NIR + 6*RED + -7.5*BLUE)",
- "arguments": {
- "data": {
- "from_node": "bands"
}, - "dimension": "bands",
- "reducer": {
- "process_graph": {
- "nir": {
- "process_id": "array_element",
- "arguments": {
- "data": {
- "from_parameter": "data"
}, - "index": 0
}
}, - "red": {
- "process_id": "array_element",
- "arguments": {
- "data": {
- "from_parameter": "data"
}, - "index": 1
}
}, - "blue": {
- "process_id": "array_element",
- "arguments": {
- "data": {
- "from_parameter": "data"
}, - "index": 2
}
}, - "sub": {
- "process_id": "subtract",
- "arguments": {
- "data": [
- {
- "from_node": "nir"
}, - {
- "from_node": "red"
}
]
}
}, - "p1": {
- "process_id": "product",
- "arguments": {
- "data": [
- 6,
- {
- "from_node": "red"
}
]
}
}, - "p2": {
- "process_id": "product",
- "arguments": {
- "data": [
- -7.5,
- {
- "from_node": "blue"
}
]
}
}, - "sum": {
- "process_id": "sum",
- "arguments": {
- "data": [
- 1,
- {
- "from_node": "nir"
}, - {
- "from_node": "p1"
}, - {
- "from_node": "p2"
}
]
}
}, - "div": {
- "process_id": "divide",
- "arguments": {
- "data": [
- {
- "from_node": "sub"
}, - {
- "from_node": "sum"
}
]
}
}, - "p3": {
- "process_id": "product",
- "arguments": {
- "data": [
- 2.5,
- {
- "from_node": "div"
}
]
}, - "result": true
}
}
}
}
}, - "mintime": {
- "process_id": "reduce",
- "description": "Compute a minimum time composite by reducing the temporal dimension",
- "arguments": {
- "data": {
- "from_node": "evi"
}, - "dimension": "temporal",
- "reducer": {
- "process_graph": {
- "min": {
- "process_id": "min",
- "arguments": {
- "data": {
- "from_parameter": "data"
}
}, - "result": true
}
}
}
}
}, - "save": {
- "process_id": "save_result",
- "arguments": {
- "data": {
- "from_node": "mintime"
}, - "format": "GTiff"
}, - "result": true
}
}
}, - "plan": "free",
- "budget": 100
}
{- "id": "550e8400-e29b-11d4-a716-446655440000",
- "code": "SampleError",
- "message": "Parameter 'sample' is missing.",
}
The URL of the API MAY freely be chosen by the back-end providers. The path, including API versioning, is a recommendation only. Nevertheless, all servers MUST support HTTPS as the authentication methods are not secure with HTTP only!
Returns all information about a submitted batch job.
job_id required | string (job_id) ^[\w\-\.~]+$ Example: a3cca2b2aa1e3b5b Unique job identifier. |
Full job information.
id required | string (job_id) ^[\w\-\.~]+$ Unique identifier of the batch job, generated by the back-end during creation. MUST match the specified pattern. |
title | string (eo_title) Nullable A short description to easily distinguish entities. |
description | string <commonmark> (eo_description) Nullable Detailed multi-line description to explain the entity. CommonMark 0.29 syntax MAY be used for rich text representation. |
process required | object (Process Graph with metadata) A process graph, optionally enriched with process metadata. |
status required | string Default: "created" Enum: "created" "queued" "running" "canceled" "finished" "error" The current status of a batch job. The following status changes can occur:
|
progress | number [ 0 .. 100 ] Indicates the process of a running batch job in percent.
Can also be set for a job which stopped due to an error or was canceled by the user. In this case, the value indicates the progress at which the job stopped. The Property may not be available for the status codes |
created required | string <date-time> (created) Date and time of creation, formatted as a RFC 3339 date-time. |
updated | string <date-time> (updated) Date and time of last status change, formatted as a RFC 3339 date-time. |
plan | string (billing_plan) The billing plan to process and charge the job with. The plans can be retrieved by calling |
costs | number (money) Nullable Default: null An amount of money or credits. The value MUST be specified in the currency the back-end is working with. The currency can be retrieved by calling |
budget | number (budget) Nullable Default: null Maximum amount of costs the request is allowed to produce. The value MUST be specified in the currency the back-end is working with. The currency can be retrieved by calling If possible, back-ends SHOULD reject jobs with openEO error Setting the budget to |
The request can't be fulfilled due to an error on client-side, i.e. the request is invalid. The client SHOULD NOT repeat the request without modifications.
The response body SHOULD contain a JSON error object. MUST be any HTTP status code specified in RFC 7231. This request MUST respond with HTTP status codes 401 if authorization is required or 403 if the authorization failed or access is forbidden in general to the authenticated user. HTTP status code 404 SHOULD be used if the value of a path parameter is invalid.
See also:
The request can't be fulfilled due to an error at the back-end. The error is never the client’s fault and therefore it is reasonable for the client to retry the exact same request that triggered this response.
The response body SHOULD contain a JSON error object. MUST be any HTTP status code specified in RFC 7231.
See also:
{- "id": "a3cca2b2aa1e3b5b",
- "title": "NDVI based on Sentinel 2",
- "description": "Deriving minimum NDVI measurements over pixel time series of Sentinel 2",
- "process": {
- "id": "ndvi",
- "summary": "string",
- "description": "string",
- "parameters": [
- {
- "schema": {
- "parameters": [
- {
- "schema": {
- "type": "array",
- "subtype": "string",
- "pattern": "string",
- "enum": [
- null
], - "minimum": 0,
- "maximum": 0,
- "minItems": 0,
- "maxItems": 0,
- "items": [
- { }
]
}, - "name": "string",
- "description": "string",
- "optional": false,
- "deprecated": false,
- "experimental": false,
- "default": null
}
], - "type": "array",
- "subtype": "string",
- "pattern": "string",
- "enum": [
- null
], - "minimum": 0,
- "maximum": 0,
- "minItems": 0,
- "maxItems": 0,
- "items": [
- { }
]
}, - "name": "string",
- "description": "string",
- "optional": false,
- "deprecated": false,
- "experimental": false,
- "default": null
}
], - "returns": {
- "description": "string",
- "schema": {
- "type": "array",
- "subtype": "string",
- "pattern": "string",
- "enum": [
- null
], - "minimum": 0,
- "maximum": 0,
- "minItems": 0,
- "maxItems": 0,
- "items": [
- { }
]
}
}, - "categories": [
- "string"
], - "deprecated": false,
- "experimental": false,
- "exceptions": {
- "property1": {
- "description": "string",
- "message": "The value specified for the process argument '{argument}' in process '{process}' is invalid: {reason}",
- "http": 400
}, - "property2": {
- "description": "string",
- "message": "The value specified for the process argument '{argument}' in process '{process}' is invalid: {reason}",
- "http": 400
}
}, - "examples": [
- {
- "title": "string",
- "description": "string",
- "arguments": {
- "property1": {
- "from_parameter": null,
- "from_node": null,
- "process_graph": null
}, - "property2": {
- "from_parameter": null,
- "from_node": null,
- "process_graph": null
}
}, - "returns": null
}
], - "links": [
], - "process_graph": {
- "dc": {
- "process_id": "load_collection",
- "arguments": {
- "id": "Sentinel-2",
- "spatial_extent": {
- "west": 16.1,
- "east": 16.6,
- "north": 48.6,
- "south": 47.2
}, - "temporal_extent": [
- "2018-01-01",
- "2018-02-01"
]
}
}, - "bands": {
- "process_id": "filter_bands",
- "description": "Filter and order the bands. The order is important for the following reduce operation.",
- "arguments": {
- "data": {
- "from_node": "dc"
}, - "bands": [
- "B08",
- "B04",
- "B02"
]
}
}, - "evi": {
- "process_id": "reduce",
- "description": "Compute the EVI. Formula: 2.5 * (NIR - RED) / (1 + NIR + 6*RED + -7.5*BLUE)",
- "arguments": {
- "data": {
- "from_node": "bands"
}, - "dimension": "bands",
- "reducer": {
- "process_graph": {
- "nir": {
- "process_id": "array_element",
- "arguments": {
- "data": {
- "from_parameter": "data"
}, - "index": 0
}
}, - "red": {
- "process_id": "array_element",
- "arguments": {
- "data": {
- "from_parameter": "data"
}, - "index": 1
}
}, - "blue": {
- "process_id": "array_element",
- "arguments": {
- "data": {
- "from_parameter": "data"
}, - "index": 2
}
}, - "sub": {
- "process_id": "subtract",
- "arguments": {
- "data": [
- {
- "from_node": "nir"
}, - {
- "from_node": "red"
}
]
}
}, - "p1": {
- "process_id": "product",
- "arguments": {
- "data": [
- 6,
- {
- "from_node": "red"
}
]
}
}, - "p2": {
- "process_id": "product",
- "arguments": {
- "data": [
- -7.5,
- {
- "from_node": "blue"
}
]
}
}, - "sum": {
- "process_id": "sum",
- "arguments": {
- "data": [
- 1,
- {
- "from_node": "nir"
}, - {
- "from_node": "p1"
}, - {
- "from_node": "p2"
}
]
}
}, - "div": {
- "process_id": "divide",
- "arguments": {
- "data": [
- {
- "from_node": "sub"
}, - {
- "from_node": "sum"
}
]
}
}, - "p3": {
- "process_id": "product",
- "arguments": {
- "data": [
- 2.5,
- {
- "from_node": "div"
}
]
}, - "result": true
}
}
}
}
}, - "mintime": {
- "process_id": "reduce",
- "description": "Compute a minimum time composite by reducing the temporal dimension",
- "arguments": {
- "data": {
- "from_node": "evi"
}, - "dimension": "temporal",
- "reducer": {
- "process_graph": {
- "min": {
- "process_id": "min",
- "arguments": {
- "data": {
- "from_parameter": "data"
}
}, - "result": true
}
}
}
}
}, - "save": {
- "process_id": "save_result",
- "arguments": {
- "data": {
- "from_node": "mintime"
}, - "format": "GTiff"
}, - "result": true
}
}
}, - "status": "running",
- "progress": 75.5,
- "created": "2017-01-01T09:32:12Z",
- "updated": "2017-01-01T09:36:18Z",
- "plan": "free",
- "costs": 12.98,
- "budget": 100
}
The URL of the API MAY freely be chosen by the back-end providers. The path, including API versioning, is a recommendation only. Nevertheless, all servers MUST support HTTPS as the authentication methods are not secure with HTTP only!
Deletes all data related to this job. Computations are stopped and computed results are deleted. This job won't generate additional costs for processing.
job_id required | string (job_id) ^[\w\-\.~]+$ Example: a3cca2b2aa1e3b5b Unique job identifier. |
The job has been successfully deleted.
The request can't be fulfilled due to an error on client-side, i.e. the request is invalid. The client SHOULD NOT repeat the request without modifications.
The response body SHOULD contain a JSON error object. MUST be any HTTP status code specified in RFC 7231. This request MUST respond with HTTP status codes 401 if authorization is required or 403 if the authorization failed or access is forbidden in general to the authenticated user. HTTP status code 404 SHOULD be used if the value of a path parameter is invalid.
See also:
The request can't be fulfilled due to an error at the back-end. The error is never the client’s fault and therefore it is reasonable for the client to retry the exact same request that triggered this response.
The response body SHOULD contain a JSON error object. MUST be any HTTP status code specified in RFC 7231.
See also:
{- "id": "550e8400-e29b-11d4-a716-446655440000",
- "code": "SampleError",
- "message": "Parameter 'sample' is missing.",
}
The URL of the API MAY freely be chosen by the back-end providers. The path, including API versioning, is a recommendation only. Nevertheless, all servers MUST support HTTPS as the authentication methods are not secure with HTTP only!
Clients can ask for an estimate for a batch job. Back-ends can decide to either calculate the duration, the costs, the size or a combination of them. This MUST be the upper limit of the incurring costs. Clients can be charged less than specified, but never more. Back-end providers MAY specify an expiry time for the estimate. Starting to process data afterwards MAY be charged at a higher cost. Costs MAY NOT include downloading costs. This can be indicated with the downloads_included
flag.
job_id required | string (job_id) ^[\w\-\.~]+$ Example: a3cca2b2aa1e3b5b Unique job identifier. |
The estimated costs with regard to money, processing time and storage capacity. At least one of costs
, duration
or size
MUST be provided.
costs | number (money) Nullable Default: null An amount of money or credits. The value MUST be specified in the currency the back-end is working with. The currency can be retrieved by calling |
duration | string Estimated duration for the operation. Duration MUST be specified as a ISO 8601 duration. |
size | integer Estimated required storage capacity, i.e. the size of the generated files. Size MUST be specified in bytes. |
downloads_included | integer Nullable Default: null Specifies how many full downloads of the processed data are included in the estimate. Set to |
expires | string <date-time> Time until which the estimate is valid, formatted as a RFC 3339 date-time. |
The request can't be fulfilled due to an error on client-side, i.e. the request is invalid. The client SHOULD NOT repeat the request without modifications.
The response body SHOULD contain a JSON error object. MUST be any HTTP status code specified in RFC 7231. This request MUST respond with HTTP status codes 401 if authorization is required or 403 if the authorization failed or access is forbidden in general to the authenticated user. HTTP status code 404 SHOULD be used if the value of a path parameter is invalid.
See also:
The request can't be fulfilled due to an error at the back-end. The error is never the client’s fault and therefore it is reasonable for the client to retry the exact same request that triggered this response.
The response body SHOULD contain a JSON error object. MUST be any HTTP status code specified in RFC 7231.
See also:
{- "costs": 12.98,
- "duration": "P1Y2M10DT2H30M",
- "size": 157286400,
- "downloads_included": 5,
- "expires": "2020-11-01T00:00:00Z"
}
The URL of the API MAY freely be chosen by the back-end providers. The path, including API versioning, is a recommendation only. Nevertheless, all servers MUST support HTTPS as the authentication methods are not secure with HTTP only!
Shows 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 debug
.
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.
job_id required | string (job_id) ^[\w\-\.~]+$ Example: a3cca2b2aa1e3b5b Unique job identifier. |
offset | string Example: offset=log1234 The last identifier (property |
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 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 |
Lists the requested log entries.
logs required | Array of objects (Log Entry) |
links required | Array of objects (links_pagination) Links related to this list of resources, for example links for pagination or alternative formats such as a human-readable HTML version. The links array MUST NOT be paginated. If pagination is implemented, the following
For additional relation types see also the lists of common relation types in openEO. |
The request can't be fulfilled due to an error on client-side, i.e. the request is invalid. The client SHOULD NOT repeat the request without modifications.
The response body SHOULD contain a JSON error object. MUST be any HTTP status code specified in RFC 7231. This request MUST respond with HTTP status codes 401 if authorization is required or 403 if the authorization failed or access is forbidden in general to the authenticated user. HTTP status code 404 SHOULD be used if the value of a path parameter is invalid.
See also:
The request can't be fulfilled due to an error at the back-end. The error is never the client’s fault and therefore it is reasonable for the client to retry the exact same request that triggered this response.
The response body SHOULD contain a JSON error object. MUST be any HTTP status code specified in RFC 7231.
See also:
{- "logs": [
- {
- "id": "1",
- "code": "SampleError",
- "level": "error",
- "message": "Can't load the UDF file from the URL `https://example.com/invalid/file.txt`. Server responded with error 404.",
- "data": null,
- "path": [
- {
- "node_id": "runudf1",
- "process_id": "ndvi",
- "namespace": null,
- "parameter": "udf"
}
],
}
], - "links": [
]
}
The URL of the API MAY freely be chosen by the back-end providers. The path, including API versioning, is a recommendation only. Nevertheless, all servers MUST support HTTPS as the authentication methods are not secure with HTTP only!
After finishing processing, this request will provide signed URLs to the processed files of the batch job with some additional metadata. The response is a STAC Item (version 0.9.0) if it has spatial and temporal references included.
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.
If processing has not finished yet requests to this endpoint MUST be rejected with openEO error JobNotFinished
.
job_id required | string (job_id) ^[\w\-\.~]+$ Example: a3cca2b2aa1e3b5b Unique job identifier. |
Valid download links have been returned. The download links doesn't necessarily need to be located under the API base url.
OpenEO-Costs | number (money) Nullable Default: null Example: 12.98 Specifies the costs for fully downloading the data once, i.e. this header MAY change in subsequent calls. It MUST be set to |
stac_version required | string (stac_version) The version of the STAC specification, which MAY not be equal to the STAC API version. Supports versions 0.9.x and 1.x.x. |
stac_extensions | Array of Reference to a JSON Schema (string) or Reference to a core extension (string) (stac_extensions) A list of implemented STAC extensions. The list contains URLs to the JSON Schema files it can be validated against. For official extensions, a "shortcut" can be used. This means you can specify the folder name of the extension in the STAC repository, for example |
id required | string (job_id) ^[\w\-\.~]+$ Unique identifier of the batch job, generated by the back-end during creation. MUST match the specified pattern. |
type required | string Value: "Feature" |
bbox | Array of 4 elements (numbers) or Array of 6 elements (numbers) Potential spatial extent covered by the data. The bounding box is provided as four or six numbers. Six numbers are specified, if the coordinate reference system includes a vertical axis (height or depth). The order of the elements in the array:
The coordinate reference system of the values is WGS84 longitude/latitude. Specifying the |
geometry required | object Nullable Defines the full footprint of the asset represented by this item as GeoJSON Geometry. Results without a known location can set this value to |
properties required | object (Item Properties) MAY contain any additional properties, e.g. other STAC Item properties, properties from STAC extensions or custom properties. |
assets required | object (Assets) Dictionary of asset objects for data that can be downloaded, each with a unique key. The keys MAY be used by clients as file names. It is RECOMMENDED to link to a copy of this STAC Item with relative links in the assets, which allows users to easily publish their processed data with a basic set of metadata. |
links required | Array of objects (Link) Links related to this batch job result, e.g. a link to an invoice, additional log files or external documentation.
The links MUST NOT contain links to the processed and downloadable data. Instead specify these in the |
The request can't be fulfilled as the batch job failed. This request will deliver the last error message that was produced by the batch job.
This HTTP code MUST be sent only when the job status
is error
.
The request can't be fulfilled due to an error on client-side, i.e. the request is invalid. The client SHOULD NOT repeat the request without modifications.
The response body SHOULD contain a JSON error object. MUST be any HTTP status code specified in RFC 7231. This request MUST respond with HTTP status codes 401 if authorization is required or 403 if the authorization failed or access is forbidden in general to the authenticated user. HTTP status code 404 SHOULD be used if the value of a path parameter is invalid.
See also:
The request can't be fulfilled due to an error at the back-end. The error is never the client’s fault and therefore it is reasonable for the client to retry the exact same request that triggered this response.
The response body SHOULD contain a JSON error object. MUST be any HTTP status code specified in RFC 7231.
See also:
{- "stac_version": "string",
- "id": "a3cca2b2aa1e3b5b",
- "type": "Feature",
- "bbox": [
- -180,
- -90,
- 180,
- 90
], - "geometry": {
- "type": "Polygon",
- "coordinates": [
- [
- [
- -180,
- -90
], - [
- 180,
- -90
], - [
- 180,
- 90
], - [
- -180,
- 90
], - [
- -180,
- -90
]
]
]
}, - "properties": {
- "datetime": "2020-07-17T12:18:32Z",
- "start_datetime": "2020-07-17T12:18:32Z",
- "end_datetime": "2020-07-17T12:18:32Z",
- "title": "NDVI based on Sentinel 2",
- "description": "Deriving minimum NDVI measurements over pixel time series of Sentinel 2",
- "license": "Apache-2.0",
- "providers": [
- {
- "name": "Cool EO Cloud Corp",
- "description": "No further processing applied.",
- "roles": [
- "producer",
- "licensor",
- "host"
],
}
], - "created": "2017-01-01T09:32:12Z",
- "updated": "2017-01-01T09:36:18Z",
- "expires": "2020-11-01T00:00:00Z"
}, - "assets": {
- "preview.png": {
- "type": "image/png",
- "title": "Thumbnail",
- "roles": [
- "thumbnail"
]
}, - "process.json": {
- "type": "application/json",
- "title": "Original Process",
- "roles": [
- "process",
- "reproduction"
]
}, - "1.tif": {
- "type": "image/tiff; application=geotiff",
- "title": "Band 1",
- "roles": [
- "data"
]
}, - "2.tif": {
- "type": "image/tiff; application=geotiff",
- "title": "Band 2",
- "roles": [
- "data"
]
}, - "inspire.xml": {
- "type": "application/xml",
- "title": "INSPIRE metadata",
- "description": "INSPIRE compliant XML metadata",
- "roles": [
- "metadata"
]
}
}, - "links": [
]
}
The URL of the API MAY freely be chosen by the back-end providers. The path, including API versioning, is a recommendation only. Nevertheless, all servers MUST support HTTPS as the authentication methods are not secure with HTTP only!
Adds a batch job to the processing queue to compute the results.
The result will be stored in the format specified in the process graph. To specify the format use a process such as save_result
.
This endpoint has no effect if the job status is already queued
or running
. In particular, it doesn't restart a running job. Processing MUST be canceled before to restart it.
The job status is set to queued
, if processing doesn't start instantly.
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
.
job_id required | string (job_id) ^[\w\-\.~]+$ Example: a3cca2b2aa1e3b5b Unique job identifier. |
The creation of the resource has been queued successfully.
The request can't be fulfilled due to an error on client-side, i.e. the request is invalid. The client SHOULD NOT repeat the request without modifications.
The response body SHOULD contain a JSON error object. MUST be any HTTP status code specified in RFC 7231. This request MUST respond with HTTP status codes 401 if authorization is required or 403 if the authorization failed or access is forbidden in general to the authenticated user. HTTP status code 404 SHOULD be used if the value of a path parameter is invalid.
See also:
The request can't be fulfilled due to an error at the back-end. The error is never the client’s fault and therefore it is reasonable for the client to retry the exact same request that triggered this response.
The response body SHOULD contain a JSON error object. MUST be any HTTP status code specified in RFC 7231.
See also:
{- "id": "550e8400-e29b-11d4-a716-446655440000",
- "code": "SampleError",
- "message": "Parameter 'sample' is missing.",
}
The URL of the API MAY freely be chosen by the back-end providers. The path, including API versioning, is a recommendation only. Nevertheless, all servers MUST support HTTPS as the authentication methods are not secure with HTTP only!
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 as it was canceled. Finished results MUST NOT be deleted until the job is deleted or job processing is started again.
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
.
job_id required | string (job_id) ^[\w\-\.~]+$ Example: a3cca2b2aa1e3b5b Unique job identifier. |
Processing the job has been successfully canceled.
The request can't be fulfilled due to an error on client-side, i.e. the request is invalid. The client SHOULD NOT repeat the request without modifications.
The response body SHOULD contain a JSON error object. MUST be any HTTP status code specified in RFC 7231. This request MUST respond with HTTP status codes 401 if authorization is required or 403 if the authorization failed or access is forbidden in general to the authenticated user. HTTP status code 404 SHOULD be used if the value of a path parameter is invalid.
See also:
The request can't be fulfilled due to an error at the back-end. The error is never the client’s fault and therefore it is reasonable for the client to retry the exact same request that triggered this response.
The response body SHOULD contain a JSON error object. MUST be any HTTP status code specified in RFC 7231.
See also:
{- "id": "550e8400-e29b-11d4-a716-446655440000",
- "code": "SampleError",
- "message": "Parameter 'sample' is missing.",
}
The URL of the API MAY freely be chosen by the back-end providers. The path, including API versioning, is a recommendation only. Nevertheless, all servers MUST support HTTPS as the authentication methods are not secure with HTTP only!
The request will ask the back-end for 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.
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 are allowed to be case insensitive throughout the API.
An object with a map containing all service names as keys and an object that defines supported configuration settings and process parameters.
Service Name* | object (Service Type) |
The request can't be fulfilled due to an error on client-side, i.e. the request is invalid. The client SHOULD NOT repeat the request without modifications.
The response body SHOULD contain a JSON error object. MUST be any HTTP status code specified in RFC 7231. This request usually does not respond with HTTP status codes 401 and 403 due to missing authorization. HTTP status code 404 SHOULD be used if the value of a path parameter is invalid.
See also:
The request can't be fulfilled due to an error at the back-end. The error is never the client’s fault and therefore it is reasonable for the client to retry the exact same request that triggered this response.
The response body SHOULD contain a JSON error object. MUST be any HTTP status code specified in RFC 7231.
See also:
{- "WMS": {
- "title": "OGC Web Map Service",
- "configuration": {
- "version": {
- "type": "string",
- "description": "The WMS version offered to consumers of the service.",
- "default": "1.3.0",
- "enum": [
- "1.1.1",
- "1.3.0"
]
}
}, - "process_parameters": [
- {
- "name": "layer",
- "description": "The layer name.",
- "schema": {
- "type": "string"
}, - "default": "roads"
}, - {
- "name": "spatial_extent_west",
- "description": "The lower left corner for coordinate axis 1 of the extent currently shown to the consumer.",
- "schema": {
- "type": "number"
}
}, - {
- "name": "spatial_extent_south",
- "description": "The lower left corner for coordinate axis 2 of the extent currently shown to the consumer.",
- "schema": {
- "type": "number"
}
}, - {
- "name": "spatial_extent_east",
- "description": "The upper right corner for coordinate axis 1 of the extent currently shown to the consumer.",
- "schema": {
- "type": "number"
}
}, - {
- "name": "spatial_extent_north",
- "description": "The upper right corner for coordinate axis 2 of the extent currently shown to the consumer.",
- "schema": {
- "type": "number"
}
}
], - "links": [
- {
- "rel": "about",
- "title": "OGC Web Map Service Standard"
}
]
}, - "OGCAPI-FEATURES": {
- "title": "OGC API - Features",
- "description": "Exposes a OGC API - Features in version 1.0 of the specification (successor of OGC WFS 3.0).",
- "configuration": {
- "title": {
- "type": "string",
- "description": "The title for the OGC API - Features landing page"
}, - "description": {
- "type": "string",
- "description": "The description for the OGC API - Features landing page"
}, - "conformsTo": {
- "type": "array",
- "description": "The OGC API - Features conformance classes to enable for this service.\n\n`http://www.opengis.net/spec/ogcapi-features-1/1.0/conf/core` is always enabled.",
}
}, - "process_parameters": [ ],
- "links": [
- {
- "rel": "about",
- "title": "OGC Web Feature Service Standard"
}
]
}
}
The URL of the API MAY freely be chosen by the back-end providers. The path, including API versioning, is a recommendation only. Nevertheless, all servers MUST support HTTPS as the authentication methods are not secure with HTTP only!
Requests to this endpoint will list 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 from objects inservices
(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}
.
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 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 |
Array of secondary web service descriptions
services required | Array of objects (Secondary Web Service) |
links required | Array of objects (links_pagination) Links related to this list of resources, for example links for pagination or alternative formats such as a human-readable HTML version. The links array MUST NOT be paginated. If pagination is implemented, the following
For additional relation types see also the lists of common relation types in openEO. |
The request can't be fulfilled due to an error on client-side, i.e. the request is invalid. The client SHOULD NOT repeat the request without modifications.
The response body SHOULD contain a JSON error object. MUST be any HTTP status code specified in RFC 7231. This request MUST respond with HTTP status codes 401 if authorization is required or 403 if the authorization failed or access is forbidden in general to the authenticated user. HTTP status code 404 SHOULD be used if the value of a path parameter is invalid.
See also:
The request can't be fulfilled due to an error at the back-end. The error is never the client’s fault and therefore it is reasonable for the client to retry the exact same request that triggered this response.
The response body SHOULD contain a JSON error object. MUST be any HTTP status code specified in RFC 7231.
See also:
{- "services": [
- {
- "id": "wms-a3cca9",
- "title": "NDVI based on Sentinel 2",
- "description": "Deriving minimum NDVI measurements over pixel time series of Sentinel 2",
- "type": "wms",
- "enabled": true,
- "process": {
- "id": "ndvi",
- "summary": "string",
- "description": "string",
- "parameters": [
- {
- "schema": {
- "parameters": [
- {
- "schema": {
- "type": "array",
- "subtype": "string",
- "pattern": "string",
- "enum": [
- null
], - "minimum": 0,
- "maximum": 0,
- "minItems": 0,
- "maxItems": 0,
- "items": [
- { }
]
}, - "name": "string",
- "description": "string",
- "optional": false,
- "deprecated": false,
- "experimental": false,
- "default": null
}
], - "type": "array",
- "subtype": "string",
- "pattern": "string",
- "enum": [
- null
], - "minimum": 0,
- "maximum": 0,
- "minItems": 0,
- "maxItems": 0,
- "items": [
- { }
]
}, - "name": "string",
- "description": "string",
- "optional": false,
- "deprecated": false,
- "experimental": false,
- "default": null
}
], - "returns": {
- "description": "string",
- "schema": {
- "type": "array",
- "subtype": "string",
- "pattern": "string",
- "enum": [
- null
], - "minimum": 0,
- "maximum": 0,
- "minItems": 0,
- "maxItems": 0,
- "items": [
- { }
]
}
}, - "categories": [
- "string"
], - "deprecated": false,
- "experimental": false,
- "exceptions": {
- "property1": {
- "description": "string",
- "message": "The value specified for the process argument '{argument}' in process '{process}' is invalid: {reason}",
- "http": 400
}, - "property2": {
- "description": "string",
- "message": "The value specified for the process argument '{argument}' in process '{process}' is invalid: {reason}",
- "http": 400
}
}, - "examples": [
- {
- "title": "string",
- "description": "string",
- "arguments": {
- "property1": {
- "from_parameter": null,
- "from_node": null,
- "process_graph": null
}, - "property2": {
- "from_parameter": null,
- "from_node": null,
- "process_graph": null
}
}, - "returns": null
}
], - "links": [
], - "process_graph": {
- "dc": {
- "process_id": "load_collection",
- "arguments": {
- "id": "Sentinel-2",
- "spatial_extent": {
- "west": 16.1,
- "east": 16.6,
- "north": 48.6,
- "south": 47.2
}, - "temporal_extent": [
- "2018-01-01",
- "2018-02-01"
]
}
}, - "bands": {
- "process_id": "filter_bands",
- "description": "Filter and order the bands. The order is important for the following reduce operation.",
- "arguments": {
- "data": {
- "from_node": "dc"
}, - "bands": [
- "B08",
- "B04",
- "B02"
]
}
}, - "evi": {
- "process_id": "reduce",
- "description": "Compute the EVI. Formula: 2.5 * (NIR - RED) / (1 + NIR + 6*RED + -7.5*BLUE)",
- "arguments": {
- "data": {
- "from_node": "bands"
}, - "dimension": "bands",
- "reducer": {
- "process_graph": {
- "nir": {
- "process_id": "array_element",
- "arguments": {
- "data": {
- "from_parameter": "data"
}, - "index": 0
}
}, - "red": {
- "process_id": "array_element",
- "arguments": {
- "data": {
- "from_parameter": "data"
}, - "index": 1
}
}, - "blue": {
- "process_id": "array_element",
- "arguments": {
- "data": {
- "from_parameter": "data"
}, - "index": 2
}
}, - "sub": {
- "process_id": "subtract",
- "arguments": {
- "data": [
- {
- "from_node": "nir"
}, - {
- "from_node": "red"
}
]
}
}, - "p1": {
- "process_id": "product",
- "arguments": {
- "data": [
- 6,
- {
- "from_node": "red"
}
]
}
}, - "p2": {
- "process_id": "product",
- "arguments": {
- "data": [
- -7.5,
- {
- "from_node": "blue"
}
]
}
}, - "sum": {
- "process_id": "sum",
- "arguments": {
- "data": [
- 1,
- {
- "from_node": "nir"
}, - {
- "from_node": "p1"
}, - {
- "from_node": "p2"
}
]
}
}, - "div": {
- "process_id": "divide",
- "arguments": {
- "data": [
- {
- "from_node": "sub"
}, - {
- "from_node": "sum"
}
]
}
}, - "p3": {
- "process_id": "product",
- "arguments": {
- "data": [
- 2.5,
- {
- "from_node": "div"
}
]
}, - "result": true
}
}
}
}
}, - "mintime": {
- "process_id": "reduce",
- "description": "Compute a minimum time composite by reducing the temporal dimension",
- "arguments": {
- "data": {
- "from_node": "evi"
}, - "dimension": "temporal",
- "reducer": {
- "process_graph": {
- "min": {
- "process_id": "min",
- "arguments": {
- "data": {
- "from_parameter": "data"
}
}, - "result": true
}
}
}
}
}, - "save": {
- "process_id": "save_result",
- "arguments": {
- "data": {
- "from_node": "mintime"
}, - "format": "GTiff"
}, - "result": true
}
}
}, - "configuration": {
- "version": "1.3.0"
}, - "attributes": {
- "layers": [
- "ndvi",
- "evi"
]
}, - "created": "2017-01-01T09:32:12Z",
- "plan": "free",
- "costs": 12.98,
- "budget": 100
}
], - "links": [
]
}
The URL of the API MAY freely be chosen by the back-end providers. The path, including API versioning, is a recommendation only. Nevertheless, all servers MUST support HTTPS as the authentication methods are not secure with HTTP only!
Calling this endpoint will create a secondary web service such as 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.
The base data for the secondary web service to create
title | string (eo_title) Nullable A short description to easily distinguish entities. |
description | string <commonmark> (eo_description) Nullable Detailed multi-line description to explain the entity. CommonMark 0.29 syntax MAY be used for rich text representation. |
process 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 |
enabled | boolean (service_enabled) Default: true Describes whether a secondary web service is responding to requests (true) or not (false). Defaults to true. 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 |
plan | string (billing_plan_defaultable) Nullable The billing plan to process and charge the job with. The plans and the default plan can be retrieved by calling Billing plans MUST be accepted case insensitive. Billing plans not on the list of available plans MUST be rejected with openEO error If no billing plan is specified by the client, the server MUST default to the default billing plan in |
budget | number (budget) Nullable Default: null Maximum amount of costs the request is allowed to produce. The value MUST be specified in the currency the back-end is working with. The currency can be retrieved by calling If possible, back-ends SHOULD reject jobs with openEO error Setting the budget to |
The service has been created successfully.
Location required | string <uri> Example: "https://example.openeo.org/api/services/123" Absolute URL to the newly created service. The URL points to the metadata endpoint
|
OpenEO-Identifier required | string (service_id) ^[\w\-\.~]+$ Example: "wms-a3cca9" Unique identifier of the secondary web service, generated by the back-end during creation. MUST match the specified pattern. |
The request can't be fulfilled due to an error on client-side, i.e. the request is invalid. The client SHOULD NOT repeat the request without modifications.
The response body SHOULD contain a JSON error object. MUST be any HTTP status code specified in RFC 7231. This request MUST respond with HTTP status codes 401 if authorization is required or 403 if the authorization failed or access is forbidden in general to the authenticated user. HTTP status code 404 SHOULD be used if the value of a path parameter is invalid.
See also:
The request can't be fulfilled due to an error at the back-end. The error is never the client’s fault and therefore it is reasonable for the client to retry the exact same request that triggered this response.
The response body SHOULD contain a JSON error object. MUST be any HTTP status code specified in RFC 7231.
See also:
{- "title": "NDVI based on Sentinel 2",
- "description": "Deriving minimum NDVI measurements over pixel time series of Sentinel 2",
- "process": {
- "id": "ndvi",
- "summary": "string",
- "description": "string",
- "parameters": [
- {
- "schema": {
- "parameters": [
- {
- "schema": {
- "type": "array",
- "subtype": "string",
- "pattern": "string",
- "enum": [
- null
], - "minimum": 0,
- "maximum": 0,
- "minItems": 0,
- "maxItems": 0,
- "items": [
- { }
]
}, - "name": "string",
- "description": "string",
- "optional": false,
- "deprecated": false,
- "experimental": false,
- "default": null
}
], - "type": "array",
- "subtype": "string",
- "pattern": "string",
- "enum": [
- null
], - "minimum": 0,
- "maximum": 0,
- "minItems": 0,
- "maxItems": 0,
- "items": [
- { }
]
}, - "name": "string",
- "description": "string",
- "optional": false,
- "deprecated": false,
- "experimental": false,
- "default": null
}
], - "returns": {
- "description": "string",
- "schema": {
- "type": "array",
- "subtype": "string",
- "pattern": "string",
- "enum": [
- null
], - "minimum": 0,
- "maximum": 0,
- "minItems": 0,
- "maxItems": 0,
- "items": [
- { }
]
}
}, - "categories": [
- "string"
], - "deprecated": false,
- "experimental": false,
- "exceptions": {
- "property1": {
- "description": "string",
- "message": "The value specified for the process argument '{argument}' in process '{process}' is invalid: {reason}",
- "http": 400
}, - "property2": {
- "description": "string",
- "message": "The value specified for the process argument '{argument}' in process '{process}' is invalid: {reason}",
- "http": 400
}
}, - "examples": [
- {
- "title": "string",
- "description": "string",
- "arguments": {
- "property1": {
- "from_parameter": null,
- "from_node": null,
- "process_graph": null
}, - "property2": {
- "from_parameter": null,
- "from_node": null,
- "process_graph": null
}
}, - "returns": null
}
], - "links": [
], - "process_graph": {
- "dc": {
- "process_id": "load_collection",
- "arguments": {
- "id": "Sentinel-2",
- "spatial_extent": {
- "west": 16.1,
- "east": 16.6,
- "north": 48.6,
- "south": 47.2
}, - "temporal_extent": [
- "2018-01-01",
- "2018-02-01"
]
}
}, - "bands": {
- "process_id": "filter_bands",
- "description": "Filter and order the bands. The order is important for the following reduce operation.",
- "arguments": {
- "data": {
- "from_node": "dc"
}, - "bands": [
- "B08",
- "B04",
- "B02"
]
}
}, - "evi": {
- "process_id": "reduce",
- "description": "Compute the EVI. Formula: 2.5 * (NIR - RED) / (1 + NIR + 6*RED + -7.5*BLUE)",
- "arguments": {
- "data": {
- "from_node": "bands"
}, - "dimension": "bands",
- "reducer": {
- "process_graph": {
- "nir": {
- "process_id": "array_element",
- "arguments": {
- "data": {
- "from_parameter": "data"
}, - "index": 0
}
}, - "red": {
- "process_id": "array_element",
- "arguments": {
- "data": {
- "from_parameter": "data"
}, - "index": 1
}
}, - "blue": {
- "process_id": "array_element",
- "arguments": {
- "data": {
- "from_parameter": "data"
}, - "index": 2
}
}, - "sub": {
- "process_id": "subtract",
- "arguments": {
- "data": [
- {
- "from_node": "nir"
}, - {
- "from_node": "red"
}
]
}
}, - "p1": {
- "process_id": "product",
- "arguments": {
- "data": [
- 6,
- {
- "from_node": "red"
}
]
}
}, - "p2": {
- "process_id": "product",
- "arguments": {
- "data": [
- -7.5,
- {
- "from_node": "blue"
}
]
}
}, - "sum": {
- "process_id": "sum",
- "arguments": {
- "data": [
- 1,
- {
- "from_node": "nir"
}, - {
- "from_node": "p1"
}, - {
- "from_node": "p2"
}
]
}
}, - "div": {
- "process_id": "divide",
- "arguments": {
- "data": [
- {
- "from_node": "sub"
}, - {
- "from_node": "sum"
}
]
}
}, - "p3": {
- "process_id": "product",
- "arguments": {
- "data": [
- 2.5,
- {
- "from_node": "div"
}
]
}, - "result": true
}
}
}
}
}, - "mintime": {
- "process_id": "reduce",
- "description": "Compute a minimum time composite by reducing the temporal dimension",
- "arguments": {
- "data": {
- "from_node": "evi"
}, - "dimension": "temporal",
- "reducer": {
- "process_graph": {
- "min": {
- "process_id": "min",
- "arguments": {
- "data": {
- "from_parameter": "data"
}
}, - "result": true
}
}
}
}
}, - "save": {
- "process_id": "save_result",
- "arguments": {
- "data": {
- "from_node": "mintime"
}, - "format": "GTiff"
}, - "result": true
}
}
}, - "type": "wms",
- "enabled": true,
- "configuration": {
- "version": "1.3.0"
}, - "plan": "free",
- "budget": 100
}
{- "id": "550e8400-e29b-11d4-a716-446655440000",
- "code": "SampleError",
- "message": "Parameter 'sample' is missing.",
}
The URL of the API MAY freely be chosen by the back-end providers. The path, including API versioning, is a recommendation only. Nevertheless, all servers MUST support HTTPS as the authentication methods are not secure with HTTP only!
Calling this endpoint will change the specified secondary web service, but maintain its identifier. Changes can be grouped in a single request. To change the service type create a new service.
service_id required | string (service_id) ^[\w\-\.~]+$ Example: wms-a3cca9 Unique secondary web service identifier. |
The data to change for the specified secondary web service.
title | string (eo_title) Nullable A short description to easily distinguish entities. |
description | string <commonmark> (eo_description) Nullable Detailed multi-line description to explain the entity. CommonMark 0.29 syntax MAY be used for rich text representation. |
process | object (Process Graph with metadata) A process graph, optionally enriched with process metadata. |
enabled | boolean (service_enabled) Default: true Describes whether a secondary web service is responding to requests (true) or not (false). Defaults to true. 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 |
plan | string (billing_plan_defaultable) Nullable The billing plan to process and charge the job with. The plans and the default plan can be retrieved by calling Billing plans MUST be accepted case insensitive. Billing plans not on the list of available plans MUST be rejected with openEO error If no billing plan is specified by the client, the server MUST default to the default billing plan in |
budget | number (budget) Nullable Default: null Maximum amount of costs the request is allowed to produce. The value MUST be specified in the currency the back-end is working with. The currency can be retrieved by calling If possible, back-ends SHOULD reject jobs with openEO error Setting the budget to |
Changes to the service were applied successfully.
The request can't be fulfilled due to an error on client-side, i.e. the request is invalid. The client SHOULD NOT repeat the request without modifications.
The response body SHOULD contain a JSON error object. MUST be any HTTP status code specified in RFC 7231. This request MUST respond with HTTP status codes 401 if authorization is required or 403 if the authorization failed or access is forbidden in general to the authenticated user. HTTP status code 404 SHOULD be used if the value of a path parameter is invalid.
See also:
The request can't be fulfilled due to an error at the back-end. The error is never the client’s fault and therefore it is reasonable for the client to retry the exact same request that triggered this response.
The response body SHOULD contain a JSON error object. MUST be any HTTP status code specified in RFC 7231.
See also:
{- "title": "NDVI based on Sentinel 2",
- "description": "Deriving minimum NDVI measurements over pixel time series of Sentinel 2",
- "process": {
- "id": "ndvi",
- "summary": "string",
- "description": "string",
- "parameters": [
- {
- "schema": {
- "parameters": [
- {
- "schema": {
- "type": "array",
- "subtype": "string",
- "pattern": "string",
- "enum": [
- null
], - "minimum": 0,
- "maximum": 0,
- "minItems": 0,
- "maxItems": 0,
- "items": [
- { }
]
}, - "name": "string",
- "description": "string",
- "optional": false,
- "deprecated": false,
- "experimental": false,
- "default": null
}
], - "type": "array",
- "subtype": "string",
- "pattern": "string",
- "enum": [
- null
], - "minimum": 0,
- "maximum": 0,
- "minItems": 0,
- "maxItems": 0,
- "items": [
- { }
]
}, - "name": "string",
- "description": "string",
- "optional": false,
- "deprecated": false,
- "experimental": false,
- "default": null
}
], - "returns": {
- "description": "string",
- "schema": {
- "type": "array",
- "subtype": "string",
- "pattern": "string",
- "enum": [
- null
], - "minimum": 0,
- "maximum": 0,
- "minItems": 0,
- "maxItems": 0,
- "items": [
- { }
]
}
}, - "categories": [
- "string"
], - "deprecated": false,
- "experimental": false,
- "exceptions": {
- "property1": {
- "description": "string",
- "message": "The value specified for the process argument '{argument}' in process '{process}' is invalid: {reason}",
- "http": 400
}, - "property2": {
- "description": "string",
- "message": "The value specified for the process argument '{argument}' in process '{process}' is invalid: {reason}",
- "http": 400
}
}, - "examples": [
- {
- "title": "string",
- "description": "string",
- "arguments": {
- "property1": {
- "from_parameter": null,
- "from_node": null,
- "process_graph": null
}, - "property2": {
- "from_parameter": null,
- "from_node": null,
- "process_graph": null
}
}, - "returns": null
}
], - "links": [
], - "process_graph": {
- "dc": {
- "process_id": "load_collection",
- "arguments": {
- "id": "Sentinel-2",
- "spatial_extent": {
- "west": 16.1,
- "east": 16.6,
- "north": 48.6,
- "south": 47.2
}, - "temporal_extent": [
- "2018-01-01",
- "2018-02-01"
]
}
}, - "bands": {
- "process_id": "filter_bands",
- "description": "Filter and order the bands. The order is important for the following reduce operation.",
- "arguments": {
- "data": {
- "from_node": "dc"
}, - "bands": [
- "B08",
- "B04",
- "B02"
]
}
}, - "evi": {
- "process_id": "reduce",
- "description": "Compute the EVI. Formula: 2.5 * (NIR - RED) / (1 + NIR + 6*RED + -7.5*BLUE)",
- "arguments": {
- "data": {
- "from_node": "bands"
}, - "dimension": "bands",
- "reducer": {
- "process_graph": {
- "nir": {
- "process_id": "array_element",
- "arguments": {
- "data": {
- "from_parameter": "data"
}, - "index": 0
}
}, - "red": {
- "process_id": "array_element",
- "arguments": {
- "data": {
- "from_parameter": "data"
}, - "index": 1
}
}, - "blue": {
- "process_id": "array_element",
- "arguments": {
- "data": {
- "from_parameter": "data"
}, - "index": 2
}
}, - "sub": {
- "process_id": "subtract",
- "arguments": {
- "data": [
- {
- "from_node": "nir"
}, - {
- "from_node": "red"
}
]
}
}, - "p1": {
- "process_id": "product",
- "arguments": {
- "data": [
- 6,
- {
- "from_node": "red"
}
]
}
}, - "p2": {
- "process_id": "product",
- "arguments": {
- "data": [
- -7.5,
- {
- "from_node": "blue"
}
]
}
}, - "sum": {
- "process_id": "sum",
- "arguments": {
- "data": [
- 1,
- {
- "from_node": "nir"
}, - {
- "from_node": "p1"
}, - {
- "from_node": "p2"
}
]
}
}, - "div": {
- "process_id": "divide",
- "arguments": {
- "data": [
- {
- "from_node": "sub"
}, - {
- "from_node": "sum"
}
]
}
}, - "p3": {
- "process_id": "product",
- "arguments": {
- "data": [
- 2.5,
- {
- "from_node": "div"
}
]
}, - "result": true
}
}
}
}
}, - "mintime": {
- "process_id": "reduce",
- "description": "Compute a minimum time composite by reducing the temporal dimension",
- "arguments": {
- "data": {
- "from_node": "evi"
}, - "dimension": "temporal",
- "reducer": {
- "process_graph": {
- "min": {
- "process_id": "min",
- "arguments": {
- "data": {
- "from_parameter": "data"
}
}, - "result": true
}
}
}
}
}, - "save": {
- "process_id": "save_result",
- "arguments": {
- "data": {
- "from_node": "mintime"
}, - "format": "GTiff"
}, - "result": true
}
}
}, - "enabled": true,
- "configuration": {
- "version": "1.3.0"
}, - "plan": "free",
- "budget": 100
}
{- "id": "550e8400-e29b-11d4-a716-446655440000",
- "code": "SampleError",
- "message": "Parameter 'sample' is missing.",
}
The URL of the API MAY freely be chosen by the back-end providers. The path, including API versioning, is a recommendation only. Nevertheless, all servers MUST support HTTPS as the authentication methods are not secure with HTTP only!
Requests to this endpoint will return JSON description of the secondary web service.
service_id required | string (service_id) ^[\w\-\.~]+$ Example: wms-a3cca9 Unique secondary web service identifier. |
Details of the created service
id required | string (service_id) ^[\w\-\.~]+$ Unique identifier of the secondary web service, generated by the back-end during creation. MUST match the specified pattern. |
title | string (eo_title) Nullable A short description to easily distinguish entities. |
description | string <commonmark> (eo_description) Nullable Detailed multi-line description to explain the entity. CommonMark 0.29 syntax MAY be used for rich text representation. |
url required | string <uri> URL at which the secondary web service is accessible. Doesn't necessarily need to be located within the API. |
type required | string (service_type) Definition of the service type to access result data. All available service types can be retrieved via |
enabled required | boolean (service_enabled) Default: true Describes whether a secondary web service is responding to requests (true) or not (false). Defaults to true. Disabled services don't produce any costs. |
process required | object (Process Graph with metadata) A process graph, optionally enriched with process metadata. |
configuration required | object (Service Configuration) Map of configuration settings, i.e. the setting names supported by the secondary web service combined with actual values. See |
attributes required | object (Secondary Web Service Attributes) Additional attributes of the secondary web service, e.g. available layers for a WMS based on the bands in the underlying GeoTiff. |
created | string <date-time> (created) Date and time of creation, formatted as a RFC 3339 date-time. |
plan | string (billing_plan) The billing plan to process and charge the job with. The plans can be retrieved by calling |
costs | number (money) Nullable Default: null An amount of money or credits. The value MUST be specified in the currency the back-end is working with. The currency can be retrieved by calling |
budget | number (budget) Nullable Default: null Maximum amount of costs the request is allowed to produce. The value MUST be specified in the currency the back-end is working with. The currency can be retrieved by calling If possible, back-ends SHOULD reject jobs with openEO error Setting the budget to |
The request can't be fulfilled due to an error on client-side, i.e. the request is invalid. The client SHOULD NOT repeat the request without modifications.
The response body SHOULD contain a JSON error object. MUST be any HTTP status code specified in RFC 7231. This request MUST respond with HTTP status codes 401 if authorization is required or 403 if the authorization failed or access is forbidden in general to the authenticated user. HTTP status code 404 SHOULD be used if the value of a path parameter is invalid.
See also:
The request can't be fulfilled due to an error at the back-end. The error is never the client’s fault and therefore it is reasonable for the client to retry the exact same request that triggered this response.
The response body SHOULD contain a JSON error object. MUST be any HTTP status code specified in RFC 7231.
See also:
{- "id": "wms-a3cca9",
- "title": "NDVI based on Sentinel 2",
- "description": "Deriving minimum NDVI measurements over pixel time series of Sentinel 2",
- "type": "wms",
- "enabled": true,
- "process": {
- "id": "ndvi",
- "summary": "string",
- "description": "string",
- "parameters": [
- {
- "schema": {
- "parameters": [
- {
- "schema": {
- "type": "array",
- "subtype": "string",
- "pattern": "string",
- "enum": [
- null
], - "minimum": 0,
- "maximum": 0,
- "minItems": 0,
- "maxItems": 0,
- "items": [
- { }
]
}, - "name": "string",
- "description": "string",
- "optional": false,
- "deprecated": false,
- "experimental": false,
- "default": null
}
], - "type": "array",
- "subtype": "string",
- "pattern": "string",
- "enum": [
- null
], - "minimum": 0,
- "maximum": 0,
- "minItems": 0,
- "maxItems": 0,
- "items": [
- { }
]
}, - "name": "string",
- "description": "string",
- "optional": false,
- "deprecated": false,
- "experimental": false,
- "default": null
}
], - "returns": {
- "description": "string",
- "schema": {
- "type": "array",
- "subtype": "string",
- "pattern": "string",
- "enum": [
- null
], - "minimum": 0,
- "maximum": 0,
- "minItems": 0,
- "maxItems": 0,
- "items": [
- { }
]
}
}, - "categories": [
- "string"
], - "deprecated": false,
- "experimental": false,
- "exceptions": {
- "property1": {
- "description": "string",
- "message": "The value specified for the process argument '{argument}' in process '{process}' is invalid: {reason}",
- "http": 400
}, - "property2": {
- "description": "string",
- "message": "The value specified for the process argument '{argument}' in process '{process}' is invalid: {reason}",
- "http": 400
}
}, - "examples": [
- {
- "title": "string",
- "description": "string",
- "arguments": {
- "property1": {
- "from_parameter": null,
- "from_node": null,
- "process_graph": null
}, - "property2": {
- "from_parameter": null,
- "from_node": null,
- "process_graph": null
}
}, - "returns": null
}
], - "links": [
], - "process_graph": {
- "dc": {
- "process_id": "load_collection",
- "arguments": {
- "id": "Sentinel-2",
- "spatial_extent": {
- "west": 16.1,
- "east": 16.6,
- "north": 48.6,
- "south": 47.2
}, - "temporal_extent": [
- "2018-01-01",
- "2018-02-01"
]
}
}, - "bands": {
- "process_id": "filter_bands",
- "description": "Filter and order the bands. The order is important for the following reduce operation.",
- "arguments": {
- "data": {
- "from_node": "dc"
}, - "bands": [
- "B08",
- "B04",
- "B02"
]
}
}, - "evi": {
- "process_id": "reduce",
- "description": "Compute the EVI. Formula: 2.5 * (NIR - RED) / (1 + NIR + 6*RED + -7.5*BLUE)",
- "arguments": {
- "data": {
- "from_node": "bands"
}, - "dimension": "bands",
- "reducer": {
- "process_graph": {
- "nir": {
- "process_id": "array_element",
- "arguments": {
- "data": {
- "from_parameter": "data"
}, - "index": 0
}
}, - "red": {
- "process_id": "array_element",
- "arguments": {
- "data": {
- "from_parameter": "data"
}, - "index": 1
}
}, - "blue": {
- "process_id": "array_element",
- "arguments": {
- "data": {
- "from_parameter": "data"
}, - "index": 2
}
}, - "sub": {
- "process_id": "subtract",
- "arguments": {
- "data": [
- {
- "from_node": "nir"
}, - {
- "from_node": "red"
}
]
}
}, - "p1": {
- "process_id": "product",
- "arguments": {
- "data": [
- 6,
- {
- "from_node": "red"
}
]
}
}, - "p2": {
- "process_id": "product",
- "arguments": {
- "data": [
- -7.5,
- {
- "from_node": "blue"
}
]
}
}, - "sum": {
- "process_id": "sum",
- "arguments": {
- "data": [
- 1,
- {
- "from_node": "nir"
}, - {
- "from_node": "p1"
}, - {
- "from_node": "p2"
}
]
}
}, - "div": {
- "process_id": "divide",
- "arguments": {
- "data": [
- {
- "from_node": "sub"
}, - {
- "from_node": "sum"
}
]
}
}, - "p3": {
- "process_id": "product",
- "arguments": {
- "data": [
- 2.5,
- {
- "from_node": "div"
}
]
}, - "result": true
}
}
}
}
}, - "mintime": {
- "process_id": "reduce",
- "description": "Compute a minimum time composite by reducing the temporal dimension",
- "arguments": {
- "data": {
- "from_node": "evi"
}, - "dimension": "temporal",
- "reducer": {
- "process_graph": {
- "min": {
- "process_id": "min",
- "arguments": {
- "data": {
- "from_parameter": "data"
}
}, - "result": true
}
}
}
}
}, - "save": {
- "process_id": "save_result",
- "arguments": {
- "data": {
- "from_node": "mintime"
}, - "format": "GTiff"
}, - "result": true
}
}
}, - "configuration": {
- "version": "1.3.0"
}, - "attributes": {
- "layers": [
- "ndvi",
- "evi"
]
}, - "created": "2017-01-01T09:32:12Z",
- "plan": "free",
- "costs": 12.98,
- "budget": 100
}
The URL of the API MAY freely be chosen by the back-end providers. The path, including API versioning, is a recommendation only. Nevertheless, all servers MUST support HTTPS as the authentication methods are not secure with HTTP only!
Calling this endpoint will stop a given secondary web service to access result data.
service_id required | string (service_id) ^[\w\-\.~]+$ Example: wms-a3cca9 Unique secondary web service identifier. |
The service has been successfully deleted.
The request can't be fulfilled due to an error on client-side, i.e. the request is invalid. The client SHOULD NOT repeat the request without modifications.
The response body SHOULD contain a JSON error object. MUST be any HTTP status code specified in RFC 7231. This request MUST respond with HTTP status codes 401 if authorization is required or 403 if the authorization failed or access is forbidden in general to the authenticated user. HTTP status code 404 SHOULD be used if the value of a path parameter is invalid.
See also:
The request can't be fulfilled due to an error at the back-end. The error is never the client’s fault and therefore it is reasonable for the client to retry the exact same request that triggered this response.
The response body SHOULD contain a JSON error object. MUST be any HTTP status code specified in RFC 7231.
See also:
{- "id": "550e8400-e29b-11d4-a716-446655440000",
- "code": "SampleError",
- "message": "Parameter 'sample' is missing.",
}
The URL of the API MAY freely be chosen by the back-end providers. The path, including API versioning, is a recommendation only. Nevertheless, all servers MUST support HTTPS as the authentication methods are not secure with HTTP only!
Shows 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 debug
.
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.
service_id required | string (service_id) ^[\w\-\.~]+$ Example: wms-a3cca9 Unique secondary web service identifier. |
offset | string Example: offset=log1234 The last identifier (property |
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 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 |
Lists the requested log entries.
logs required | Array of objects (Log Entry) |
links required | Array of objects (links_pagination) Links related to this list of resources, for example links for pagination or alternative formats such as a human-readable HTML version. The links array MUST NOT be paginated. If pagination is implemented, the following
For additional relation types see also the lists of common relation types in openEO. |
The request can't be fulfilled due to an error on client-side, i.e. the request is invalid. The client SHOULD NOT repeat the request without modifications.
The response body SHOULD contain a JSON error object. MUST be any HTTP status code specified in RFC 7231. This request MUST respond with HTTP status codes 401 if authorization is required or 403 if the authorization failed or access is forbidden in general to the authenticated user. HTTP status code 404 SHOULD be used if the value of a path parameter is invalid.
See also:
The request can't be fulfilled due to an error at the back-end. The error is never the client’s fault and therefore it is reasonable for the client to retry the exact same request that triggered this response.
The response body SHOULD contain a JSON error object. MUST be any HTTP status code specified in RFC 7231.
See also:
{- "logs": [
- {
- "id": "1",
- "code": "SampleError",
- "level": "error",
- "message": "Can't load the UDF file from the URL `https://example.com/invalid/file.txt`. Server responded with error 404.",
- "data": null,
- "path": [
- {
- "node_id": "runudf1",
- "process_id": "ndvi",
- "namespace": null,
- "parameter": "udf"
}
],
}
], - "links": [
]
}
The URL of the API MAY freely be chosen by the back-end providers. The path, including API versioning, is a recommendation only. Nevertheless, all servers MUST support HTTPS as the authentication methods are not secure with HTTP only!
This service lists all user-uploaded files that are stored at the back-end.
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 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 |
Flattened file tree with path relative to the user's root directory and some basic properties such as the file size and the timestamp of the last modification. All properties except the name are optional. Folders MUST NOT be listed separately so each element in the list MUST be a downloadable file.
files required | Array of objects (Workspace File) |
links required | Array of objects (links_pagination) Links related to this list of resources, for example links for pagination or alternative formats such as a human-readable HTML version. The links array MUST NOT be paginated. If pagination is implemented, the following
For additional relation types see also the lists of common relation types in openEO. |
The request can't be fulfilled due to an error on client-side, i.e. the request is invalid. The client SHOULD NOT repeat the request without modifications.
The response body SHOULD contain a JSON error object. MUST be any HTTP status code specified in RFC 7231. This request MUST respond with HTTP status codes 401 if authorization is required or 403 if the authorization failed or access is forbidden in general to the authenticated user. HTTP status code 404 SHOULD be used if the value of a path parameter is invalid.
See also:
The request can't be fulfilled due to an error at the back-end. The error is never the client’s fault and therefore it is reasonable for the client to retry the exact same request that triggered this response.
The response body SHOULD contain a JSON error object. MUST be any HTTP status code specified in RFC 7231.
See also:
{- "files": [
- {
- "path": "test.txt",
- "size": 182,
- "modified": "2015-10-20T17:22:10Z"
}, - {
- "path": "test.tif",
- "size": 183142,
- "modified": "2017-01-01T09:36:18Z"
}, - {
- "path": "Sentinel2/S2A_MSIL1C_20170819T082011_N0205_R121_T34KGD_20170819T084427.zip",
- "size": 4183353142,
- "modified": "2018-01-03T10:55:29Z"
}
], - "links": [ ]
}
The URL of the API MAY freely be chosen by the back-end providers. The path, including API versioning, is a recommendation only. Nevertheless, all servers MUST support HTTPS as the authentication methods are not secure with HTTP only!
This service downloads a user files identified by its path relative to the user's root directory.
If a folder is specified as path a FileOperationUnsupported
error MUST be sent as response.
path required | string Path of the file, relative to the user's root directory. MAY include folders, but MUST not include relative references such as Folder and file names in the path MUST be url-encoded. The path separator The URL-encoding may be shown incorrectly in rendered versions due to OpenAPI 3 not supporting path parameters which contain slashes. This may also lead to OpenAPI validators not validating paths containing folders correctly. |
A file from the workspace.
The request can't be fulfilled due to an error on client-side, i.e. the request is invalid. The client SHOULD NOT repeat the request without modifications.
The response body SHOULD contain a JSON error object. MUST be any HTTP status code specified in RFC 7231. This request MUST respond with HTTP status codes 401 if authorization is required or 403 if the authorization failed or access is forbidden in general to the authenticated user. HTTP status code 404 SHOULD be used if the value of a path parameter is invalid.
See also:
The request can't be fulfilled due to an error at the back-end. The error is never the client’s fault and therefore it is reasonable for the client to retry the exact same request that triggered this response.
The response body SHOULD contain a JSON error object. MUST be any HTTP status code specified in RFC 7231.
See also:
{- "id": "550e8400-e29b-11d4-a716-446655440000",
- "code": "SampleError",
- "message": "Parameter 'sample' is missing.",
}
The URL of the API MAY freely be chosen by the back-end providers. The path, including API versioning, is a recommendation only. Nevertheless, all servers MUST support HTTPS as the authentication methods are not secure with HTTP only!
This service uploads a new or updates an existing file at a given path.
Folders are created once required by a file upload. Empty folders can't be created.
path required | string Path of the file, relative to the user's root directory. MAY include folders, but MUST not include relative references such as Folder and file names in the path MUST be url-encoded. The path separator The URL-encoding may be shown incorrectly in rendered versions due to OpenAPI 3 not supporting path parameters which contain slashes. This may also lead to OpenAPI validators not validating paths containing folders correctly. |
The file has been uploaded successfully.
path required | string Path of the file, relative to the user's root directory. MUST NOT start with a slash and MUST NOT be url-encoded. |
size | integer File size in bytes. |
modified | string <date-time> Date and time the file has lastly been modified, formatted as a RFC 3339 date-time. |
The request can't be fulfilled due to an error on client-side, i.e. the request is invalid. The client SHOULD NOT repeat the request without modifications.
The response body SHOULD contain a JSON error object. MUST be any HTTP status code specified in RFC 7231. This request MUST respond with HTTP status codes 401 if authorization is required or 403 if the authorization failed or access is forbidden in general to the authenticated user. HTTP status code 404 SHOULD be used if the value of a path parameter is invalid.
See also:
The request can't be fulfilled due to an error at the back-end. The error is never the client’s fault and therefore it is reasonable for the client to retry the exact same request that triggered this response.
The response body SHOULD contain a JSON error object. MUST be any HTTP status code specified in RFC 7231.
See also:
{- "path": "folder/file.txt",
- "size": 1024,
- "modified": "2018-01-03T10:55:29Z"
}
The URL of the API MAY freely be chosen by the back-end providers. The path, including API versioning, is a recommendation only. Nevertheless, all servers MUST support HTTPS as the authentication methods are not secure with HTTP only!
This service deletes an existing user-uploaded file specified by its path. Resulting empty folders MUST be deleted automatically.
Back-ends MAY support deleting folders including its files and sub-folders. If not supported by the back-end a FileOperationUnsupported
error MUST be sent as response.
path required | string Path of the file, relative to the user's root directory. MAY include folders, but MUST not include relative references such as Folder and file names in the path MUST be url-encoded. The path separator The URL-encoding may be shown incorrectly in rendered versions due to OpenAPI 3 not supporting path parameters which contain slashes. This may also lead to OpenAPI validators not validating paths containing folders correctly. |
The file has been successfully deleted at the back-end.
The request can't be fulfilled due to an error on client-side, i.e. the request is invalid. The client SHOULD NOT repeat the request without modifications.
The response body SHOULD contain a JSON error object. MUST be any HTTP status code specified in RFC 7231. This request MUST respond with HTTP status codes 401 if authorization is required or 403 if the authorization failed or access is forbidden in general to the authenticated user. HTTP status code 404 SHOULD be used if the value of a path parameter is invalid.
See also:
The request can't be fulfilled due to an error at the back-end. The error is never the client’s fault and therefore it is reasonable for the client to retry the exact same request that triggered this response.
The response body SHOULD contain a JSON error object. MUST be any HTTP status code specified in RFC 7231.
See also:
{- "id": "550e8400-e29b-11d4-a716-446655440000",
- "code": "SampleError",
- "message": "Parameter 'sample' is missing.",
}