

Examples (proof of concept)¶

This page gives a detailed description of the openEO proof of concept use cases. After the proof of concept, this stays in the API to have some basic examples. The proof of concept covered three clearly defined example use cases and how they are translated to sequences of API calls:

Deriving minimum NDVI measurements over pixel time series of Sentinel 2 imagery
Create a monthly aggregated Sentinel 1 product from a custom Python script
Compute time series of zonal (regional) statistics of Sentinel 2 imagery over user-specified polygons

Note: CORS and authentication is not included in these examples for simplicity. Repeating calls are also not included as it would not make much sense to list the same discovery requests (see Use Case 1, requests 1 to 6) for each use case individually.

Use Case 1¶

Deriving minimum NDVI measurements over pixel time series of Sentinel 2 imagery.

Requesting the API versions available at the back-end

Request
```
GET /.well-known/openeo
```
Requesting the capabilities of the back-end

Note: The actual request path depends on the response of the previous request.

Request
```
GET /
```
Check which collections are available at the back-end

Request
```
GET /collections HTTP/1.1
```
Request details about a specific collection (e.g. Sentinel 2)

Note: The actual collection ID in the path depends on the response of the previous request.

Request
```
GET /collections/Sentinel-2 HTTP/1.1
```
Check that needed processes are available

Request
```
GET /processes HTTP/1.1
```
Request the supported secondary web service types

Request
```
GET /service_types HTTP/1.1
```

Create a WMS service

Request

POST /services HTTP/1.1
Content-Type: application/json; charset=utf-8

{
  "title": "Min. NDVI for Sentinel 2",
  "description": "Deriving minimum NDVI measurements over pixel time series of Sentinel 2 imagery.",
  "process_graph": {
    "loadco1": {
      "process_id": "load_collection",
      "arguments": {
        "id": "Sentinel-2",
        "spatial_extent": {
          "west": {"variable_id": "spatial_extent_west"},
          "east": {"variable_id": "spatial_extent_east"},
          "north": {"variable_id": "spatial_extent_north"},
          "south": {"variable_id": "spatial_extent_south"}
        },
        "temporal_extent": ["2017-01-01", "2017-02-01"]
      }
    },
    "ndvi1": {
      "process_id": "ndvi",
      "arguments": {
        "data": {"from_node": "loadco1"}
      }
    },
    "reduce1": {
      "process_id": "reduce",
      "arguments": {
        "data": {"from_node": "ndvi1"},
        "dimension": "temporal",
        "reducer": {
          "callback": {
            "min1": {
              "process_id": "min",
              "arguments": {
                "data": {"from_argument": "data"}
              },
              "result": true
            }
          }
        }
      },
      "result": true
    }
  },
  "type": "WMS",
  "parameters": {
    "version": "1.1.1"
  }
}

Response

HTTP/1.1 201 Created
Location: /services/wms-a3cca9
OpenEO-Identifier: wms-a3cca9

Requesting the service information

Request
```
GET /services/wms-a3cca9 HTTP/1.1
```
Download the data on demand from the WMS

Omitted, not part of the openEO API.

Use Case 2¶

Create a monthly aggregated Sentinel 1 product from a custom Python script.

Upload python script

Request

PUT /files/john_doe/s1_aggregate.py HTTP/1.1
Content-Type: application/octet-stream

<File content>

Create a batch job

Request

POST /jobs HTTP/1.1
Content-Type: application/json; charset=utf-8

{
  "title": "Monthly aggregation on Sentinel 1",
  "description": "Create a monthly aggregated Sentinel 1 product from a custom Python script.",
  "process_graph": {
    "loadco1": {
      "process_id": "load_collection",
      "arguments": {
        "id": "Sentinel-1",
        "spatial_extent": {
          "west": 16.1,
          "east": 16.6,
          "north": 48.6,
          "south": 47.2
        },
        "temporal_extent": ["2017-01-01", "2017-02-01"]
      }
    },
    "reduce1": {
      "process_id": "reduce",
      "arguments": {
        "data": {"from_node": "loadco1"},
        "dimension": "temporal",
        "reducer": {
          "callback": {
            "runudf1": {
              "process_id": "run_udf",
              "arguments": {
                "data": [
                  {"from_argument": "x"},
                  {"from_argument": "y"}
                ],
                "udf": "s1_aggregate.py",
                "runtime": "Python"
              },
              "result": true
            }
          }
        },
        "binary": true
      },
      "result": true
    }
  }
}

