Skip to content

openEO API for Subscriptions 0.4.0 documentation

The openEO API specification for interoperable cloud-based processing of large Earth observation datasets.

This is a subset of the openEO API that handles WebSocket-based protocols for subscriptions and notifications.

openeo.authorize, openeo.welcome, openeo.subscribe and openeo.unsubsribe MUST be implemeneted by all back-ends.

Security considerations: A handshake has to be performed directly after establishing the WebSocket connection. The client MUST send a openeo.authorize request and receives a openeo.welcome message after a successful authorization. The WebSocket connections MUST be closed by servers once a request with invalid authorization credentials is sent. Servers are allowed to close connections to clients that have not sent a openeo.authorize request 30 seconds after establishing a WebSocket connection.

Table of Contents

Topics

subscribe openeo.authorize

Message

Starts a handshake with the server to authorize the client.

The client MUST send a openeo.authorize request directly after establishing the WebSocket connection and a openeo.welcome will be sent by the server after successful authorization. The WebSocket connections MUST be closed if invalid authorization credentials are sent.

Payload
Name Type Description Accepted values
authorization (required) string

Takes the same values as the HTTP Authorization header that is accepted by most openEO endpoints. The value is concatenated from the Authorization scheme (usually Bearer), a space and the actual token for authorization.

Any
message (required) object Any
message.issued (required) string

Date and time when the message was sent, formatted as a RFC 3339 date-time.

Any
message.topic (required) string

Message type

Any
Example
{
  "authorization": "Bearer eyJhbGciOiJIUzI1NiJ9.e30.4E_Bsx-pJi3kOW9wVXN8CgbATwP09D9V5gxh9-9zSZ0",
  "message": {
    "issued": "2018-08-07T14:06:36Z",
    "topic": "openeo.authorize"
  }
}

publish openeo.welcome

Message

Welcome message for clients.

Sends the supported topics, excluding openeo.authorize, openeo.subscribe, openeo.unsubscribe and openeo.welcome (because these MUST be implemented by every back-end anyway). This message MUST be sent by all servers directly after receiving the openeo.authorize message with valid credentials.

Payload
Name Type Description Accepted values
message (required) object Any
message.issued (required) string

Date and time when the message was sent, formatted as a RFC 3339 date-time.

Any
message.topic (required) string

Message type

Any
payload (required) object Any
payload.topics (required) array(string) Any
Example
{
  "message": {
    "issued": "2018-08-07T14:06:36Z",
    "topic": "openeo.welcome"
  },
  "payload": {
    "topics": [
      "openeo.jobs.output",
      "openeo.jobs.status",
      "openeo.data"
    ]
  }
}

subscribe openeo.subscribe

Message

Subscribes to certain topics.

Additional parameters that may be used to restrict the scope of the subscription are described in the specific messages. For example, a restriction of a subscription to a specific job.

The WebSocket connections MUST be closed if invalid authorization credentials are sent.

Payload
Name Type Description Accepted values
authorization (required) string

Takes the same values as the HTTP Authorization header that is accepted by most openEO endpoints. The value is concatenated from the Authorization scheme (usually Bearer), a space and the actual token for authorization.

Any
message (required) object Any
message.issued (required) string

Date and time when the message was sent, formatted as a RFC 3339 date-time.

Any
message.topic (required) string

Message type

Any
payload (required) object Any
payload.topics (required) array(object)

A list of topics to (un)subscribe to/from.

Any
payload.topics.topic (required) string Any
Example
{
  "authorization": "Bearer eyJhbGciOiJIUzI1NiJ9.e30.4E_Bsx-pJi3kOW9wVXN8CgbATwP09D9V5gxh9-9zSZ0",
  "message": {
    "issued": "2018-08-07T14:06:36Z",
    "topic": "openeo.subscribe"
  },
  "payload": {
    "topics": [
      {
        "topic": "openeo.jobs.status",
        "job_id": "a3cca2b2aa1e3b5b"
      },
      {
        "topic": "openeo.files"
      }
    ]
  }
}

subscribe openeo.unsubscribe

Message

Unsubscribes from certain topics.

The WebSocket connections MUST be closed if invalid authorization credentials are sent.

Payload
Name Type Description Accepted values
authorization (required) string

