OpenEO UDF API API Reference

The OpenEO UDF API specification

Request Content-Types: application/json
Schemes: http, https
Version: 0.1pre-alpha

Authentication

basicAuth

type
basic

Paths

UDF

POST /udf

Run a Python user defined function (UDF) on the provided data

The UDF Python source code and data as JSON definition to process

Request Content-Types: application/json
Request Example
{
  "code": {
    "language": "python",
    "source": "import numpy as np \n \ndef udf(data): \n    pass\n"
  },
  "data": {
    "proj": "EPSG:4326",
    "raster_collection_tiles": [
      {
        "id": "RED",
        "wavelength": 420,
        "start_times": [
          "2001-01-01T00:00:00",
          "2001-01-02T00:00:00"
        ],
        "end_times": [
          "2001-01-02T00:00:00",
          "2001-01-03T00:00:00"
        ],
        "data": [
          [
            [
              0,
              1
            ],
            [
              2,
              3
            ]
          ],
          [
            [
              0,
              1
            ],
            [
              2,
              3
            ]
          ]
        ],
        "extent": {
          "top": 53,
          "bottom": 50,
          "right": 30,
          "left": 24,
          "hight": 0.01,
          "width": 0.01
        }
      }
    ],
    "feature_collection_tiles": [
      {
        "id": "test_data",
        "start_times": [
          "2001-01-01T00:00:00",
          "2001-01-02T00:00:00"
        ],
        "end_times": [
          "2001-01-02T00:00:00",
          "2001-01-03T00:00:00"
        ],
        "data": {
          "features": [
            {
              "id": "0",
              "type": "Feature",
              "properties": {
                "a": 1,
                "b": "a"
              },
              "geometry": {
                "coordinates": [
                  24,
                  50
                ],
                "type": "Point"
              }
            },
            {
              "id": "1",
              "type": "Feature",
              "properties": {
                "a": 2,
                "b": "b"
              },
              "geometry": {
                "coordinates": [
                  30,
                  53
                ],
                "type": "Point"
              }
            }
          ],
          "type": "FeatureCollection"
        }
      }
    ],
    "structured_data": [
      {
        "description": "Output of a statistical analysis. The univariate analysis of multiple raster collection tiles. Each entry in the output dict/map contains min, mean and max of all pixels in a raster collection tile. The key is the id of the raster collection tile.",
        "data": {
          "RED": {
            "min": 0,
            "max": 100,
            "mean": 50
          },
          "NIR": {
            "min": 0,
            "max": 100,
            "mean": 50
          }
        },
        "type": "dict"
      },
      {
        "description": "A list of values.",
        "data": {
          "list": [
            1,
            2,
            3,
            4,
            5
          ]
        },
        "type": "list"
      },
      {
        "description": "A list of values.",
        "data": {
          "table": [
            [
              "id",
              "value"
            ],
            [
              1,
              10
            ],
            [
              2,
              23
            ],
            [
              3,
              4
            ]
          ]
        },
        "type": "table"
      }
    ],
    "machine_learn_models": [
      {
        "framework": "sklearn",
        "name": "random_forest",
        "description": "A random forest model",
        "path": "/tmp/model.pkl.xz"
      }
    ]
  }
}
200 OK

The result of the UDF computation.

400 Bad Request

The error message.