Response

HTTP/1.1 201 Created
Location: https://openeo.org/api/v0.4/jobs/132
OpenEO-Identifier: 132

Start batch processing the job

Request
```
POST /jobs/132/results HTTP/1.1
```

Create a TMS service

Request

POST /services HTTP/1.1
Content-Type: application/json; charset=utf-8

{
  "title": "Monthly aggregation on Sentinel 1",
  "description": "Create a monthly aggregated Sentinel 1 product from a custom Python script.",
  "process_graph": {
    "1": {
      "process_id": "load_result",
      "arguments": {
        "id": "132"
      },
      "result": true
    }
  },
  "type": "TMS"
}

Response

HTTP/1.1 201 Created
Location: https://openeo.org/api/v0.4/services/tms-75ff8c
OpenEO-Identifier: tms-75ff8c

Requesting the service information

Request

GET https://openeo.org/api/v0.4/services/tms-75ff8c HTTP/1.1

Download the data on demand from the WMS

Omitted, not part of the openEO API.

Use Case 3¶

Compute time series of zonal (regional) statistics of Sentinel 2 imagery over user-specified polygons.

Create a batch job

Request

POST /jobs HTTP/1.1
Content-Type: application/json; charset=utf-8

{
  "title": "Zonal Statistics / Sentinel 2",
  "description": "Compute time series of zonal (regional) statistics of Sentinel 2 imagery over user-specified polygons.",
  "process_graph": {
    "loadco1": {
      "process_id": "load_collection",
      "arguments": {
        "id": "Sentinel-2",
        "spatial_extent": {
          "west": 16.1,
          "east": 16.6,
          "north": 48.6,
          "south": 47.2
        },
        "temporal_extent": ["2017-01-01", "2017-02-01"],
        "bands": ["B8"]
      }
    },
    "reduce1": {
      "process_id": "reduce",
      "arguments": {
        "data": {"from_node": "loadco1"},
        "dimension": "spectral"
      }
    },
    "aggreg1": {
      "process_id": "aggregate_polygon",
      "arguments": {
        "data": {"from_node": "reduce1"},
        "polygons": {
          "type": "Polygon",
          "coordinates": [
            [
              [16.138916,48.320647],
              [16.524124,48.320647],
              [16.524124,48.1386],
              [16.138916,48.1386],
              [16.138916,48.320647]
            ]
          ]
        },
        "reducer": {
          "callback": {
            "mean1": {
              "process_id": "mean",
              "arguments": {
                "data": {"from_argument": "data"}
              },
              "result": true
            }
          }
        }
      }
    },
    "savere1": {
      "process_id": "save_result",
      "arguments": {
        "data": {"from_node": "aggreg1"},
        "format": "JSON"
      },
      "result": true
    }
  }
}

Response

HTTP/1.1 201 Created
Location: https://openeo.org/jobs/133
OpenEO-Identifier: 133

Start batch processing the job

Request
```
POST /jobs/133/results HTTP/1.1
```

Retrieve download links (after the job has finished)

Request

GET /jobs/133/results HTTP/1.1

Response

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Expires: Wed, 01 May 2019 00:00:00 GMT
OpenEO-Costs: 0

{
  "id":"133",
  "title":"Zonal Statistics / Sentinel 2",
  "description":"Compute time series of zonal (regional) statistics of Sentinel 2 imagery over user-specified polygons.",
  "updated": "2019-02-01T09:36:18Z",
  "links": [
    {
      "href": "https://cdn.openeo.org/4854b51643548ab8a858e2b8282711d8/result.json",
      "type": "application/json"
    }
  ]
}

Download file(s)

Request

GET https://cdn.openeo.org/4854b51643548ab8a858e2b8282711d8/result.json HTTP/1.1

Response

A JSON file containing the results, content omitted.