openEO API
The openEO API specification for interoperable cloud-based processing of large Earth observation datasets. Conformance class: https://api.openeo.org/1.3.0 API…
Fork copies the collection into your workspace, without the publisher's secrets, so you can add your own key and send requests. Star saves it to your starred APIs (Account › Marketplace) and helps others find it.
Overview
The openEO API specification for interoperable cloud-based processing of large Earth observation datasets.
Conformance class: https://api.openeo.org/1.3.0
API Principles
Language
In the specification the key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in RFC 2119 and RFC 8174.
Literal Case
Unless otherwise stated the API works case sensitive.
All names SHOULD be written in snake case, i.e. words are separated with one underscore character (_) and no spaces, with all letters lower-cased. Example: hello_world. This applies particularly to endpoints and JSON property names. HTTP header fields are generally case-insensitive according to RFC 7230 and their respective casing conventions are followed, e.g. Content-Type or OpenEO-Costs, for better readability and consistency.
HTTP / REST
This specification uses HTTP REST Level 2 for communication between client and back-end server.
Public API implementations 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 sending the whole JSON object defined by the first-level property.
Naming rules of the API 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 openEO API makes use of HTTP Content Negotiation,
including, but not limited to, the request headers Accept, Accept-Charset and Accept-Language.
JSON
The API uses JSON for request and response bodies whenever feasible. Services use JSON as the default encoding. Other encodings can be requested using HTTP Content Negotiation (Accept header). Clients and servers MUST NOT rely on the order in which properties appear in JSON. To keep the response size small, lists of resources (e.g. the list of batch jobs) usually should not include nested JSON objects, if this information can be requested from the individual resource endpoints (e.g. the metadata for a single batch job).
Charset
If not negotiated otherwise with HTTP Content Negotiation (Accept-Charset header), services use UTF-8 as the default charset.
Web Linking
The API is designed in a way that for most resources, such as collections and processes, a set of links can be added. These can be alternate representations such as 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: Refers to the location that the resource can be (permanently) found online. This is particularly useful when the data is made available offline, so that the downstream user knows the source of the data.
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 to or further explains the resource, e.g. a user guide.
canonical: This relation type usually points to a publicly accessible and more long-lived URL for a resource that otherwise often requires (Bearer) authentication with a short-lived token.
This way the exposed resources can be used by non-openEO clients without…
Endpoints 39
Capabilities
- GETInformation about the back-end
/Lists general information about the back-end, including which version and endpoints of the openEO API are supported. May also include billing information. - GETSupported openEO versions
https://openeo.example/.well-known/openeoLists all implemented openEO versions supported by the service provider. This endpoint is the Well-Known URI (see RFC 5785) for openEO. This allows a client… - GETSupported file formats
/file_formatsLists 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… - GETConformance classes this API implements
/conformanceLists all conformance classes specified in various standards that the implementation conforms to. Conformance classes are commonly used in all OGC API… - GETSupported UDF runtimes
/udf_runtimesLists the supported runtimes for user-defined functions (UDFs), which includes either the programming languages including version numbers and available… - GETSupported secondary web service protocols
/service_typesLists 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…
Account Management
- GETOpenID Connect authentication
/credentials/oidcLists the supported OpenID Connect providers (OP). OpenID Connect Providers MUST support OpenID Connect Discovery. It is highly RECOMMENDED to implement… - GETHTTP Basic authentication
/credentials/basicChecks the credentials provided through HTTP Basic Authentication according to RFC 7617 and returns an access token in exchange for providing valid… - GETInformation about the authenticated user
/meLists information about the authenticated user such as the user id. The endpoint MAY return the disk quota available to the user. The endpoint MAY also return…
EO Data Discovery
- GETBasic metadata for all datasets
/collectionsLists available collections with at least the required information. It is strongly RECOMMENDED to keep the response size small by omitting larger optional… - GETFull metadata for a specific dataset
/collections/:collection_idLists all information about a specific collection specified by the identifier collection_id. This endpoint is compatible with STAC API 1.0.0 and later and OGC… - GETMetadata filters for a specific dataset
/collections/:collection_id/queryablesLists all supported metadata filters (also called "queryables") for a specific collection. This endpoint is compatible with the endpoint defined in the STAC…
Process Discovery
- GETSupported predefined processes
/processesLists all predefined processes and returns detailed process descriptions, including parameters and return values.
User-Defined Processes
- GETList all user-defined processes
/process_graphsLists 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… - GETFull metadata for a user-defined process
/process_graphs/:process_graph_idLists all information about a user-defined process, including its process graph. - PUTStore a user-defined process
/process_graphs/:process_graph_idStores 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… - DELETEDelete a user-defined process
/process_graphs/:process_graph_idDeletes the data related to this user-defined process, including its process graph. Does NOT delete jobs or services that reference this user-defined process.
Data Processing
- POSTValidate a user-defined process (graph)
/validationValidates a user-defined process without executing it. A user-defined process is considered valid unless the errors array in the response contains at least… - POSTProcess and download data synchronously
/resultExecutes a user-defined process directly (synchronously) and the result will be downloaded in the format specified in the process graph. This endpoint can be… - GETList all batch jobs
/jobsLists all batch jobs submitted by a user. It is strongly RECOMMENDED to keep the response size small by omitting all optional non-scalar values (i.e. arrays… - POSTCreate a new batch job
/jobsCreates a new batch processing task (job) from one or more (chained) processes at the back-end. Processing the data does not start yet. The job status gets… - GETFull metadata for a batch job
/jobs/:job_idLists all information about a submitted batch job. - DELETEDelete a batch job
/jobs/:job_idDeletes all data related to a given batch job. Computations are stopped and computed results are deleted. This job will not generate additional costs for… - PATCHModify a batch job
/jobs/:job_idModifies an existing job at the back-end, but maintains the identifier. Changes can be grouped in a single request. The job status does not change. Jobs can… - GETGet an estimate for a batch job
/jobs/:job_id/estimateCalculates an estimate for a batch job. Back-ends can decide to either calculate the duration, the costs, the size or a combination of them. Back-end… - GETLogs for a batch job
/jobs/:job_id/logsLists 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)… - GETList batch job results
/jobs/:job_id/resultsLists signed URLs pointing to the processed files, usually after the batch job has finished. Back-ends may also point to intermediate results after the job… - POSTStart processing a batch job
/jobs/:job_id/resultsAdds a batch job to the processing queue to compute the results. The result will be stored in the format specified in the process. To specify the format use a… - DELETECancel processing a batch job
/jobs/:job_id/resultsCancels 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…
Secondary Services
- GETList all web services
/servicesLists 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… - POSTPublish a new service
/servicesCreates a new secondary web service such as a OGC WMS, OGC WCS, OGC API - Features or XYZ tiles. The secondary web service SHOULD process the underlying data… - GETFull metadata for a service
/services/:service_idLists all information about a secondary web service. - DELETEDelete a service
/services/:service_idDeletes all data related to this secondary web service. Computations are stopped, computed results are deleted, and access to this service is no longer… - PATCHModify a service
/services/:service_idModifies an existing secondary web service at the back-end, but maintains the identifier. Changes can be grouped into a single request. User MUST create a new… - GETLogs for a secondary service
/services/:service_id/logsLists 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…
File Storage
- GETList all files in the workspace
/filesLists all user-uploaded files that are stored at the back-end. - GETDownload a file from the workspace
/files/:pathOffers a file from the user workspace for download. The file is identified by its path relative to the user's root directory. If a folder is specified as path… - PUTUpload a file to the workspace
/files/:pathUploads a new file to the given path or updates an existing file if a file at the path exists. Folders are created once required by a file upload. Empty… - DELETEDelete a file from the workspace
/files/:pathDeletes an existing user-uploaded file specified by its path. Resulting empty folders MUST be deleted automatically. Back-ends MAY support deleting folders…
API details
- Base URL
https://openeo.example/api/{version}- Authentication
- A bearer token in the Authorization header
HTTP Basic authentication (username and password) - Operations
- 39 operations on 27 pathsGET 25POST 5DELETE 5PUT 2PATCH 2
- Main resources
- Data Processing 13Batch Jobs 10Secondary Services 7Capabilities 6User-Defined Processes 5File Storage 4Account Management 3EO Data Discovery 3Process Discovery 3
- Response formats
application/jsonapplication/geo+jsonapplication/octet-streamapplication/schema+json- Description format
- OpenAPI 3.0.2, API version
1.3.0 - Links
- Documentation · OpenAPI document · Support
- Listed from
- openEO's published OpenAPI description (Open-EO/openeo-api) (Apache-2.0)
How to test the openEO API in Swastik Codes
- Open the APISelect “Fork & run in Swastik Codes” on this page. Sign in or create a free account if asked.
- Fork it into your workspaceChoose a workspace. You get your own copy of the openEO API collection, without the publisher's secrets.
- Add your credentialsThis API uses A bearer token in the Authorization header. Add yours in the collection's variables or an environment; the requests already reference it.
- Send a requestPick an endpoint, for example “Information about the back-end” (GET /), and press Send. Check the response, add tests and run the whole collection with the runner.
Frequently asked questions
What is the openEO API?
The openEO API specification for interoperable cloud-based processing of large Earth observation datasets. Conformance class: https://api.openeo.org/1.3.0 API… It is listed under Data & analytics and has 39 endpoints.
Who publishes the openEO API?
It is listed from openEO's public API description (an OpenAPI document), not published by openEO on Swastik Codes. Anyone who controls openeo.org can claim the profile by adding a DNS TXT record.
What is the base URL of the openEO API?
Requests go to https://openeo.example/api/{version}. Endpoint paths are added to this base URL.
How do I authenticate with the openEO API?
It accepts 2 methods: A bearer token in the Authorization header; HTTP Basic authentication (username and password).
How many endpoints does the openEO API have?
39 operations on 27 paths (25 GET, 5 POST, 5 DELETE, 2 PUT, 2 PATCH). The largest groups are Data Processing, Batch Jobs, Secondary Services, Capabilities.
Is forking the openEO API free?
Yes. Forking copies the collection into your workspace for free. It has been starred 0 times and forked 0 times.