API v4 Concepts

Introduction

We are currently developing our API v4. We will gradually add new endpoints to it. V3 will stay unchanged but we encourage you to migrate from v3 to v4 as all new products will only be made available on v4. You can find support for your migration in the API migration section below.
Please don’t hesitate to contact us if you have any questions!

ATTENTION: Currently we only deliver Sentinel data on our new platform.

OpenAPI documentation

The API is implemented as simple REST service supporting a number of resources.
On the integrated OpenAPI documentation you will find the technical description of all available endpoints and you can also try out endpoints after authentication with a valid api key, e.g. this demo key: 39553fb7-7f6f-4945-9b84-a4c8745bdbec


The API key needs to be added to every API request to authenticate the user with „?key=39553fb7-7f6f-4945-9b84-a4c8745bdbec“.If you are testing the API in the OpenAPI Swagger UI just hit the Authenticate Button and insert the API Demo key in the input form.

General remarks

  • The reference coordinate system of all parcel geometries is WGS84/EPSG:4326. The raster-images are projected in EPSG:3857 for web mapping applications.
  • All characters in text fields should be UTF-8.
  • All dates are in this format: YYYY-MM-DD.
  • We are using the open standard formats GeoJSON and WKT to represent and exchange data of geographical features such as points and polygons.
    • ATTENTION: In both formats the coordinate order is: longitude, latitude, so x, y. The most common issue when working with geographical data is a flip of coordinates. If something is not working, always first check if the coordinates are passed correctly between the different systems. This is especially true, when working with javascript mapping libraries (e.g leaflet.js, mapbox.js, Google Map API), where the LatLon base class uses the reverse coordinate order: latitude, longitude.
    • EXCEPTION: There is one exception where we don’t use GeoJSON or WKT for the exchange of geographical data: in the raster product response there is a „bounds“ element, which is an object that can be used directly as input in a Leaflet or Mapbox javascript application. Therefore its coordinate order is latitude, longitude.
  • Whenever you send our API geometries we expect valid parcel geometries according to OGC simple feature specification. We try to make all invalid geometries that we receive valid, e.g. intersecting polygons are splitted into a multipolygon geometry.
  • We reduce parcel geometries to 12 decimal digits and expect them to be valid after that.
  • The minimum parcel size is 0.04 ha, the maximum size 4000 ha. Landsat-8 data is only delivered for parcels larger than 0.4 ha. Below that it doesn’t make sense from a technical point of view.
  • All raster ids can change from time to time. Please make sure your system can cope with that. This is necessary e.g. because we regularly reprocess data to improve data quality and keep track of changing satellite product formats. You can use our Notification Messages to keep track of changes.

API migration v3 -> v4

Below we are summarizing the main differences between API v3 and API v4 and new features to help you prepare your migration.

Changes in API v4

  • Modern tech stack with derived documentation from code, OpenAPI standard
  • On the integrated OpenAPI documentation you can also try out endpoints after authentication with a valid api key
  • Minor versioning in version object of root endpoint of API e.g. `“version“: „4.0.1“`
  • New endpoints and products
  • Bugfixing
  • Improved consistency of endpoint and product logic
  • Reworked error handling:
    • content object does only carry valid data; in case of an error it is not present!
    • error object with category name (e.g. `“Authentication Error“`)
    • error detail object with detail message (e.g. `“key validity expired“`) or list of errors in case of Client data error (HTTP 422)
    • Client data validation errors (HTTP 422 Unprocessable Entity) will be more verbose in response in object detail
    • Status code in HTTP headers of API response according to the error (e.g. `HTTP 401 Unauthorized, HTTP 422 Unprocessable Entity`)

API Endpoint structure

The API endpoint structure of certain endpoints has been changed to increase consistency and logic. Here is a list of changed endpoints: 

Comparison_API_v3_v4_responsesHerunterladen

Image products

png

  • In contrast to API v3 all png images are delivered in 5m resolution. Therefore the image sizes change for the Visible, Vitality and Variations products. The others stay unchanged.
  • In contrast to API v3 all png images can be reprojected on-the-fly using the „&epsg“ parameter.
  • In contrast to API v3 the boundary removal effect can be switched on and off for all pngs. The default is on (consistent to API v3).
  • In contrast to API v3 each product is visualized in its own optimized colormap by default. In API v3 the default colormap was „vitality“ for all products. Therefore the images for one product may look different compared to API v3.

The following table illustrates the changes in png images between API v3 and API v4 for the default colormaps:

For Vitality (and Visible and Variations) the size changes due to the different resolutions of the images. For all other vegetation indexes (Professional Monitoring package) the size and resolution remains  unchanged. Due to the optimized colormaps used for each vegetation index by default in v4, the colour representation of images can change between API v3 and v4. This can be avoided by defining specific colormaps instead of the using the default ones.