Response Content-Types: application/json
Response Example (200 OK)
{
  "proj": "EPSG:4326",
  "raster_collection_tiles": [
    {
      "id": "RED",
      "wavelength": 420,
      "start_times": [
        "2001-01-01T00:00:00",
        "2001-01-02T00:00:00"
      ],
      "end_times": [
        "2001-01-02T00:00:00",
        "2001-01-03T00:00:00"
      ],
      "data": [
        [
          [
            0,
            1
          ],
          [
            2,
            3
          ]
        ],
        [
          [
            0,
            1
          ],
          [
            2,
            3
          ]
        ]
      ],
      "extent": {
        "top": 53,
        "bottom": 50,
        "right": 30,
        "left": 24,
        "hight": 0.01,
        "width": 0.01
      }
    }
  ],
  "feature_collection_tiles": [
    {
      "id": "test_data",
      "start_times": [
        "2001-01-01T00:00:00",
        "2001-01-02T00:00:00"
      ],
      "end_times": [
        "2001-01-02T00:00:00",
        "2001-01-03T00:00:00"
      ],
      "data": {
        "features": [
          {
            "id": "0",
            "type": "Feature",
            "properties": {
              "a": 1,
              "b": "a"
            },
            "geometry": {
              "coordinates": [
                24,
                50
              ],
              "type": "Point"
            }
          },
          {
            "id": "1",
            "type": "Feature",
            "properties": {
              "a": 2,
              "b": "b"
            },
            "geometry": {
              "coordinates": [
                30,
                53
              ],
              "type": "Point"
            }
          }
        ],
        "type": "FeatureCollection"
      }
    }
  ],
  "structured_data": [
    {
      "description": "Output of a statistical analysis. The univariate analysis of multiple raster collection tiles. Each entry in the output dict/map contains min, mean and max of all pixels in a raster collection tile. The key is the id of the raster collection tile.",
      "data": {
        "RED": {
          "min": 0,
          "max": 100,
          "mean": 50
        },
        "NIR": {
          "min": 0,
          "max": 100,
          "mean": 50
        }
      },
      "type": "dict"
    },
    {
      "description": "A list of values.",
      "data": {
        "list": [
          1,
          2,
          3,
          4,
          5
        ]
      },
      "type": "list"
    },
    {
      "description": "A list of values.",
      "data": {
        "table": [
          [
            "id",
            "value"
          ],
          [
            1,
            10
          ],
          [
            2,
            23
          ],
          [
            3,
            4
          ]
        ]
      },
      "type": "table"
    }
  ],
  "machine_learn_models": [
    {
      "framework": "sklearn",
      "name": "random_forest",
      "description": "A random forest model",
      "path": "/tmp/model.pkl.xz"
    }
  ]
}
Response Example (400 Bad Request)
{
  "message": "string",
  "traceback": "string"
}

Schema Definitions

UdfRequest: object

The udf request JSON specification. This class is not part of the UDF API but used to create the UDF test server.

code: UdfCode
data: UdfData
Example
{
  "code": {
    "language": "python",
    "source": "import numpy as np \n \ndef udf(data): \n    pass\n"
  },
  "data": {
    "proj": "EPSG:4326",
    "raster_collection_tiles": [
      {
        "id": "RED",
        "wavelength": 420,
        "start_times": [
          "2001-01-01T00:00:00",
          "2001-01-02T00:00:00"
        ],
        "end_times": [
          "2001-01-02T00:00:00",
          "2001-01-03T00:00:00"
        ],
        "data": [
          [
            [
              0,
              1
            ],
            [
              2,
              3
            ]
          ],
          [
            [
              0,
              1
            ],
            [
              2,
              3
            ]
          ]
        ],
        "extent": {
          "top": 53,
          "bottom": 50,
          "right": 30,
          "left": 24,
          "hight": 0.01,
          "width": 0.01
        }
      }
    ],
    "feature_collection_tiles": [
      {
        "id": "test_data",
        "start_times": [
          "2001-01-01T00:00:00",
          "2001-01-02T00:00:00"
        ],
        "end_times": [
          "2001-01-02T00:00:00",
          "2001-01-03T00:00:00"
        ],
        "data": {
          "features": [
            {
              "id": "0",
              "type": "Feature",
              "properties": {
                "a": 1,
                "b": "a"
              },
              "geometry": {
                "coordinates": [
                  24,
                  50
                ],
                "type": "Point"
              }
            },
            {
              "id": "1",
              "type": "Feature",
              "properties": {
                "a": 2,
                "b": "b"
              },
              "geometry": {
                "coordinates": [
                  30,
                  53
                ],
                "type": "Point"
              }
            }
          ],
          "type": "FeatureCollection"
        }
      }
    ],
    "structured_data": [
      {
        "description": "Output of a statistical analysis. The univariate analysis of multiple raster collection tiles. Each entry in the output dict/map contains min, mean and max of all pixels in a raster collection tile. The key is the id of the raster collection tile.",
        "data": {
          "RED": {
            "min": 0,
            "max": 100,
            "mean": 50
          },
          "NIR": {
            "min": 0,
            "max": 100,
            "mean": 50
          }
        },
        "type": "dict"
      },
      {
        "description": "A list of values.",
        "data": {
          "list": [
            1,
            2,
            3,
            4,
            5
          ]
        },
        "type": "list"
      },
      {
        "description": "A list of values.",
        "data": {
          "table": [
            [
              "id",
              "value"
            ],
            [
              1,
              10
            ],
            [
              2,
              23
            ],
            [
              3,
              4
            ]
          ]
        },
        "type": "table"
      }
    ],
    "machine_learn_models": [
      {
        "framework": "sklearn",
        "name": "random_forest",
        "description": "A random forest model",
        "path": "/tmp/model.pkl.xz"
      }
    ]
  }
}

