Kontali API

API Reference

The Kontali API is structured around REST. The API has resource-oriented URLs, returns JSON responses, and uses standard HTTP response codes.

The Swagger documentation is available at https://api.kontali.com/swagger

The OpenAPI definition is available at https://api.kontali.com/openapi.json

Authentication

To authenticate requests made for resources, the API utilizes a JWT (JSON Web Token). Each request needs to include a JWT as an Authorization header, with the format "Authorization: Bearer xxx". The JWT is a signed token that contains information pertaining to your subscription and the resources you are authorized to access. For additional details on JWT, you can refer to JWT.io.

An access token can be requested from the /oauth/token endpoint in the API using your application's Client ID and Client Secret. All requests must be made over HTTPS.

Errors

The Kontali API uses standard HTTP response codes, which indicate the success or failure of the request. A response code of 200 indicates that the request was successful. Response codes in the range 4xx generally indicate that the information provided was either insufficient or inaccurate. Response codes in the range 5xx indicate that an error has occurred in our server. For more information on this, you can refer to Mozilla documentation.

The Kontali API uses the following status codes:

Code	Detail
200 - OK	The request was successful
400 - Bad Request	The request contained invalid values, e.g. dates
401 - Unauthorized	The credentials could not be authenticated, e.g. expired, invalid
403 - Forbidden	The credentials do not provide sufficient permissions
404 - Not Found	The requested resource does not exist
429 - Too Many Requests	The rate-limit has been exceeded
5xx - Server Errors	An error occurred on our side

Rate Limiting

Rate-limiting is enforced on all endpoints of the API. During the early access phase, there is a rate limit of 120 requests per minute that applies to all endpoints. If the rate limit is exceeded, a status code of 429 will be returned. Subsequent requests will be declined until the time limit is reset.

It is encouraged to make use of this status code in applications to prevent wasted requests.

Quickstart

Requesting a token

To use the API, you'll first need to obtain an access token to authenticate your requests and access your resources. An example of requesting a token is as follows:

PythoncURL

import requests

body = {
  "client_id": "<your 32-character id>",
  "client_secret": "<your 64-character secret>",
}
response = requests.post(url="https://api.kontali.com/api/v1/oauth/token", json=body)

print(response.json())

curl -X 'POST' \
  'https://api.kontali.com/api/v1/oauth/token' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
      "client_id": "<your 32-character id>",
      "client_secret": "<your 64-character secret>"
    }'

Token requesting

If you receive a 401 response code it is likely that the credentials you provided are incorrect

The response looks as follows:

Response

{
  "access_token": "12345",
  "expires_in": 86400,
  "token_type": "Bearer"
}

Requesting a resource

To request a resource you will now need to send an authenticated request to the server using the token received in the previous section. For example, if you wish to request datapoints for Norwegian Monthly Salmon harvest volumes (WFE) in tonnes, you can make the following request:

PythoncURL

import requests

header = {"Authorization": "Bearer 12345"}

params = {
    "curve_name": "SAL HA NO SEA vol t WFE monthly hest Kontali",
    "start_date": "2024-01-01",
    "end_date": "2024-01-01",
}

response = requests.get(
    url="https://api.kontali.com/api/v1/curves/timeseries",
    headers=header,
    params=params
)

print(response.json())

curl -X 'GET' \
  'https://api.kontali.com/api/v1/curves/timeseries?start_date=2024-01-01&end_date=2024-01-01&curve_name=SAL%20HA%20NO%20SEA%20vol%20t%20WFE%20monthly%20hest%20Kontali' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer 12345'

This will return a response in the following format:

Response

{
  "name": "SAL HA NO SEA vol t WFE monthly hest Kontali",
  "deprecated": false,
  "end_of_life": null,
  "timeseries": [
    {
      "timestamp": "2024-01-01T00:00:00+00:00",
      "value": 100000,
      "updated_at": "2025-02-28T12:29:39.337668+00:00"
    }
  ],
  "timeseries_type": "forecast"
}

In this example, SAL HA NO SEA vol t WFE monthly hest Kontali is the name of the "curve" being requested - the curve is the taxonomic construction corresponding to Norwegian Monthly Salmon harvest volumes (WFE) in tonnes. Details on how these taxonomic constructions are formed will be detailed in later sections.

Deprecated curves