geotif

  • In contrast to API v3 the HTTP response content type for geotif images is now ‚image/tif‘. For API v3 it was ‚image/tiff‚.
  • In contrast to API v3 all geotif images are delivered in 10m resolution except the reflectances geotif which contains each band in its native resolution.
  • In contrast to API v3 all geotif images can be reprojected on-the-fly using the „&epsg“ parameter.
  • In contrast to API v3 the boundary removal effect can be switched on and off for all pngs. The default is off (in contrast to API v3).
    Note that if boundary removal effect is active for API v4 requesting a geotif, the spatial resolution will internally be switched to 5m for API v3 compatibility reasons.

The following table illustrates the changes in tif images between API v3 and API v4:

Due to the changes in resolution also the image sizes change to one consistent size and resolution (10 m = native resolution of satellite images) for all products in API v4. In contrast to the pngs the boundary effect is switched off by default for geotifs.

Vitality

  • In contrast to API v3 the Vitality product now contains the same information as the NDVI reflectance product.

SAVI

  • In contrast to API v3 SAVI’s soil correction factor L is now exposed in the API and the user can adjust it for different soils based on his knowledge.

Error handling, API responses and HTTP return codes

Our goal is to provide a consistent and robust API, so developers can rely on the same response structure of any endpoint of the API.
This reduces coding efforts on the client side and thus reduces development time and costs.
Our expertise both in the API backend and also on the frontend side with various widgets enables us to optimize our API for a better integration experience for developers.

General idea of response handling

Due to the consistent structure of the API in v4 the developer’s workflow for reacting on API responses is always the same:

  • check status response code of HTTP headers. e.g. `HTTP 200 OK` or `HTTP 404 Not Found`
  • if the HTTP headers status code is `HTTP 200 OK`
    • process the response as expected:
      • JSON response expected: read the response body, query the content element and process the data for e.g. visualization
      • Binary image data expected: read the response body and process the data
  • otherwise (HTTP headers status code is not `HTTP 200 OK` – e.g. `HTTP 404 Not Found` not found or `HTTP 422 Unprocessable Entity`)
    • there is always a JSON response with two objects: `error` and `detail`; read the response body, query the `error` element for the categorial error message and `detail` for further information on the error.

Error responses for all endpoints in API v4

The structure of all responses in ag|knowledge API v4 complies to the following.

HTTP response status codes except HTTP 422 Unprocessable Entity

Response of the API to any API error except `HTTP 422 Unprocessable Entity`.

Includes an `error` object with the category of the error and a `detail` object storing a detailed message of the error.

Schema

{
    "error": str,
    "detail": str
}

Example

{
    "error": "Authentication Error",
    "detail": "apikey validity expired"
}

HTTP status return code in headers according to the error:

  • HTTP 401 Unauthorized
  • HTTP 403 Forbidden
  • HTTP 404 Not Found
  • HTTP 422 Unprocessable Entity
  • HTTP 500 Internal Server Error

HTTP response status code 422 Unprocessable Entity – Validation Error

Response of the API to a validation error of the input data the client sent in a request to the API.

Schema

{
   "error": str,
   "detail":[
      {
         "loc": List[str],
         "msg": str
         "type": str
      }
   ]
}

Example

{
   "error": "Validation Error",
   "detail":[
      {
         "loc":[
            "query",
            "startdate"
         ],
         "msg":"invalid datetime format",
         "type":"value_error.datetime"
      }
   ]
}

 HTTP status return code in headers: HTTP 422 Unprocessable Entity

Detailed changes in endpoints from API v3 to API v4

API root response

API root v3

GET  https://geocledian.com/agknow/api/v3
{
    "content": "agknow API, version 3.2"
}

HTTP status return code in headers: HTTP 200 OK

API root v4

GET  https://geocledian.com/agknow/api/v4
{
    "content": "Welcome to ag|knowledge API!",
    "version": "4.0.1",
    "links" : {  
      "documentation": "/agknow/api/v4/docs",
      "openapi_json": "/agknow/api/v4/openapi.json"
    }
}

 HTTP status return code in headers: HTTP 200 OK

API Key authentication response

no API key supplied v3

GET  https://geocledian.com/agknow/api/v3/parcels
{
    "content": "missing api key"
}

 HTTP status return code in headers: HTTP 200 OK

no API key supplied v4

GET  https://geocledian.com/agknow/api/v4/colormaps
{
    "error": "Authentication Error",
    "detail": "missing api key"
}

 HTTP status return code in headers: HTTP 401 Unauthorized

API key invalid v3

GET  https://geocledian.com/agknow/api/v3/parcels?key=39553fb7-7f6f-4945-9b84-a4c8745bdbec
{
    "content": "key is not authorized"
}

HTTP status return code in headers: HTTP 200 OK

API key invalid v4

GET  https://geocledian.com/agknow/api/v3/colormaps?key=39553fb7-7f6f-4945-9b84-a4c8745bdbec

