NAV
cURL Python

Introduction

BASE URL

https://api.riscognition.io

Welcome to the Riscognition API Docs!

Riscognition provides API products, tools and resources that enable you to harness the power of satellites
and other platforms by processing and preparing the data and making it available.

Our API is organized around REST, has predictable resource-oriented URLs, returns JSON-encoded responses
and uses standard HTTP response codes as well as API-Keys for authentication.

We regularly update and improve our services and may use different version numbers for major design changes.
These improvements make it important for you to stay informed so you don’t miss any updates.

Authentication

Authorization via Query Param:

curl https://api.riscognition.io/burned_areas?key=YOUR-API-KEY

response = requests.get("https://api.riscognition.io/hotspots?key=YOUR-API-KEY")

Authorization via Header:

curl https://api.riscognition.io/burned_areas \
-H 'Authorization: Bearer YOUR-API-KEY'

headers = {'Authorization': 'Bearer YOUR-API-KEY'}
response = requests.get("https://api.riscognition.io/hotspots", headers = headers)

Authorization via Basic Auth:

curl https://api.riscognition.io/burned_areas \
-u 'YOUR-API-KEY'

The Riscognition API uses API keys to authenticate requests. We offer a developer portal to manage API keys yourself on https://riscognition.io.

The Riscogntion API expects for the API key to be included in all API requests to the server. Authentication to the API is performed via query parameter, bearer token or basic auth.

Query Parameter: key=YOUR-API-KEY
Header: Authorization: Bearer YOUR-API-KEY
Basic auth: username: YOUR-API-KEY

🌡️ Hotspots

ENDPOINTS

GET /hotspots
GET /hotspots/:id
GET /hotspot_check

Access current hotspot data for any location on Earth. Current hotspots are frequently updated based on validation models and data from multiple different satellites and sensors. Data is available in JSON format.

You can retrive individual hotspots as well as list and filter all hotspots from our database.

List Hotspots

GET /hotspots

curl https://api.riscognition.io/hotspots \
-H "Authorization: Bearer YOUR-API-KEY"

headers = {'Authorization': 'Bearer YOUR-API-KEY'}
response = requests.get("https://api.riscognition.io/hotspots", headers = headers)

GET /hotspots - Example with bbox filter

curl "https://api.riscognition.io/hotspots?bbox=1.1865234,50.4505090,4.2407226,51.7508394" \
-H "Authorization: Bearer YOUR-API-KEY"

headers = {'Authorization': 'Bearer YOUR-API-KEY'}
response = requests.get("https://api.riscognition.io/hotspots?bbox=1.1865234,50.4505090,4.2407226,51.7508394", headers = headers)

GET /hotspots - Example with more filters + limit

curl "https://api.riscognition.io/hotspots?country=GB,DE&start=1590451200&limit=5" \
-H "Authorization: Bearer YOUR-API-KEY"

headers = {'Authorization': 'Bearer YOUR-API-KEY'}
response = requests.get("https://api.riscognition.io/hotspots?country=GB,DE&start=1590451200&limit=5", headers = headers)

RESPONSE

{
  "type": "FeatureCollection",
  "feature_count": 10,
  "features": [
    {
      "type": "Feature",
      "properties": {
        "acquired": 1616126040,
        "accuracy": 375,
        "country": "GB",
        "country_name": "United Kingdom",
        "region": "GB-NTL",
        "region_name": "Neath Port Talbot",
        "confidence": "nominal",
        "sensor": "VIIRS",
        "satellite": "Suomi NPP",
        "frp": 0
      },
      "geometry": {
        "type": "Point",
        "coordinates": [
          -3.76407,
          51.57113
        ]
      }
    },
    {...},
    {...}
  ]
}

Retrieve a list of hotspots sorted by date and filtered by corresponding parameters.

Parameters

Parameter Description Mandatory
start filter starting at a certain time (unix timestamp UTC-0) in the past (default: now-24h) no
end filter until a certain time (unix timestamp UTC-0) in the past no
country filter by Two-letter comma separated country codes (ISO 3166-1 ALPHA-2) no
bbox filter by comma separated bounding box (southwestLng, southwestLat, northeastLng, northeastLat) no
limit limit on the number of objects to be returned (default: 25) no

Returns

Returns a GEOJSON FeatureCollection of hotspots.

If no filter parameters are defined the newest hotspots from the database are returned with the default limit of 25.

Check Location

GET /hotspot_check

curl "https://api.riscognition.io/hotspot_check?latitude=35&longitude=139" \
-H "Authorization: Bearer YOUR-API-KEY"

headers = {'Authorization': 'Bearer YOUR-API-KEY'}
response = requests.get("https://api.riscognition.io/hotspot_check?latitude=35&longitude=139", headers = headers)