In the /curves/timeseries response, the deprecated field indicates whether the curve is deprecated, and the end_of_life field provides the ISO-formatted (YYYY-MM-DD) removal date.

To see the details on the taxonomy relating to SAL HA NO SEA vol t WFE monthly hest Kontali use the /api/v1/taxonomy endpoint. For example, the following request:

PythoncURL

import requests

header = {"Authorization": "Bearer 12345"}

params = {
    "curve_name": "SAL HA NO SEA vol t WFE monthly hest Kontali",
}

response = requests.get(
    url="https://api.kontali.com/api/v1/taxonomy",
    headers=header,
    params=params
)

print(response.json())

curl -X 'GET' \
  'https://api.kontali.com/api/v1/taxonomy?curve_name=SAL%20HA%20NO%20SEA%20vol%20t%20WFE%20monthly%20hest%20Kontali' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer 12345'

This will return a response in the following format:

Response

[
  {
    "category": "Source",
    "dimension": "Kontali",
    "dimension_abbr": "Kontali"
  },
  {
    "category": "Value chain",
    "dimension": "Harvest",
    "dimension_abbr": "HA"
  },
  {
    "category": "Unit",
    "dimension": "Tonnes",
    "dimension_abbr": "t"
  },
  {
    "category": "Data type",
    "dimension": "Historic estimate",
    "dimension_abbr": "hest"
  },
  {
    "category": "Unit Function",
    "dimension": "Whole Fish Equivalent",
    "dimension_abbr": "WFE"
  },
  {
    "category": "Resolution",
    "dimension": "Monthly",
    "dimension_abbr": "monthly"
  },
  {
    "category": "Measurement",
    "dimension": "Volume",
    "dimension_abbr": "vol"
  },
  {
    "category": "Location",
    "dimension": "Norway",
    "dimension_abbr": "NO"
  },
  {
    "category": "Species",
    "dimension": "Atlantic salmon",
    "dimension_abbr": "SAL"
  },
  {
    "category": "Environment",
    "dimension": "Sea Environment",
    "dimension_abbr": "SEA"
  }
]

To see the all the curves available from your subscription, the endpoint to use is /api/v1/curves. This endpoint allows for optional filtering by taxonomy, which can allow you to find the specific curves you need. As an example, after consulting the taxonomy if it is determined that you need all curves relating to Atlantic salmon exports from Norway to Japan, this can be constructed as follows:

Abbreviation	Dimension	Category
SAL	Atlantic Salmon	Species
Exp	Export	Value Chain
NO	Norway	Origin
JP	Japan	Destination

These Dimensions can then be supplied to the /api/v1/curves endpoint as query parameter to filter.

PythoncURL

import requests

header = {"Authorization": "Bearer 12345"}

params = {
    "species": "SAL",
    "value_chain": "EXP",
    "origin": "NO",
    "destination": "JP",
}

response = requests.get(
    url="https://api.kontali.com/api/v1/curves",
    headers=header,
    params=params
)
print(response.json())

curl -X 'GET' \
  'https://api.kontali.com/api/v1/curves?species=SAL&value_chain=EXP&origin=NO&destination=JP' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer 12345'

This will return a response in the following format:

Response

{
  "curve_names": [
    "SAL EXP NO JP FIL FRE vol t monthly Act SSB",
    "SAL EXP NO JP WHL FRO vol t monthly Act SSB"
  ]
}

Curves

In its simplest form, a curve is a set of time-series data.

More broadly, a curve is a uniquely named object that has the following properties:

Curve name
Time-series data
Categories and Dimensions

Combined it gives a full description of the data it represents and the properties of that data.

Example

The curve SAL HA NO SEA vol t WFE monthly sum Est Kontali, is the monthly harvest volumes of Atlantic salmon in Norway represented in tonnes WFE.

Curve Name

The curve name is a unique property created for every curve, which is used to reference that curve.

The name is a series of abbreviations, separated by whitespace, for each category:dimension attached to that curve.

Getting updates

Additionally, the curves endpoint allows for filtering of curves based on the date they were last updated, using the updated_since query parameter. As an example, using an updated version of the above query:

PythoncURL

import requests

header = {"Authorization": "Bearer 12345"}

params = {
    "species": "SAL",
    "value_chain": "EXP",
    "origin": "NO",
    "destination": "JP",
    "updated_since": "2023-06-01"
}

response = requests.get(
    url="https://api.kontali.com/api/v1/curves",
    headers=header,
    params=params
)