UdfCode: object

The object that stores the UDF code and language specification. This class is not part of the UDF API but used to create the UDF test server.

language: string

The language of UDF code

source: string

The UDF source code as a string

Example
{
  "language": "python",
  "source": "import numpy as np \n \ndef udf(data): \n    pass\n"
}

UdfData: object

The UDF data object that stores raster collection tiles, feature collection tiles,projection information and machine learn models. This object is argument for the UDF as well as their return value.

proj: string

The EPSG code or WKT projection string. eg: EPSG:4326

raster_collection_tiles: RasterCollectionTile

A list of raster collection tiles. Each tile represents a single image band or other scalar values like temperature.

RasterCollectionTile
feature_collection_tiles: FeatureCollectionTile

A list of feature collection tiles.

FeatureCollectionTile
structured_data_list: StructuredData

A list of structured data objects that contain processing results that cant be represented by raster- or feature collection tiles.

StructuredData
machine_learn_models: MachineLearnModel

A list of machine learn models.

MachineLearnModel
Example
{
  "proj": "EPSG:4326",
  "raster_collection_tiles": [
    {
      "id": "RED",
      "wavelength": 420,
      "start_times": [
        "2001-01-01T00:00:00",
        "2001-01-02T00:00:00"
      ],
      "end_times": [
        "2001-01-02T00:00:00",
        "2001-01-03T00:00:00"
      ],
      "data": [
        [
          [
            0,
            1
          ],
          [
            2,
            3
          ]
        ],
        [
          [
            0,
            1
          ],
          [
            2,
            3
          ]
        ]
      ],
      "extent": {
        "top": 53,
        "bottom": 50,
        "right": 30,
        "left": 24,
        "hight": 0.01,
        "width": 0.01
      }
    }
  ],
  "feature_collection_tiles": [
    {
      "id": "test_data",
      "start_times": [
        "2001-01-01T00:00:00",
        "2001-01-02T00:00:00"
      ],
      "end_times": [
        "2001-01-02T00:00:00",
        "2001-01-03T00:00:00"
      ],
      "data": {
        "features": [
          {
            "id": "0",
            "type": "Feature",
            "properties": {
              "a": 1,
              "b": "a"
            },
            "geometry": {
              "coordinates": [
                24,
                50
              ],
              "type": "Point"
            }
          },
          {
            "id": "1",
            "type": "Feature",
            "properties": {
              "a": 2,
              "b": "b"
            },
            "geometry": {
              "coordinates": [
                30,
                53
              ],
              "type": "Point"
            }
          }
        ],
        "type": "FeatureCollection"
      }
    }
  ],
  "structured_data": [
    {
      "description": "Output of a statistical analysis. The univariate analysis of multiple raster collection tiles. Each entry in the output dict/map contains min, mean and max of all pixels in a raster collection tile. The key is the id of the raster collection tile.",
      "data": {
        "RED": {
          "min": 0,
          "max": 100,
          "mean": 50
        },
        "NIR": {
          "min": 0,
          "max": 100,
          "mean": 50
        }
      },
      "type": "dict"
    },
    {
      "description": "A list of values.",
      "data": {
        "list": [
          1,
          2,
          3,
          4,
          5
        ]
      },
      "type": "list"
    },
    {
      "description": "A list of values.",
      "data": {
        "table": [
          [
            "id",
            "value"
          ],
          [
            1,
            10
          ],
          [
            2,
            23
          ],
          [
            3,
            4
          ]
        ]
      },
      "type": "table"
    }
  ],
  "machine_learn_models": [
    {
      "framework": "sklearn",
      "name": "random_forest",
      "description": "A random forest model",
      "path": "/tmp/model.pkl.xz"
    }
  ]
}

RasterCollectionTile: object

A three dimensional tile of data that represents a spatio-temporal subset of a spatio-temporal raster collection.

id: string

The identifier of this raster collection tile.

wavelength: float

The wavelength of the raster collection tile.

data: float[][][]

A three dimensional array fo integer (8,16,32,64 bit) or float (16, 32, 64 bit) values.The index dimension is as follows: [time][y][x]. Hence, the index data[0] returns the 2D slice for the first time-stamp. The y-indexing if counted from top to bottom and represents the rows of the 2D array. The x-indexing is counted from left to right and represents the columns of the 2D array.

float[][]
float[]
float
start_times: string[]

The array that contains that start time values for each x,y slice.As date-time string format ISO 8601 must be supported.

string
end_times: string[]