GET /hotspot_check - Example with radius

curl "https://api.riscognition.io/hotspot_check?latitude=47.192569&longitude=7.558133&radius=600" \
-H "Authorization: Bearer YOUR-API-KEY"

headers = {'Authorization': 'Bearer YOUR-API-KEY'}
response = requests.get("https://api.riscognition.io/hotspot_check?latitude=47.192569&longitude=7.558133&radius=600", headers = headers)

RESPONSE

{
  "affected": true,
  "count": 3,
  "location": "48.245923, 14.701172",
  "message": "3 hotspots were found in the search area"
}

A simple check for hotspots in an area around a given location.

Parameters

Parameter Description Mandatory
latitude latitude for the location of your interest yes
longitude longitude for the location of your interest yes
start check for hotspots starting at a certain time (unix timestamp) in the past no
end check for hotspots until a certain time (unix timestamp) in the past no
radius radius in meter for the area (circle) to be searched in (default: 500m) no

Returns

Returns an object with information for the given location.

🔥 Burned Areas

ENDPOINTS

GET /burned_areas

Access historical burned area data from all over Europe.

List Burned Areas

GET /burned_areas

curl https://api.riscognition.io/burned_areas \
-H "Authorization: Bearer YOUR-API-KEY"

headers = {'Authorization': 'Bearer YOUR-API-KEY'}
response = requests.get("https://api.riscognition.io/burned_areas", headers = headers)

GET /burned_areas - Example with filter + limit

curl "https://api.riscognition.io/burned_areas?country=GB,DE&end=1473493686&limit=5" \
-H "Authorization: Bearer YOUR-API-KEY"

headers = {'Authorization': 'Bearer YOUR-API-KEY'}
response = requests.get("https://api.riscognition.io/burned_areas?country=GB,DE&end=1473493686&limit=5", headers = headers)

RESPONSE

{
  "type":"FeatureCollection",
  "features": [{
    "type":"Feature",
    "properties":{
      "id":1,
      "effi_id":122779,
      "firedate":"2016-06-16T00:00:00Z",
      "year":2016,
      "country_code":"IT",
      "country":"Italy",
      "province":"Agrigento",
      "commune":"Ravanusa",
      "area_ha":66
      },
      "geometry":{...}
    },
    {...}
  ]
}

Retrieve a list of burned areas. The burned areas are returned in sorted order, with the most recent appearing first.

Parameters

Parameter Description Mandatory
start filter starting at a certain time (unix timestamp UTC-0) in the past (default: now-24h) no
end filter until a certain time (unix timestamp UTC-0) in the past no
country filter by Two-letter comma separated country codes (ISO 3166-1 ALPHA-2) no
limit limit on the number of objects to be returned (default: 25) no

Returns

Returns a GEOJSON FeatureCollection of burned areas.

If no filter parameters are defined the newest burned_areas from the database are returned with the default limit of 25.

🚜 Landcover

ENDPOINTS

GET /landcover
GET /landcover/:id

This service gives you access to landcover related data - currently only based on Corine Landcover.

The database includes:

  1. Corine Landcover 2012
  2. Corine Landcover 2018

The data is provided in json/geojson format.

List Landcover

GET /landcover

curl https://api.riscognition.io/landcover \
-H "Authorization: Bearer YOUR-API-KEY"

headers = {'Authorization': 'Bearer YOUR-API-KEY'}
response = requests.get("https://api.riscognition.io/landcover", headers = headers)

GET /landcover - Example with filter 

curl "https://api.riscognition.io/landcover?code=111&year=2018&nuts=MT00" \
-H "Authorization: Bearer YOUR-API-KEY"

headers = {'Authorization': 'Bearer YOUR-API-KEY'}
response = requests.get("https://api.riscognition.io/landcover?code=111&year=2018&nuts=MT00", headers = headers)

RESPONSE

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "geometry": {
        "type": "MultiPolygon",
        "coordinates": [
        ]
      },
      "properties": {
        "fid": 1,
        "clc_code": "111",
        "area_ha": 130.863653769991,
        "clc_id": "EU-1",
        "label": "Continuous urban fabric",
        "rgb": "230,000,077",
        "source": "U2018_CLC2018_V2020_20u1",
        "year": 2018
      }
    },
    {...},
    {...}
}

Retrieve a list of landcover data filtered by corresponding parameters.

Parameters

Parameter Description Mandatory
year filter by the year the data was produced (default: 2018) no
nuts filter by nuts id to receive data for a specific nuts region (e.g. MT00 for Malta) no
code filter by clc code (e.g.: 111) no
limit limit on the number of objects to be returned (default: 5) no

Returns

Returns a GEOJSON FeatureCollection of landcover data.

If no filter parameters are defined the first datasets from the database are returned with the default limit of 5.

