openEO

# 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:

  1. Deriving minimum NDVI measurements over pixel time series of Sentinel 2 imagery
  2. Create a monthly aggregated Sentinel 1 product from a custom Python script
  3. 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.

A similar example (computing an EVI) is also available. (opens new window)

  1. Requesting the API versions available at the back-end

    Request

    GET /.well-known/openeo

  2. Requesting the capabilities of the back-end

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

    Request

    GET /

  3. Check which collections are available at the back-end

    Request

    GET /collections HTTP/1.1

  4. 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

  5. Check that needed processes are available

    Request

    GET /processes HTTP/1.1

  6. Request the supported secondary web service types

    Request

    GET /service_types HTTP/1.1

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

  8. Requesting the service information

    Request

    GET /services/wms-a3cca9 HTTP/1.1

  9. 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.

  1. Upload python script

    Request

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

<File content>

  2. 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

  3. Start batch processing the job

    Request

    POST /jobs/132/results HTTP/1.1

  4. 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

  5. Requesting the service information

    Request

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

  6. 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.

  1. 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

  2. Start batch processing the job

    Request

    POST /jobs/133/results HTTP/1.1

  3. 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"
    }
  ]
}

  4. Download file(s)

    Request

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

    Response

    A JSON file containing the results, content omitted.