API Reference

Supported endpoints

/timeseries_by_area

GET Endpoint for requesting Sentinel-1 (S1), Sentinel-2 (S2) timeseries.

The following input parameters are accepted:

Parameter	Type	Priority	Default	Description
`timeseries_from`	timestamp with time zone	Required		Timestamp since which the updated time series will be returned. All the results that have been updated exactly on `updates_from` timestamp or later until the `updates_to` will be returned.
`timeseries_to`	timestamp with time zone	Optional	`now()` at time zone in DB	Timestamp up to which the updated time series will be returned. All the results that have been updated exactly on `updates_from` timestamp or later until the `updates_to` will be returned.
`query_area`	text	Required		Define the polygon in WKT format that surrounds the area of interest, e.g. POLYGON((25.376 58.778,25.376 58.819,25.482 58.819,25.482 58.778,25.376 58.778))
`properties`	text	Optional	All properties	Define the returned properties, e.g. `/timeseries&properties=id,cohvh_avg`.
`format`	text	Optional	`json`	Define the format of returned results. `json` for JSON, `txt` for txt file.
`page`	integer	Optional		Toggle pagination of returned results and define which page is returned. Number of results is limited to 10000 per page.

The following output parameters ("properties") are supported:

Parameter	Type	Description
`id`	integer	Unique id of the estimate.
`parcel_foreign_id`	text	Foreign id of the parcel which the time series data point applies to.
`s1product_end_time`	timestamp with time zone	Timestamp of the S1 time series data point.
`cohvh_min`	float	Minimum VH coherence (S1).
`cohvh_avg`	float	Average VH coherence (S1).
`cohvh_max`	float	Maximum VH coherence (S1).
`cohvh_std`	float	Standard deviation of VH coherence (S1).
`cohvv_min`	float	Minimum VV coherence (S1).
`cohvv_avg`	float	Average VV coherence (S1).
`cohvv_max`	float	Maximum VV coherence (S1).
`cohvv_std`	float	Standard deviation of VV coherence (S1).
`vhvv_min`	float	Minimum VH / VV ratio (S1).
`vhvv_avg`	float	Average VH / VV ratio (S1).
`vhvv_max`	float	Maximum VH / VV ratio (S1).
`vhvv_std`	float	Standard deviation of VH / VV ratio (S1).
`s0vh_min`	float	Minimum VH sigma0 (S1).
`s0vh_avg`	float	Average VH sigma0 (S1).
`s0vh_max`	float	Maximum VH sigma0 (S1).
`s0vh_std`	float	Standard deviation of VH sigma0 (S1).
`s0vv_min`	float	Minimum VV sigma0 (S1).
`s0vv_avg`	float	Average VV sigma0 (S1).
`s0vv_max`	float	Maximum VV sigma0 (S1).
`s0vv_std`	float	Standard deviation of VV sigma0 (S1).
`linc`	float	Incidence angle (S1).
`updated_at`	timestamp with time zone	Timestamp of the last update on the estimate. Mutually exclusive with `result_deleted`.
`deleted_at`	timestamp with time zone	Timestamp of the deletion of the estimate. Mutually exclusive with `result_updated`.

Python code example

import requests
import json

# api-endpoint
URL = "https://demodev.kappazeta.ee/api/demo/timeseries_by_area"

# defining the area and time frame of interest
query_area = "POLYGON((25.376 58.778,25.376 58.819,25.482 58.819,25.482 58.778,25.376 58.778))"
timeseries_from = "2019-05-01"
timeseries_to = "2019-05-11"
properties = "parcel_id,cohvh_avg,cohvv_avg,s0vh_min,s0vh_max,s0vh_avg,s0vh_std,linc"
PARAMS = {'query_area':query_area,
          'timeseries_from':timeseries_from,
          'timeseries_to':timeseries_to,
          'properties':properties
         }

# sending get request and saving the response as response object
r = requests.get(url = URL, params = PARAMS)

# extracting data in json format
data = r.json()

# printing the formatted output
print(json.dumps(data, indent=2))

/parcel

GET Endpoint for requesting parcel parameters.

The following input parameters are accepted:

Parameter	Type	Priority	Default	Description
`parcel_foreign_id`	text	Optional	All parcels	Foreign id of the parcel to request.
`client_foreign_id`	text	Optional	All clients	Foreign id of the client to request.
`crop_foreign_code`	text	Optional	All crops	Foreign code of the crop to request.
`landuse_foreign_code`	text	Optional	All landuse types	Foreign code of the landuse type to request.
`query_area`	WKT geometry	Optional	Extent of parcels in DB	A WKT POLYGON or MULTIPOLYGON (in the EPSG:4326 coordinate system) which determines the area where the results will be returned.
`properties`	text	Optional	All properties	Define the returned properties, e.g. `/parcel&properties=id,geometry`.
`format`	text	Optional	`json`	Define the format of returned results. `json` for JSON, `txt` for txt file.

At least one of the following parameters must be specified:
parcel_foreign_id, client_foreign_id, crop_foreign_code, landuse_foreign_code.

The following output parameters ("properties") are supported:

Parameter	Type	Description
`parcel_foreign_id`	text	Foreign id of the parcel.
`client_foreign_id`	text	Foreign id of the client (owner of the parcel).
`client_name`	text	Name of the client (owner of the parcel).
`crop_code`	text	Code string of the crop type.
`crop_foreign_code`	text	Foreign code string of the crop type.
`landuse_code`	text	Code string of the landuse type.
`landuse_foreign_code`	text	Foreign code string of the landuse type.
`created_at`	timestamp with time zone	Timestamp of creation.
`updated_at`	timestamp with time zone	Timestamp of the last update on the parcel.
`geometry`	WKT geometry	Geometry of the parcel.
`area`	real	Parcel area in ha.

Python code example

import requests
import json

# api-endpoint
URL = "https://demodev.kappazeta.ee/api/demo/parcel"

# defining the area and properties of interest
query_area = "POLYGON((25.376 58.778,25.376 58.819,25.482 58.819,25.482 58.778,25.376 58.778))"

properties = "parcel_foreign_id,client_foreign_id,crop_foreign_code,landuse_foreign_code"
PARAMS = {'query_area':query_area, 'properties':properties}

# sending get request and saving the response as response object
r = requests.get(url = URL, params = PARAMS)

# printing the output in json format
print(json.dumps(r.json(), indent=2))

/status

GET Endpoint for verifying connectivity.

The endpoint outputs the following parameters:

Parameter	Type	Description
`status`	text	Service status. One of the following: `ok`, `error`.
`api_version`	text	Version of the API.
`schema_version`	text	Version of the database schema.
`authentication_required`	boolean	Whether authentication is required.

Python code example

import requests
import json

# api-endpoint
URL = "https://demodev.kappazeta.ee/api/demo/status"

# sending get request and saving the response as response object
r = requests.get(url = URL)

# printing the output in json format
print(json.dumps(r.json(), indent=2))

Try a demo of the time series API here.