Feed – a stream of Event Snapshots. Has a number of Snapshots, and a way to query
new ones.
Observation – an atomic chunk of data coming from external providers. Should be
linked to an Event.
Event – a collection of pointers to data about a certain disaster or related chains of
disasters. Visible as Event Snapshots in the Feed.
Event Snapshot – a view on the Event that combines all the Observations. Snapshots
are saved verbatim, copying all the information, so that a change in the future will not
alter the information presented in them.
Episode – a snapshot of the state of the Event in time. Exists in the context of Event
Snapshot. Is combined from one or multiple observations.
Version – is a sequential number of Event Snapshot. The version is assigned for the
Event within the Feed.

Each Event Snapshot has the following parameters:
● event identifier
● event version
● event name
● event description
● date and time when the event has started
● date and time when the event has finished
● date and time when the event was updated in the feed
● links to external resources for this event
● list of Observations
● list of Episodes
● event geometry (in GeoJSON format), this is the combined geometry of all

Episodes
● proper name of the event (if exists)
● event location (country list or hierarchical structure)
● event details (additional event data, calculated based on Event geometry, if any)
● feed, for which the snapshot is generated.

An Event Snapshot has at least one Episode, each has the following parameters:
● episode name
● episode description
● episode type (FLOOD, TSUNAMI, WILDFIRE, TORNADO, WINTER_STORM,
EARTHQUAKE, STORM, CYCLONE, DROUGHT, VOLCANO, OTHER)
● episode activity mark
● episode severity (EXTREME, SEVERE, MODERATE, MINOR, TERMINATION,
UNKNOWN)
● date and time when the episode has started
● date and time when the episode has finished
● date and time when the episode was updated in the feed
● date and time when the episode was updated into data source
● links to external resources for this episode
● list of Observations
● episode geometry (in GeoJSON format)
● proper name of the event (if exists)
● episode location (country list or hierarchical structure)
● episode details (additional episode data, calculated based on Episode geometry,
if any).

The new Version is formed when additional observations appear on the Event.
All Versions are stored and can be requested separately.
This is the Event versioning scheme:

Kontur Event Feed is accessed through RESTful API with information about disaster
events worldwide.
RESTful API lets you interact directly with Kontur Event Feed sending HTTPS requests
to specific URLs (endpoints).
To be able to use it be sure that you fit these requirements:
● basic knowledge of RESTful API;
● familiarity with JSON data format;
● basic knowledge of command-line interface.

All requests performed to the API must be authenticated with the token. For
authorization, we use Bearer token.
To obtain it you can send this cURL command using command-line interface:

curl --data-urlencode "client_id=kontur_platform" --data-urlencode "username=[EMAIL]"
--data-urlencode "password=[PASSWORD]" --data-urlencode "grant_type=password" -H
"Content-Type: application/x-www-form-urlencoded" -X POST
https://keycloak01.kontur.io/auth/realms/kontur/protocol/openid-connect/token

where [EMAIL] and [PASSWORD] are your account email and password.
If your password contains special characters, you may have problems getting the token
via cURL.
In this case, you should use a special application to request the token, such as Postman.
You can also use any other application that supports API requests.
If you have any difficulties with access, you can contact us at the contacts listed in the
“Support” section at the bottom of the page.

There are endpoints that you can use:
● https://apps.kontur.io/events/v1 – search for events by type, location, date,
severity, etc.;
● https://apps.kontur.io/events/v1/event/ – search for an exact event (if you have
an event identifier). It returns event by its version, identifier and feed alias;
● https://apps.kontur.io/events/v1/observations/{observationId} – search for an
exact observation (if you have an observation identifier).

Link to Swagger with all available endpoints and their description:
https://apps.kontur.io/events/.
Feed name that you should use for requests: kontur-public.

The instructions below describe the process of interacting with Kontur Event Feed
through Swagger.

• To Log in input your access token to Authorize pop-up.
  After that, you can create your first request.

• Let’s try the most common-used endpoint (https://apps.kontur.io/events/v1):
  request a list of events based on some parameters (as an event type, location, date,
  severity, etc.).

• You must fill the feed name as kontur-public and add some additional filters
  (optional).
• Press the Execute button to see the response.

Response format

Most of the responses from the server are in JSON format, but there may be data in
XML, CSV, or another format for raw data. If the request is successfully completed, the
required set of keys and values is returned, intended for a specific response to the
request.
Date and time format: unless otherwise specified, dates and times are represented in
ISO 8601 standard.
Coordinate format: The coordinate reference system of the values is WGS84
longitude/latitude.

Errors

If the operation fails, a JSON Error node is returned containing:
● Status – error code of the operation;
● Message – error message;
● Errors – list of errors.

● 400 Bad Request
● 401 Unauthorized
● 204 No Content
● 500 Internal Server Error

In case you have any questions you can contact us via hello@kontur.io or use intercom
chat on our website kontur.io.