curl -X 'GET' \
  'https://api.kontali.com/api/v1/curves?species=SAL&value_chain=EXP&origin=NO&destination=JP&updated_since=2023-06-01' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer 12345'

This will return a reduced list of curve names consisting only of curves which have been updated since 2023-06-01. This parameter also supports datetimes, in the ISO8601 format, for example 2023-09-01T06:57:53+00:00.

Datetime Formats

The parameter is flexible and can handle various derivatives of the above format, for example any of the following are also acceptable: 2023-09-01T06:57:53, 2023-09-01 06:57:53. For consitency it is encouraged to use the 2023-09-01T06:57:53+00:00 format which is returned from the /api/v1/curves/timeseries endpoint.

Categories and dimensions

The categories are a set of meta-data values that can be attached to a curve. For each category assigned to a curve, the dimension within that category needs to be specified. Which categories used can vary depending on the time-series, but the overall order is fixed.

Categories have the following properties:

Name
Description

Dimensions have the following properties:

Category
Name
Description
Abbreviation

Taxonomy

Taxonomy is the classification and naming system used on curves in Kontali. Each curve will have a name comprised of a series of abbreviations, where each abbreviation is linked to a value (dimension) within that category.

Which categories used can vary depending on the curves, but the overall order is fixed. The general rule-set is specified in this document.

There are some common rules which the taxonomy must abide to:

Every curve-name is unique
Every category is separated by a blank space in the curve name
Within each category, the abbreviations for a dimension is unique. Permitted characters for abbreviations are:
[A-Z]
[a-z]
[0-9]
Hyphen [ - ]
Underscore [ _ ]

To retrieve the full available taxonomy for your subscription, use the https://api.kontali.com/api/v1/taxonomy endpoint.

Example

Curve name: SAL Exp NO WHL FRE vol kg WFE month Act SSB

Abbreviation	Dimension	Category
SAL	Atlantic Salmon	Species
Exp	Export	Value Chain
NO	Norway	Origin
WHL	Whole	Presentation
FRE	Fresh and Chilled	Preservation
vol	Volume	Measurement
kg	Kilograms	Unit
WFE	Whole Fish Equivalent	Unit Function
month	Monthly	Resolution
Act	Actual	Data Type
SSB	Norwegian Statistics Bureau	Source

Category Order

The order of the categories used in the construction of the curve name is important. While some categories are conditional, there are general rules which will always apply. As an example (if present), species will always be first. The full order (descending priority) is below:

Category	Description
Species	FAO species list with Kontali amendments. Describes the aquatic species when relevant. Also includes families and subfamilies.
Value Chain	For which value chain and where within that chain the curve contains data. Also includes segments on macro values.
Location	Location indicates the geographical origin or point-of-reference for a curve. Generally it follows the ISO 3166-1 alpha-2 convention for countries and ISO 3166-2 for subdivisions on counties, provinces or states.
Origin	Origin of transport or transferable goods. Follows the same dimensional space as Location. Origin is also used for conversion factors, with the respective units’ dimensions.
Destination	Destination of transport or transferable goods. Follows the same dimensional space as Location. Destination is also used for conversion factors, with the respective units’ dimensions - e.g. the base currency for currency conversion rates.
Environment	The environment category specifies the type of natural environment for the observed data. An example is the environment for aquaculture, being at sea or on land.
Financial Product	Contains non-physical products such as benchmarks, derivatives, and indicators.
Product	HS2-8 product definition
Product Origin	The type of production origin a commodity comes from
From Company
Presentation	The presented state of a product. Can be a converted value between different presentations.
Preservation	The preservation state for a product.
Preparation	The preparation method of a good or product.
Generation	The generation of the aquatic species. For example one year’s generation of Atlantic Salmon. Can also be applied to shrimp and other bred species.
Release
Measurement	Description of what is measured in the time-series included in the curve.
Size	Fish size
Unit	The unit for the measurement in the time-series.
Unit Function	Any function applied on the unit.
Resolution	The resolution of the time series. This can be either temporal (time) or spatial (geographical) resolution.
Data Function	Any function of aggregation applied on the data in the time series.
Data Type	The type of data in the time-series, e.g. measurements, estimates, or predictions.
Source	The closest source for the data. If data comes from a model, the model is referenced and not the data source used to build the model. Data source hierarchy can be added in the meta data.