The vector that contains that end time values for each x,y slice, in case the the time stamps for all or a subset of slices are intervals. For time instances the from and to time stamps must be equal or empty. As date-time string format ISO 8601 must be supported

string
extent: SpatialExtent
Example
{
  "id": "test_data",
  "wavelength": 420,
  "start_times": [
    "2001-01-01T00:00:00",
    "2001-01-02T00:00:00"
  ],
  "end_times": [
    "2001-01-02T00:00:00",
    "2001-01-03T00:00:00"
  ],
  "data": [
    [
      [
        0,
        1
      ],
      [
        2,
        3
      ]
    ],
    [
      [
        0,
        1
      ],
      [
        2,
        3
      ]
    ]
  ],
  "extent": {
    "top": 53,
    "bottom": 50,
    "right": 30,
    "left": 24,
    "hight": 0.01,
    "width": 0.01
  }
}

SpatialExtent: object

spatial extent with resolution information

top: float

The top (north) border.

bottom: float

The bottom (south) border.

right: float

The right (eastern) border.

left: float

The left (wester) border.

hight: float

The top-bottom resolution in projection units.

width: float

The right-left resolution in projection units.

Example
{
  "extent": {
    "top": 53,
    "bottom": 50,
    "right": 30,
    "left": 24,
    "hight": 0.01,
    "width": 0.01
  }
}

FeatureCollectionTile: object

A tile of vector data that represents a spatio-temporal subset of a spatio-temporal vector dataset.

id: string

The identifier of this vector tile.

data: [object Object]

A GeoJSON FeatureCollection.

start_times: string[]

The array that contains that start time values for each vector feature.As date-time string format ISO 8601 must be supported.

string
end_times: string[]

The vector that contains that end time values for each vector feature, in case the the time stamps for all or a subset of slices are intervals. For time instances the from and to time stamps must be equal or empty. As date-time string format ISO 8601 must be supported.

string
Example
{
  "id": "test_data",
  "start_times": [
    "2001-01-01T00:00:00",
    "2001-01-02T00:00:00"
  ],
  "end_times": [
    "2001-01-02T00:00:00",
    "2001-01-03T00:00:00"
  ],
  "data": {
    "features": [
      {
        "id": "0",
        "type": "Feature",
        "properties": {
          "a": 1,
          "b": "a"
        },
        "geometry": {
          "coordinates": [
            24,
            50
          ],
          "type": "Point"
        }
      },
      {
        "id": "1",
        "type": "Feature",
        "properties": {
          "a": 2,
          "b": "b"
        },
        "geometry": {
          "coordinates": [
            30,
            53
          ],
          "type": "Point"
        }
      }
    ],
    "type": "FeatureCollection"
  }
}

StructuredData: object

This model represents structured data that is produced by an UDF and can not be representedas a RasterCollectionTile or FeatureCollectionTile. For example the result of a statistical computation. The data is self descriptive and supports the basic types dict/map, list and table.

description: string

A detailed description of the output format.

data: [object Object]

The structured data. This field contains the UDF specific values (argument or return)as dict, list or table. A dict can be as complex as required by the UDF. A list must contain simple data types example {"list": [1,2,3,4]} * A table is a list of lists with a header, example {"table": [["id","value"], [1, 10], [2, 23], [3, 4]]}

type: string dict, table, list

The type of the structured data that may be of type dict, table or list. This is just a hint for the user howto interpret the provided data.

Example
{
  "description": "Output of a statistical analysis. The univariate analysis of multiple raster collection tiles. Each entry in the output dict/map contains min, mean and max of all pixels in a raster collection tile. The key is the id of the raster collection tile.",
  "data": {
    "RED": {
      "min": 0,
      "max": 100,
      "mean": 50
    },
    "NIR": {
      "min": 0,
      "max": 100,
      "mean": 50
    }
  },
  "type": "dict"
}

MachineLearnModel: object

A machine learn model that should be applied to the UDF data.

framework: string sklearn, pytorch, tensorflow, R

The framework that was used to train the model

name: string

The name of the machine learn model.

description: string

The description of the machine learn model.

path: string

The path/url to the machine learn model file to which the UDF must have read access.

Example
{
  "framework": "sklearn",
  "name": "random_forest",
  "description": "A random forest model",
  "path": "/tmp/model.pkl.xz"
}

ErrorResponse: object

The error message. This class is not part of the UDF API but used to create the UDF test server.

message: string

The error message

traceback: string

The optional python traceback

Example
{
  "message": "string",
  "traceback": "string"
}