API GUIDE

RESTful API

1. Scope

General concepts related to the GreenSense API are discussed here, e.g. which kind of data are available and what’s the general idea of the API structure.

Detailed technical specification of the API is provided in the OpenAPI format. 

2. Overview

There are two broad types of API endpoints provided by GreenSense:

  1. Endpoints not aware of field boundaries: Such endpoints are stateless, read-only and operate independently from each other. Authentication is used only for the accounting purpose.
  2. Field-oriented endpoints: Such endpoints are focused around a concept of a field being owned by a particular user. Such endpoints maintain a field state (e.g. crop type, planting date, etc.) which can be modified by the user affecting the output of the endpoints.

3. General technical information

  • If not stated otherwise all responses return data in the application/json format.
  • Non-GET request methods handle input parameters in any of the application/x-www-form-urlencoded (default), application/json or multipart/form-data formats. If a non-default format is used, it should be indicated using the Content-Type HTTP header.
  • The errors are reported using HTTP status codes. The response payload may or may not contain a human-readable description of the error.
  • Authentication is done with the HTTP basic method.
  • All the dates are in the YYYY-MM-DD format.

4. Field-unaware endpoints

This group of endpoints serve crop growth-related indicators (e.g. NDVI, LAI, historical productivity). Each endpoint returns a given indicator value for a given area at a given date. There are both XYZ map service endpoints available and the ones returning data as JSON tables.

Data availability

Data availability depends on the indicator:
• All single satellite acquisition-based indicators (e.g. NDVI, LAI) come in 2 to 5 days intervals (depending on the region) and are available worldwide. An acquisition can be skipped due to bad weather conditions (clouds) which can be an issue in some parts of the world and/or some parts of a year.
• Compound indicators (here it is only the historical productivity map) are updated yearly. Currently they are available in Austria but we can compute them worldwide.

Free testing

We can provide single satellite acquisition-based indicators for any area in the world for testing. Just let us know what is your region of interest and wait a few days for a next satellite acquisition. The historical productivity map is available for testing only for the Austria. User accounts for using field-unaware endpoints are created on-demand by the GreenSense team.

5. Field-oriented endpoints

Field-aware endpoints focus around following concepts:

  • An owner (a farmer). Client of a service. Identified by a login (typically but not necessarily an email). If there is a man in the middle (a reseller) it can be both the enduser (a farmer) or a reseller, it does not make a difference to us.
  • A polygon (a field, a parcel). It is identified by a number. It stores information about a georeferenced shape (a geometry), a crop planted on the field, etc. stored information are used in the data processing algorithms (e.g. the crop type and amount of irrigation is used to compute the right irrigation advice). Each field belongs to an owner and only its owner can interact with it.

To use a field-oriented endpoints user must first register an account (there is an API endpoint for that) and create his polygons (fields).

Currently there are two field-oriented services available

  • The irrigation advice service computing a water balance for fields. It takes into account weather, crop type, soil properties (if a soil map is available for the region) and information on irrigation provided by the user. It provides both detailed water balance history since planting and a simple irrigation advice – how much to water the field.
  • The segmentation service performing a field segmentation according to a given indicator (e.g. most recent productivity or historical productivity map). Depending on the indicator used for the segmentation it can be further used for various tasks, e.g. a variable rate fertilizer application (there is a separate API endpoint taking the segmentation and a few fertilization parameters like minimum and maximum amount of fertilizer and returning an fertilization machinery-readable shapefile).

Data availability

Both the irrigation and the segmentation services can handle fields worldwide.

Free testing

There is a demo account (user: demo with password: demo) allowing to test services with fields in a few selected regions (Europe, around Cape Town in South Africa, around Adelaide in Australia). If you want another region to be included, contact us.