Retrieve a Landcover

GET /landcover/:id

curl https://api.riscognition.io/landcover/EU-1 \
-H "Authorization: Bearer YOUR-API-KEY"

headers = {'Authorization': 'Bearer YOUR-API-KEY'}
response = requests.get("https://api.riscognition.io/landcover/EU-1", headers = headers)

RESPONSE

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "geometry": {
        "type": "MultiPolygon",
        "coordinates": [
        ]
      },
      "properties": {
        "fid": 1,
        "clc_code": "111",
        "area_ha": 130.863653769991,
        "clc_id": "EU-1",
        "label": "Continuous urban fabric",
        "rgb": "230,000,077",
        "source": "U2018_CLC2018_V2020_20u1",
        "year": 2018
      }
    },
    {...},
}

Retrieve a landcover polygon by its unique CLC ID.

Parameters

no parameters

Returns

Returns a GEOJSON FeatureCollection with a single feature.

🌰 Nuts

ENDPOINTS

GET /nuts
GET /nuts/:id

This service gives you access to the NUTS 2021 dataset.

The NUTS classification (Nomenclature of territorial units for statistics) is a hierarchical system for dividing up the economic territory of the EU and the UK for the purpose of:

NUTS 2021 classification by the European Union/Eurostat is licensed under CC BY 4.0

The data is provided in json/geojson format.

List NUTS data

GET /nuts

curl https://api.riscognition.io/nuts \
-H "Authorization: Bearer YOUR-API-KEY"

headers = {'Authorization': 'Bearer YOUR-API-KEY'}
response = requests.get("https://api.riscognition.io/nuts", headers = headers)

GET /nuts - Example with filter 

curl "https://api.riscognition.io/nuts?country=DE&level=1&limit=100" \
-H "Authorization: Bearer YOUR-API-KEY"

headers = {'Authorization': 'Bearer YOUR-API-KEY'}
response = requests.get("https://api.riscognition.io/nuts?country=DE&level=1&limit=100", headers = headers)

RESPONSE

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "geometry": {
        "type": "MultiPolygon",
        "coordinates": [
        ]
      },
      "properties": {
        "nuts_id": "DEA",
        "cntr_code": "DE",
        "levl_code": 1,
        "nuts_name": "Nordrhein-Westfalen",
        "name_latn": "Nordrhein-Westfalen",
        "mount_type": 0,
        "urbn_type": null,
        "coast_type": null
      }
    },
    {...},
    {...}
}

Retrieve a list of landcover data filtered by corresponding parameters.

Parameters

Parameter Description Mandatory
country filter by Two-letter comma separated country codes* (ISO 3166-1 ALPHA-2) no
level filter by nuts level (0, 1, 2, 3) no
limit limit on the number of objects to be returned (default: 5) no

Returns

Returns a GEOJSON FeatureCollection of nuts regions.

If no filter parameters are defined the first datasets from the database are returned with the default limit of 5.

Retrieve a single NUTS region

GET /nuts/:id

curl https://api.riscognition.io/nuts/FR107 \
-H "Authorization: Bearer YOUR-API-KEY"

headers = {'Authorization': 'Bearer YOUR-API-KEY'}
response = requests.get("https://api.riscognition.io/nuts/FR107", headers = headers)

RESPONSE

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "geometry": {
        "type": "MultiPolygon",
        "coordinates": [
        ]
      },
      "properties": {
        "ogc_fid": 1423,
        "nuts_id": "FR107",
        "levl_code": 3,
        "cntr_code": "FR",
        "name_latn": "Val-de-Marne",
        "nuts_name": "Val-de-Marne",
        "mount_type": 4,
        "urbn_type": 1,
        "coast_type": 3,
        "fid": "FR107"
      }
    }
  ]
}

Retrieve a NUTS region by its unique NUTS ID.

Parameters

no parameters

Returns

Returns a GEOJSON FeatureCollection with a single feature.

🌍 Area of Interest (AOI)

ENDPOINTS

GET     /aois
GET     /aois/:id
POST    /aois
DELETE  /aois/:id

This Service is an initial API to set up your Areas of Interest (AOIs). We store your AOIs in our system, and use the geometry to calculate an ID. The ID of a polygon can (soon) be used to configure the monitoring capabilities for other APIs (hotspots, etc.).

Create an AOI

POST /aois

curl https://api.riscognition.io/aois \
-H "Authorization: Bearer YOUR-API-KEY" \
-H "Content-Type: application/json" \
-X POST \
-d '[{"lat":39.6848587990413,"lng":-3.6344947175489},...]' 

aoi = {
      "type": "Feature",
      "properties": {},
      "geometry": {
        "type": "Polygon",
        "coordinates": [
          [
            [
              8.563156127929688,
              46.120131387408954
            ],
            [
              ...
            ]
          ]
        ]
      }
    }