{
    "error": "Authentication Error",
    "detail": "key is not authorized"
}

 HTTP status return code in headers: HTTP 401 Unauthorized

API key expired v3

GET  https://geocledian.com/agknow/api/v3/parcels?key=39553fb7-7f6f-4945-9b84-a4c8745bdbec
{  "content": "apikey validity expired" }

 HTTP status return code in headers: HTTP 200 OK

API key expired v4

GET  https://geocledian.com/agknow/api/v4/colormaps?key=39553fb7-7f6f-4945-9b84-a4c8745bdbec
{    "error": "Authentication Error",    "detail": "apikey validity expired" }

 HTTP status return code in headers: HTTP 401 Unauthorized

EUDR Check documentation

The EUDR Check endpoints group is an extension to the existing Ag|Knowledge platform. With a valid subscription for the EUDR Check you’ll have to register an area or a point with some mandatory data (e.g. geometry, production end date, commodity) that are required by the EUDR in our API v4 in a dedicated EUDR Register Parcel endpoint.

Once a parcel is registered, a scheduler process picks up new EUDR parcels every 24h to process the risk analysis and writes it to our backend. The result of the of the EUDR Check can then be obtained with a GET request to the EUDR parcel risk endpoint as follows:

GET https://geocledian.com/agknow/api/v4/eudr/parcels/45642/risk?key=c4287ef1-9373-42b7-a9c0-ae34f53c5e39

and the result (note the GeoJSON format) would look like the following:

{
  "type": "Feature",
  "geometry": {
    "type": "MultiPolygon",
    "coordinates": [
      [
        [
          [-88.602994205, 15.561067359],
          [-88.598675301, 15.560534581],
          [-88.593914305, 15.559933789],
          [-88.594129683, 15.558363793],
          [-88.597978155, 15.557660979],
          [-88.600392661, 15.557972711],
          [-88.60221771, 15.5582391],
          [-88.602926191, 15.5582391],
          [-88.60336545, 15.558338288],
          [-88.602994205, 15.561067359]
        ]
      ]
    ]
  },
  "properties": {
    "parcel_id": 45642,
    "name": "area_1",
    "commodity": "oilpalm",
    "production_start": "2020-12-31",
    "production_end": "2023-12-31",
    "area": 27.3281,
    "geohash": "d4bbxbk",
    "point_buffer_area": 4,
    "deforestation_risk": "low",
    "deforestation_index": 0,
    "deforestation_area_ha": 0,
    "baseline_date": "2020-12-31",
    "sdate": "2023-12-27",
    "landcover_forest_coverage": 0,
    "landcover_plantation_coverage": 1,
    "landcover_shrubs_coverage": 0,
    "landcover_no_trees_coverage": 0,
    "landcover_png_baseline_date": "https://global.geocledian.com/agknow/api/v4/eudr/parcels/45642/risk/1/landcover_mask.png...",
    "rgb_png_baseline_date": "https://global.geocledian.com/agknow/api/v4/parcels/45642/...",
    "rgb_png_production_enddate": "https://global.geocledian.com/agknow/api/v4/parcels/45642/...",
    "country_risk": "standard",
    "model_version": "1.0.9",
    "generation_date": "2024-05-08T20:36:00",
    "map_utils_landcover_legend_png": "https://global.geocledian.com/agknow/api/v4/eudr/parcels/45642/risk/1/landcover_mask.png...",
    "map_utils_scalebar": "https://global.geocledian.com/agknow/api/v4/eudr/parcels/45642/risk/1/landcover_mask.png..."
  },
  "id": 45642,
  "bbox": [
    15.557668681924863, -88.6033654497693, 15.561067359153306,
    -88.59397436795386
  ]
}

Detailed description

The GeoJSON response will include the latest satellite image date available (sdate) and the date of the closest satellite image available for the baseline date of 2020-12-31 (baseline_date). Furthermore the relative area of landcover detected on the registered polygon (landcover_* attributes) is part of the response.
For visualisation purposes links to the satellite data used are provided on the polygon level comprising the True Color Image (RGB) of the latest satellite image date available (rgb_png_production_enddate) and the closest satellite image available for the baseline date of 2020-12-31 (rgb_png_baseline_date). If the deforestation risk was classified as medium or high a link to the change detection analysis is provided (forest_change_png). Additionally the absolute area of deforestation (deforestation_area_ha) and the relative area of deforestation of the forest area within the parcel is provided (deforestation_index) between 0 (no deforestation) and 100 (forest area completely affected by deforestation).
The EUDR states that all countries will be assigned to a specific risk level (country_risk). Currently all countries have been assigned to a standard risk level until the EU publishes a detailed list with a dedicated risk level for each country. The internal algorithm used is stored in a version tag (model_version), while the date of the EUDR Check generation result is also available (generation_date).
For visualisation purposes you can also obtain legends to the map results and a scalebar as image with all the map_utils_* links.
On the integrated OpenAPI documentation you will find detailed description for all EUDR endpoints.