Overview
Our Professional Monitoring products extend the basic monitoring package by offering additional remote sensing indices and products.Please also see the general API documentation here.
Base URL
URL: „https://geocledian.com/agknow/api/v3“ (or „https://geocledian.com/agknow/“)
Available professional monitoring products
At the moment all professional monitoring products are available for Sentinel-2 only!
Raster products
The following raster products are available in our professional monitoring package.
| product name | description | used bands | value range | NODATA value (tif) | format |
| ndvi | Normalized Difference Vegetation Index (based on reflectance data) | based on Red (B04) & NIR (B08) bands | [-1; 1] | -99999 | png, tif |
| ndre1 | Normalized Difference Red Edge Index (v1) | based on Vegetation Red Edge 1 & 2 (B06 & B05) bands | [-1; 1] | -99999 | png, tif |
| ndre2 | Normalized Difference Red Edge Index (v2) | based on Vegetation Red Edge 1 & 3 (B07 & B05) bands | [-1; 1] | -99999 | png, tif |
| ndwi | Normalized Difference Water Index | based on NIR (B08) & SWIR 1 (B11) bands | [-1; 1] | -99999 | png, tif |
| savi | Soil Adjusted Vegetation Index | based on Red (B04) & NIR (B08) bands | [-1; 1] | -99999 | png, tif |
| evi2 | Enhanced Vegetation Index 2 | based on Vegetation Red Edge 1 (B05) & Narrow NIR (B8A) bands | [-0.735; 1.25] | -99999 | png, tif |
| cire | Chlorophyll Index – Red Edge | based on Vegetation Red Edge 1 & 3 (B07 & B05) | [-1; ca. 9] | -99999 | png, tif |
| npcri | Normalized Pigment Chlorophyll Ratio Index | based on Blue (B02) & Red (B04) bands | [-1; 1] | -99999 | png, tif |
| reflectances | „Raw“ top of atmosphere reflectances for all available bands (13 or 5 bands) | -/- | [0; 10000] | 0 | tif |
The reflectances raster product will be served as 16Bit unsigned integer GeoTiff with the original available satellite bands. Either 13 bands or 5 bands are available depending on the agreed processing mode for the region of interest.
As in the „raw“ satellite image products its values range from 0 to 10000 and have to be divided by 10000 to get reflectances (0 – 100 %).
As this product is intended to be as close as possible to the „raw“ satellite data it does not include any parcel border correction.
All other raster products of Professional Monitoring are available as 32Bit float GeoTiff or as PNG.
They are computed on top of atmosphere reflectance values.
Please don’t hesitate to contact us if you need an upgrade to 13 bands for your region of interest! This enables the delivery of all available indices.
Rasters products
Resource associated to parcels
Resource URL: /parcels/<id>/<product_name>
List
Function lists all available rasters for that product for the parcel. A summary element is given if &statistics=true is set. In this case additional key elements, such as „doy“ for day of year are added to the response list.
ATTENTION: 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. Unlike in GeoJSON or WKT representations of geographical features its coordinate order is latitude, longitude.
HTTP Request:
GET https://geocledian.com/agknow/api/v3/parcels/<parcel-id>/<product_name>?key=kkk&statistics=sss&startdate=ddd&enddate=eee&deltadays=ttt&order=~datePath Parameters
| parcel-id | id of parcel |
| product_name | Rasters product. Valid values for professional monitoring: „ndvi“,“ndre1″,“ndre2″,“ndwi“,“savi“,“evi2″,“cire“, „nprci“ and „reflectances“ |
Required parameters
| key | registered user key to authorize user default: none |
Optional parameters
| statistics | Add the statistics object to the rasters objects. Valid value: „true“ (works with all raster products except reflectances) default: false |
| source | Filter the list by source, else a combined list of products derived from Sentinel-2 and Landsat-8 will be returned. Valid values: „sentinel2“, „landsat8“ default: sentinel2 ATTENTION: At the moment all professional products are implemented for Sentinel-2 only, so you will not find data for source=landsat8 |
| startdate | start date in ANSI format: YYYY-MM-DD, e.g. 2015-03-20. default = „1900-01-01“ |
| enddate | end date in ANSI format: YYYY-MM-DD, e.g. 2015-10-20. default = „2900-01-01“ |
| delta_days | Offset days after startdate, which should appear in the raster product list. If the enddate parameter is given too, then the one which is closer to start_date will be applied. default = 999999 |
| order | sort order of the list. e.g. latest date first possible values: „date“, „~date“ default „~date“ for latest date to first date descending |
| lon | longitude coordinate, add the pixel value of the raster product at the requested location to the response list (element name: „pixel_value“). valid values: [-180.0, 180.0] Requires a valid lat parameter too. default: none ATTENTION: works with all raster products except reflectances |
| lat | latitude coordinate, add the pixel value of the raster product at the requested location to the response list (element name: „pixel_value“). valid values: [-75.0, 75.0] Requires a valid lon parameter too. default: none ATTENTION: works with all raster products except reflectances |
Response:
{
"content":[
{
"bounds":[
[
{
"latmin - number"
},
{
"lonmin - number"
}
],
[
{
"latmax - number"
},
{
"lonmax - number"
}
]
],
"parcel_id":{
"Number"
},
"raster_id":{
"Number"
},
"date":{
"string"
},
"product":{
"string"
},
"source":{
"string"
},
"png":{
"string"
},
"pixel_value":{
"Number"
},
"doy":{
"Number"
},
"days_after_startdate":{
"Number"
},
"statistics":{
"count":{
"Number"
},
"sum":{
"Number"
},
"mean":{
"Number"
},
"stddev":{
"Number"
},
"max":{
"Number"
},
"min":{
"Number"
}
}
},
{
"... next raster description"
}
],
"summary":{
"count":{
"Number"
},
"min":{
"Number"
},
"max":{
"Number"
},
"sum":{
"Number"
},
"stddev":{
"Number"
},
"mean":{
"Number"
},
"first_date":{
"string"
},
"last_date":{
"string"
},
"delta_days":{
"Number"
},
"first_date_doy":{
"Number"
},
"last_date_doy":{
"Number"
},
"first_date_days_after_startdate":{
"Number"
},
"last_date_days_after_startdate":{
"Number"
}
}
}Example
GET https://geocledian.com/agknow/api/v3/parcels/129815/ndre1?key=39553fb7-7f6f-4945-9b84-a4c8745bdbecResponse:
{
"content":" "[
{
"parcel_id": 129815,
"bounds":" "[
[
48.4343648520054,
1.368812
],
[
48.438812,
1.37420690084588
]
],
"raster_id": 3969739,
"date":" ""2018-10-13",
"product":" ""ndre1",
"source":" ""sentinel2",
"png":" ""/parcels/129815/ndre1/sentinel2/3969739.png"
},
{
"... next object"
}
]
}Get
Function returns metadata for a single raster product.
ATTENTION: 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. Unlike in GeoJSON or WKT representations of geographical features its coordinate order is latitude, longitude.
HTTP Request:
GET https://geocledian.com/agknow/api/v3/parcels/<parcel-id>/<product_name>/<source_name>/<raster-id>&key=kkk&statistics=sss&lon=ooo&lat=aaaPath parameters
| parcel-id | id of parcel |
| product_name | Rasters product. valid values for professional monitoring: „ndvi“,“ndre1″,“ndre2″,“ndwi“,“savi“,“evi2″,“cire“,“nprci“ and „reflectances“ |
| source_name | Source of the raster product. valid values: „sentinel2“, „landsat8“ default: sentinel2 ATTENTION: At the moment all professional products are implemented for Sentinel-2 only! |
| raster-id | id of raster. The raster-id is unique only for one product, e.g. „ndre1“. The rasters for different products, e.g. „ndwi“, „savi“, etc have the same id. |
Required parameters
| key | registered user key to authorize user default: none |
Optional parameters
| statistics | Add the statistics object to the rasters objects. Valid value: „true“ default: false ATTENTION: works with all raster products except reflectances |
| lon | longitude coordinate, add the pixel value of the index at the requested location to the response content (element names: „pixel_value“ and „lon_lat“). valid values: [-180.0, 180.0] Requires a valid lat parameter too default: none ATTENTION: works with all raster products except reflectances |
| lat | latitude coordinate, add the pixel value of the index at the requested location to the response content (element names: „pixel_value“ and „lon_lat“). valid values: [-75.0, 75.0] Requires a valid lon parameter too default: none ATTENTION: works with all raster products except reflectances |
GET https://geocledian.com/agknow/api/v3/parcels/129815/savi/sentinel2/3969739?key=39553fb7-7f6f-4945-9b84-a4c8745bdbec Response:
{
"content":[
{
"product":"savi",
"parcel_id":129815,
"bounds":[
[
48.4343648520054,
1.368812
],
[
48.438812,
1.37420690084588
]
],
"source":"sentinel2",
"raster_id":3969739,
"date":"2018-10-13",
"png":"/parcels/129815/savi/sentinel2/3969739.png"
}
]
}
Example for reflectances (13 bands)
GET https://geocledian.com/agknow/api/v3/parcels/129815/reflectances/sentinel2/3969739?key=39553fb7-7f6f-4945-9b84-a4c8745bdbec
Response:
{
"content":[
{
"product":"reflectances",
"epsg_code":32631,
"parcel_id":129815,
"bounds":[
[
48.4343648520054,
1.368812
],
[
48.438812,
1.37420690084588
]
],
"bands_metadata":{
"B10":"Sentinel-2: B9, 940 nm (Water vapour), 60m",
"B11":"Sentinel-2: B10, 1375 nm, (SWIR Cirrus), 60m",
"B14":"Cloud mask",
"B4":"Sentinel-2: B4, 665 nm (Red), 10m",
"B5":"Sentinel-2: B5, 705 nm (Vegetation red edge 1), 20m",
"B6":"Sentinel-2: B6, 740 nm (Vegetation red edge 2), 20m",
"B7":"Sentinel-2: B7, 783 nm (Vegetation red edge 3), 20m",
"B12":"Sentinel-2: B11, 1610 nm (SWIR 1), 20m",
"B13":"Sentinel-2: B12, 2190 nm (SWIR 2), 20m",
"B2":"Sentinel-2: B2, 490 nm (Blue), 10m",
"B3":"Sentinel-2: B3, 560 nm (Green), 10m",
"B8":"Sentinel-2: B8, 842 nm (NIR), 10m",
"B9":"Sentinel-2: B8A, 865 nm (Narrow NIR), 20m",
"B1":"Sentinel-2: B1, 443 nm (Coastal aerosol), 60m"
},
"source":"sentinel2",
"raster_id":3969739,
"date":"2018-10-13",
"png":"/parcels/129815/reflectances/sentinel2/3969739.tif"
}
]
}
ATTENTION: the resulting JSON dictionary for bands_metadata will not be ordered! The cloud mask band (B14 resp. B6) mainly contains NODATA values as we already filter out cloudy images (> 5% cloud coverage) in our processing chain.
Example for reflectances (5 bands)
GET https://geocledian.com/agknow/api/v3/parcels/131630/reflectances/sentinel2/4398103?key=39553fb7-7f6f-4945-9b84-a4c8745bdbec
{
"content":[
{
"product":"reflectances",
"epsg_code": 32632,
"parcel_id":3243,
"bounds":[
[
45.1183299034536,
10.8280456066132
],
[
45.1247009515298,
10.8384781978379
]
],
"bands_metadata":{
"B6":"Cloud mask",
"B3":"Sentinel-2: B4, 665 nm (Red), 10m",
"B1":"Sentinel-2: B2, 490 nm (Blue), 10m",
"B2":"Sentinel-2: B3, 560 nm (Green), 10m",
"B4":"Sentinel-2: B8, 842 nm (NIR), 10m",
"B5":"Sentinel-2: B8A, 865 nm (Narrow NIR), 20m"
},
"source":"sentinel2",
"raster_id": 1084398,
"date":"2015-11-24",
"png":"/parcels/3243/reflectances/sentinel2/1084398.tif"
}
]
}Raster
Function returns png or geotiff raster product file.
- PNG images are projected in EPSG:3857 for web mapping applications.
- GeoTiff images are served in original UTM projection of the satellite scene; for reflectances you may provide an optional parameter &epsg= to transform the geotiff to the desired EPSG projection
- Index raster products are available as 32Bit Float GeoTiff, „reflectances“ raster products are 16Bit unsigned integer GeoTiff.
The spatial resolution is both for png and geotiff 5m for all products except for „reflectances“ which has a spatial resolution of 10m.
HTTP Request:
GET https://geocledian.com/agknow/api/v3/parcels/<parcel-id>/<product_name>/<source_name>/<raster-id>.<format>?key=kkk&legend=lll&epsg=ccccPath parameters
| parcel-id | id of parcel |
| product_name | Rasters product. valid values:“ndvi“,“ndre1″,“ndre2″,“ndwi“,“savi“,“evi2″,“cire“,“nprci“,“reflectances“ |
| source_name | Source of the raster product. Valid values: „sentinel2“, „landsat8“. ATTENTION: At the moment all professional products are implemented for Sentinel-2 only! |
| raster-id | id of raster. The raster-id is unique only for one product, e.g. „ndre1“. The rasters for different products, e.g. „ndre2“, „savi“ etc. have the same id. |
| format | desired format, currently .png and .tif are supported ATTENTION: all raster products except reflectances support png and geotiff. reflectances is only available as geotiff. |
Required parameters
| key | registered user key to authorize user default: none |
Optional parameters
| legend | Instead of the parcel image a colormap is shown which can be used as a legend. Valid value: „true“ default: none ATTENTION: works with all raster products except reflectances |
| epsg | If provided it will be attempted to transform the geotiff to the spatial reference system of the given EPSG code. Valid values: integer in the range from 2000 to 32766. default: none (means original UTM projection of the satellite scene) ATTENTION: projection parameter &epsg= is currently only available for reflectances. |
Response:png or geotiff file
Normalized Difference Vegetation Index (NDVI calculated from reflectances)
Example of a raster image for the ndvi product
GET https://geocledian.com/agknow/api/v3/parcels/129815/ndvi/sentinel2/3952611.png?key=39553fb7-7f6f-4945-9b84-a4c8745bdbec
Example of ndvi legend
GET https://geocledian.com/agknow/api/v3/parcels/129815/ndvi/sentinel2/3952611.png?key=39553fb7-7f6f-4945-9b84-a4c8745bdbec&legend=true0.1 (NDVI) 0.9
The colormap visualizes values from -1.0 to +1.0.
Normalized Difference Red-Edge Index 1 (NDRE1)
Example of a raster image for the ndre1 product
GET https://geocledian.com/agknow/api/v3/parcels/129815/ndre1/sentinel2/3952611.png?key=39553fb7-7f6f-4945-9b84-a4c8745bdbec
Example of ndre1 legend
GET https://geocledian.com/agknow/api/v3/parcels/129815/ndre1/sentinel2/3952611.png?key=39553fb7-7f6f-4945-9b84-a4c8745bdbec&legend=true0.1 (NDRE1) 0.9
The colormap visualizes values from -1.0 to +1.0.
Normalized Difference Red-Edge Index 2 (NDRE2)
Example of a raster image for the ndre2 product
Example of ndre2 legend
GET https://geocledian.com/agknow/api/v3/parcels/129815/ndre2/sentinel2/3952611.png?key=39553fb7-7f6f-4945-9b84-a4c8745bdbec&legend=true0.1 (NDRE2) 0.9
The colormap visualizes values from -1.0 to +1.0.
Normalized Difference Water Index (NDWI)
Example of a raster image for the ndwi product
GET https://geocledian.com/agknow/api/v3/parcels/129815/ndwi/sentinel2/3952611.png?key=39553fb7-7f6f-4945-9b84-a4c8745bdbec
Example of ndwi legend
GET https://geocledian.com/agknow/api/v3/parcels/129815/ndwi/sentinel2/3952611.png?key=39553fb7-7f6f-4945-9b84-a4c8745bdbec&legend=true0.1 (NDWI) 0.9
The colormap visualizes values from -1.0 to +1.0.
Soil adjusted Vegetation Index (SAVI)
Example of a raster image for the savi product
GET https://geocledian.com/agknow/api/v3/parcels/129815/savi/sentinel2/3952611.png?key=39553fb7-7f6f-4945-9b84-a4c8745bdbec
Example of savi legend
GET https://geocledian.com/agknow/api/v3/parcels/129815/savi/sentinel2/3952611.png?key=39553fb7-7f6f-4945-9b84-a4c8745bdbec&legend=true0.1 (SAVI) 0.9
The colormap visualizes values from -1.0 to +1.0.
Enhanced Vegetation Index 2 (EVI2)
Example of a raster image for the evi2 product
GET https://geocledian.com/agknow/api/v3/parcels/129815/evi2/sentinel2/3952611.png?key=39553fb7-7f6f-4945-9b84-a4c8745bdbec
Example of evi2 legend
GET https://geocledian.com/agknow/api/v3/parcels/129815/evi2/sentinel2/3952611.png?key=39553fb7-7f6f-4945-9b84-a4c8745bdbec&legend=true0.1 (EVI2) 0.9
The colormap visualizes values from -0.7 to +1.25.
Chlorophyll Red-Edge Index (CI-RE)
Example of a raster image for the cire product
GET https://geocledian.com/agknow/api/v3/parcels/129815/cire/sentinel2/3952611.png?key=39553fb7-7f6f-4945-9b84-a4c8745bdbec
Example of cire legend
GET https://geocledian.com/agknow/api/v3/parcels/129815/cire/sentinel2/3952611.png?key=39553fb7-7f6f-4945-9b84-a4c8745bdbec&legend=true0.1 (CI-RE) 8.0
The colormap visualizes values from -1.0 to +9.0.
Normalized Pigment Chlorophyll Ratio Index (NPCRI)
Example of a raster image for the nprci product
GET https://geocledian.com/agknow/api/v3/parcels/129815/npcri/sentinel2/3952611.png?key=39553fb7-7f6f-4945-9b84-a4c8745bdbec
Example of nprci legend
GET https://geocledian.com/agknow/api/v3/parcels/129815/npcri/sentinel2/3952611.png?key=39553fb7-7f6f-4945-9b84-a4c8745bdbec&legend=true0.1 (NPRCI) 1.0
The colormap visualizes values from -1.0 to +1.0.
Reflectances
Example of a raster image for the reflectances product (original UTM projection)
GET https://geocledian.com/agknow/api/v3/parcels/129815/reflectances/sentinel2/3952611.tif?key=39553fb7-7f6f-4945-9b84-a4c8745bdbecExample of a raster image for the reflectances product in another EPSG code (31468)
GET https://geocledian.com/agknow/api/v3/parcels/129815/reflectances/sentinel2/3952611.tif?key=39553fb7-7f6f-4945-9b84-a4c8745bdbec&epsg=31468&epsg=31468Statistics
Resource associated to parcelsResource URL: /parcels/<id>/<product_name>?statistics=true
List
Function delivers time series information about the statistical development of an index of the parcel. It is the same URL as the raster list for each raster product, but requires the &statistics=true parameter at the end.
This functionality is available for all raster products except „reflectances“.
HTTP Request:
GET https://geocledian.com/agknow/api/v3/parcels/<parcel-id>/<product_name>?key=kkk&statistics=true
Path Parameters
| parcel-id | id of parcel |
| product_name | Rasters product. Valid values: „ndvi“,“ndre1″,“ndre2″,“ndwi“,“savi“,“evi2″,“cire“ |
Required parameters:
| key | registered user key to authorize user default: none |
| statistics | Add the statistics object to the rasters objects. Valid value: „true“ default: none |
Response:
{
"content": [
{
"bounds": [
[
{latmin - number},
{lonmin - number}
],
[
{latmax - number},
{lonmax - number}
]
],
"parcel_id": {Number},
"raster_id": {Number},
"date": {string},
"product": {string},
"source": {string},
"png": {string},
"statistics": {
"count": {Number},
"sum": {Number},
"mean": {Number},
"stddev": {Number},
"max": {Number},
"min": {Number}
}
},
{
... next raster description
}
]
}
Example:
GET https://geocledian.com/agknow/api/v3/parcels/4483/ndre1?key=39553fb7-7f6f-4945-9b84-a4c8745bdbec&statistics=trueResponse:
{
"content":[
{
"parcel_id":3243,
"bounds":[
[
45.1183299034536,
10.8280456066132
],
[
45.1247009515298,
10.8384781978379
]
],
"raster_id":161504,
"date":"2015-10-12",
"product":"ndre1",
"source":"sentinel2",
"png":"/parcels/3243/ndre1/161504.png",
"statistics":{
"count":7545,
"min":-0.0270926225930452,
"max":0.400043338537216,
"sum":688.139426073849,
"stddev":0.0718575498030961,
"mean":0.0912046953046851
}
},
{
"... next object"
}
]
}WMS Interface Description
In principle it is very difficult to transfer the logic of the ag|knowledge API to a static WMS definition. Ag|knoweldge offers highly dynamic content and time series, both are not supported by the WMS definition. Thus a standard WMS will not be supported. Specific parameters have to be passed. Overall we do not consider WMS as a useful interface on the long term. To help you get started if you rely on WMS for technical reasons we have implemented a WMS GetMap request. Get Capabilities will not be supported.
| Parameter | Description | Mandatory | Remark |
| VERSION= | Version of WMS | – | ignored |
| REQUEST= | GetMap | yes | only GetMap allowed |
| SRS= | Coordinate Reference System | no | Only namespace EPSG will be supported. Currently only 3857 and 32632 are supported. |
| BBOX= | Bounding Box according to the specification | yes | |
| WIDTH= HEIGHT= | Width and Height of the image according to the specification | yes | |
| LAYERS= | Layer names comma separated | yes | The layer name specifies the product type: „VISIBLE“, „VITALITY“, „VARIATIONS“ |
| STYLES= | Style parameter | – | ignored |
| FORMAT= | MIME format string | – | ignored, always .png will be delivered. |
| TRANSPARENT= | Transparency | – | ignored, always set to true |
| KEY= | User key as used by ag|knowledge | yes | |
| TIME= | Show layers for a specific time | no | Will take the latest images before this point in time. Date format: „YYYY-MM-DD“ Default: latest image will be returned |
| PARCELS= | List of parcels to be shown | no | Can be used to identify one or more parcels. |
| ENTITY= | Filter string for entity field | no | Only if PARCELS parameter is omitted |
| NAME= | Filter string for name field | no | Only if PARCELS parameter is omitted |
| CROP= | Filter string for name field | no | Only if PARCELS parameter is omitted |
| SOURCE= | Filtering string for source field | no | The source of the product images: use „sentinel2“ or „landsat8“ if you want only a specific source. Combined images are shown from both sources, if the parameter is not specified. |
Example:
Data quality
For the time series statistics of all spectral index products except NDWI and CIRE, cloud fags (date markers) are provided with the additional query parameter „&clouds=true“. The cloud and cloud shadow detection algorithm is dynamic and its output is list of data points from the time series which were contaminated by clouds and cloud shadow pixels aftter the initial cloud masking.
Through this, such data points can be removed from further analysis or can be removed or flagged in any time series visualization client.
This function is optional because waterlogging events, floods and snowcover are also flagged as „outliers“, although some use cases also require the analysis of such specific data points and anomalies.
Example:
GET https://geocledian.com/agknow/api/v3/parcels/4483/ndre1?key=39553fb7-7f6f-4945-9b84-a4c8745bdbec&statistics=true&clouds=trueResponse:
{
"content":[
{
"parcel_id":3243,
"bounds":[
[
45.1183299034536,
10.8280456066132
],
[
45.1247009515298,
10.8384781978379
]
],
"raster_id":161504,
"date":"2015-10-12",
"product":"ndre1",
"source":"sentinel2",
"png":"/parcels/3243/ndre1/161504.png",
"statistics":{
"count":7545,
"min":-0.0270926225930452,
"max":0.400043338537216,
"sum":688.139426073849,
"stddev":0.0718575498030961,
"mean":0.0912046953046851
}
},
{
"... next object"
}
]"outliers":[
{
"status":"clouds",
"date":"2018-11-03",
"name":"outlier",
"mean":0.194239255629088
},
{
"status":"clouds",
"date":"2018-11-03",
"name":"outlier",
"mean":0.194239255629088
},
{
"status":"clouds",
"date":"2018-11-03",
"name":"outlier",
"mean":0.194239255629088
}
]
}