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

You must replace YOUR-API-KEY with your personal 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:

Corine Landcover 2012
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:

The collection, development and harmonisation of European regional statistics
Socio-economic analyses of the regions
1. NUTS 1: major socio-economic regions
2. NUTS 2: basic regions for the application of regional policies
3. NUTS 3: small regions for specific diagnoses
Framing of EU regional policies
1. Regions eligible for support from cohesion policy have been defined at NUTS 2 level
2. The Cohesion report has so far mainly been prepared at NUTS 2 level

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:

Array of JSON Objects [{"lat":39.6848587990413,"lng":-3.6344947175489},...]
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.