headers = {'Authorization': 'Bearer YOUR-API-KEY'}
response = requests.post("https://api.riscognition.io/aois", json = aoi, headers = headers)

RESPONSE

{
  "id": "c682239"
}

Create an AOI by sending us your geometry.

The geometry can be sent in two different formats:

  1. Array of JSON Objects [{"lat":39.6848587990413,"lng":-3.6344947175489},...]
  2. Geojson Feature

Returns

Returns the id of your AOI in json.

Retrive a single AOI

GET /aois/:id

curl https://api.riscognition.io/aois/562dsa25 \
-H "Authorization: Bearer YOUR-API-KEY"

headers = {'Authorization': 'Bearer YOUR-API-KEY'}
response = requests.get("https://api.riscognition.io/aois/YOUR-AOI-ID", headers = headers)

RESPONSE 

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "geometry": {
        "type": "Polygon",
        "coordinates": [
        ]
      },
      "properties": {
        "id": "c682239",
        "name": "Pistachio Farm",
        "created": "2021-04-21T09:52:52.493995+02:00",
        "area": 1.2713812e+06
      }
    }
  ]
}

Parameters

no parameters

Returns

Returns a single AOI in geojson.

List AOIs

Retrieve all of your AOIs stored in our database.

GET /aois

curl https://api.riscognition.io/aois \
-H "Authorization: Bearer YOUR-API-KEY" 

headers = {'Authorization': 'Bearer YOUR-API-KEY'}
response = requests.get("https://api.riscognition.io/aois", headers = headers)

RESPONSE 

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "geometry": {
        "type": "Polygon",
        "coordinates": [
        ]
      },
      "properties": {
        "id": "c682239",
        "name": "Pistachio Farm",
        "created": "2021-04-21T09:52:52.493995+02:00",
        "area": 1.2713812e+06
      }
    },
    {...},
  ]
}

Parameters

no parameters

Returns

Returns a list of your AOIs in geojson.

Delete an AOI

DELETE /aois/:id

curl https://api.riscognition.io/aois/562dsa25 \
-H "Authorization: Bearer YOUR-API-KEY" \
-X DELETE 

headers = {'Authorization': 'Bearer YOUR-API-KEY'}
response = requests.delete("https://api.riscognition.io/aois/YOUR-AOI-ID", headers = headers)

RESPONSE

OK

Delete an AOI from our Database. Deleting an AOI is an irreversible action.

Parameters

no parameters

🌿 NDVI

ENDPOINTS

GET     /ndvi

With this service you can query NDVI values for an existing AOI. The NDVI data will be updated as soon as new satellite images are available for the area.

List NDVI

GET /ndvi

curl https://api.riscognition.io/ndvi \
-H "Authorization: Bearer YOUR-API-KEY" \
-H "Content-Type: application/json" \

headers = {'Authorization': 'Bearer YOUR-API-KEY'}
response = requests.get("https://api.riscognition.io/ndvi", headers = headers)

GET /ndvi

curl https://api.riscognition.io/ndvi?aoi_id=d40eed3 \
-H "Authorization: Bearer YOUR-API-KEY" \
-H "Content-Type: application/json" \

headers = {'Authorization': 'Bearer YOUR-API-KEY'}
response = requests.get("https://api.riscognition.io/ndvi?aoi_id=d40eed3", headers = headers)

RESPONSE

{
  "indices": [
    {
      "id": "5b5c3d3a-1811-4daa-ad12-9887cc6a3e22",
      "aoi_id": "d40eed3",
      "index": "ndvi",
      "mean": 0.32,
      "max": 0.89,
      "min": 0.060,
      "std": 0.16,
      "acquired": "2021-01-03T11:10:05+00:00"
    },
    {...},
}

Retrieve a list of ndvi values sorted by date acquired.

Parameters

Parameter Description Mandatory
aoi_id retrive NDVI values for a specific AOI no

Returns

Returns a JSON Array of ndvi values.

If the aoi filter parameter is not used the api returns NDVI values for all your AOIs sorted by acquired date.

Errors

The Riscognition API uses HTTP response/error codes to indicate the success or failure of an API request.

In general:
Codes in the 2xx range indicate success. Codes in the 4xx range indicate an error that failed given the
information provided. Codes in the 5xx range indicate an error with our servers.

Error Code Description
200 OK Everything worked as expected.
400 Bad Request The request was unacceptable, often due to missing a required parameter.
401 Unauthorized No valid API key provided.
402 Request Failed The parameters were valid but the request failed.
403 Forbidden The API key doesn't have permissions to perform the request.
404 Not Found The requested resource doesn't exist.
500, 502, 503, 504 Server Errors -Something went wrong on our servers.
cURL Python