Takes the same values as the HTTP Authorization header that is accepted by most openEO endpoints. The value is concatenated from the Authorization scheme (usually Bearer), a space and the actual token for authorization.

Any
message (required) object Any
message.issued (required) string

Date and time when the message was sent, formatted as a RFC 3339 date-time.

Any
message.topic (required) string

Message type

Any
payload (required) object Any
payload.topics (required) array(object)

A list of topics to (un)subscribe to/from.

Any
payload.topics.topic (required) string Any
Example
{
  "authorization": "Bearer eyJhbGciOiJIUzI1NiJ9.e30.4E_Bsx-pJi3kOW9wVXN8CgbATwP09D9V5gxh9-9zSZ0",
  "message": {
    "issued": "2018-08-07T14:06:36Z",
    "topic": "openeo.unsubscribe"
  },
  "payload": {
    "topics": [
      {
        "topic": "openeo.jobs.status",
        "job_id": "a3cca2b2aa1e3b5b"
      },
      {
        "topic": "openeo.files"
      }
    ]
  }
}

publish openeo.jobs.output

Message

Data written to the output console with processes of a job.

Subscriptions to this message can be restricted to a certain job by specifying a job_id.

Payload
Name Type Description Accepted values
message (required) object Any
message.issued (required) string

Date and time when the message was sent, formatted as a RFC 3339 date-time.

Any
message.topic (required) string

Message type

Any
payload (required) object Any
payload.job_id (required) string

Unique identifier of a job that is generated by the back-end during job submission.

Any
payload.output (required)

Output data of any type

Any
Example
{
  "message": {
    "issued": "2018-08-07T14:06:36Z",
    "topic": "openeo.jobs.debug"
  },
  "payload": {
    "job_id": "a3cca2b2aa1e3b5b",
    "output": "Hello world!"
  }
}

publish openeo.jobs.debug

Message

Debugging information from job execution.

Subscriptions to this message can be restricted to a certain job by specifying a job_id.

Payload
Name Type Description Accepted values
message (required) object Any
message.issued (required) string

Date and time when the message was sent, formatted as a RFC 3339 date-time.

Any
message.topic (required) string

Message type

Any
payload (required) object Any
payload.job_id (required) string

Unique identifier of a job that is generated by the back-end during job submission.

Any
payload.message (required) string

The thrown debug message

Any
payload.process object

Process throwing the debug message.

Any
payload.process.name (required) string

Name of the process.

Any
payload.process.parameters (required) object

Key-value pairs for the parameters of the process. The keys are the parameter names and the values are the actual values specified for the parameter. Specify the empty object if the process does not have any parameters or was called without parameters.

Any
Example
{
  "message": {
    "issued": "2018-08-07T14:06:36Z",
    "topic": "openeo.jobs.debug"
  },
  "payload": {
    "job_id": "a3cca2b2aa1e3b5b",
    "message": "Invalid CRS specified, defaulting to EPSG:4326.",
    "process": {
      "name": "filter_bbox",
      "parameters": {
        "crs": 9999,
        "west": 55,
        "south": 10,
        "east": 56,
        "north": 11
      }
    }
  }
}

publish openeo.jobs.status

Message

Inform about a status change of a job.

Subscriptions to this message can be restricted to a certain job by specifying a job_id.

Payload
Name Type Description Accepted values
message (required) object Any
message.issued (required) string

Date and time when the message was sent, formatted as a RFC 3339 date-time.

Any
message.topic (required) string

Message type

Any
payload (required) object Any
payload.job_id (required) string

Unique identifier of a job that is generated by the back-end during job submission.

Any
payload.status (required) string

Current status

submitted, queued, running, canceled, finished, error
payload.progress number

Progress of a running job in percent.

Any
Example
{
  "message": {
    "issued": "2018-08-07T14:06:36Z",
    "topic": "openeo.jobs.status"
  },
  "payload": {
    "job_id": "a3cca2b2aa1e3b5b",
    "status": "running",
    "progress": 75.5
  }
}

publish openeo.files

Message

Inform about changes regarding the user files.

Subscriptions to this message can't be restricted to a certain file or folder.

Payload
Name Type Description Accepted values
message (required) object Any
message.issued (required) string

Date and time when the message was sent, formatted as a RFC 3339 date-time.

Any
message.topic (required) string

Message type

Any
payload (required) object Any
payload.user_id (required) string

Unique identifier of the user.

Any
payload.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.

Any
payload.action (required) string

Describes what has changed.

created, updated, deleted
Example
{
  "message": {
    "issued": "2018-08-07T14:06:36Z",
    "topic": "openeo.files"
  },
  "payload": {
    "user_id": "john_doe",
    "path": "new_file.txt",
    "action": "created"
  }
}

publish openeo.data

Message

Inform about changes regarding an EO dataset.

At least one of the temporal_extent and spatial_extent fields MUST be specified.

Subscriptions to this message can be restricted to a certain collection by specifying name and providing a valid collection name.

Payload
Name Type Description Accepted values
message (required) object Any
message.issued (required) string

Date and time when the message was sent, formatted as a RFC 3339 date-time.

Any
message.topic (required) string

Message type

Any
payload (required) object Any
payload.name (required) string

Unique identifier for EO datasets.

Any
payload.temporal_extent array(string)

MUST be specified if the temporal extent of the dataset has changed. The temporal extent is always specified as an array, that consists of either a single timestamp or a start and an end time, each element formatted as a RFC 3339 date-time. Specifies the temporal extent of the data that has changed, not of the whole dataset. Example: The dataset covers images from beginning of 2015 until the end of 2018. A single image has been added, captured at the first day in 2019 at 01:00:00 UTC (1am). The spatial extent specified here must be an array containing a single string: 2019-01-01T01:00:00Z.

Any
payload.spatial_extent object

MUST always be specified. It is the spatial extent of the data that was changed. Specifies the spatial extent of the data that has changed, not of the whole dataset. Example: The dataset covers the whole world and an image of Austria has been added. The spatial extent specified here must be the bounding box of Austria.

Any
payload.spatial_extent.crs oneOf

Coordinate reference system specified as EPSG code or PROJ definition. Defaults to 4326 (EPSG code 4326) unless the client explicitly requests a different coordinate reference system.

Any
payload.spatial_extent.crs.0 integer Any
payload.spatial_extent.crs.1 string Any
payload.spatial_extent.west (required) number

West (lower left corner, coordinate axis 1).

Any
payload.spatial_extent.south (required) number

South (lower left corner, coordinate axis 2).

Any
payload.spatial_extent.east (required) number

East (upper right corner, coordinate axis 1).

Any
payload.spatial_extent.north (required) number

North (upper right corner, coordinate axis 2).

Any
payload.spatial_extent.base number

Base (optional, lower left corner, coordinate axis 3).

Any
payload.spatial_extent.height number

Height (optional, upper right corner, coordinate axis 3).

Any
Example of payload (generated)
{
  "message": {
    "issued": "2019-03-15T11:32:50Z",
    "topic": "openeo.sample"
  },
  "payload": {
    "name": "MOD18Q1",
    "temporal_extent": [
      "2016-01-01T02:30:00Z",
      "2016-01-01T04:45:00Z"
    ],
    "spatial_extent": {
      "crs": 7099,
      "west": 0,
      "south": 0,
      "east": 0,
      "north": 0,
      "base": 0,
      "height": 0
    }
  }
}

Schemas

authorization

Name Type Description Accepted values
authorization string Any
Example
"Bearer eyJhbGciOiJIUzI1NiJ9.e30.4E_Bsx-pJi3kOW9wVXN8CgbATwP09D9V5gxh9-9zSZ0"

message

Name Type Description Accepted values
issued (required) string

Date and time when the message was sent, formatted as a RFC 3339 date-time.

Any
topic (required) string

Message type

Any
Example (generated)
{
  "issued": "2019-03-15T11:32:50Z",
  "topic": "openeo.sample"
}

collection_name

Name Type Description Accepted values
collection_name string Any
Example
"MOD18Q1"

job_id

Name Type Description Accepted values
job_id string Any
Example
"a3cca2b2aa1e3b5b"

user_id

Name Type Description Accepted values
user_id string Any
Example
"john_doe"

topics

Name Type Description Accepted values
topics array(object) Any
topics.topic (required) string Any
Example
[
  {
    "topic": "openeo.jobs.output",
    "job_id": 123
  },
  {
    "topic": "openeo.jobs.status"
  },
  {
    "topic": "openeo.data",
    "name": "MOD18Q1"
  }
]