API
The front end of MICAT communicates with a corresponding back end API to retrieve information about indicators and perform calculations. The base URL of the API is:
Available API endpoints are documented below. Results are returned as JSON.
Please note that
a) most of the endpoints can be used as URL in the address bar of a browser (GET request).
b) some of the endpoints require to pass additional information in terms of a payload / request body (POST request).
The recommenced way to retrieve and display information is to use our front end: https:/app.micatool.eu. Alternative approaches would be to write custom JavaScript code or use some advanced REST client tool.
ID tables
Following API endpoints provide information about ID tables:
https://api.micatool.eu/id_mode
https://api.micatool.eu/id_region
https://api.micatool.eu/id_subsector
https://api.micatool.eu/id_action_type
https://api.micatool.eu/id_final_energy_carrier
https://api.micatool.eu/id_indicator
Also see related section [indices/indices_description].
The JSON result includes the properties headers and rows. The individual headers of the ID tables are:
id: Unique numeric ID, used to identify the “row/entity”. Also used as parameter in some API requests.
label: A short text that serves as a name. Might be used as a display label in graphical user interfaces, e.g. for combo boxes.
description: Potentially longer text, including more details. Might be used as tooltip text in graphical user interfaces to provide additional context.
Example JSON result for the id_final_energy_carrier endpoint:
{
"headers": ["id", "label", "description"],
"rows": [
[1, "Electricity", "Electricity"],
[2, "Oil", "Oil"],
[3, "Coal", "Coal"],
[4, "Gas", "Gas"],
[5, "Biomass and Waste", "Biomass and Waste"],
[6, "Heat", "District heating and CHP"],
[7, "H2 and e-fuels", "H2 and synthetic fuels"]
]
}
Mapping tables
Following API endpoints provide information about mapping tables, describing relations between ID tables:
https://api.micatool.eu/mapping__subsector__action_type
The JSON result includes the properties headers and rows. In addition to the column “id”, there is a source column (left) and a target column (right).
In a mapping table, several source values might be mapped to several target values. Therefore, mapping tables allow to model multiple types of relation: many to many, many to one, one to many, one to one). The values of the source column might not be unique. The values of the column ‘id’ are unique.
The mapping table mapping__subsector__action_type describes what id_action_type values exist for a distinct value of id_subsector. For example, id_subsector 1 provides the id_action_type values 8, 10, 11, 12.
Indicator calculations
The API endpoint for indicator calculations is
https://api.micatool.eu/indicator_data
Please note that indicator results cannot be requested individually. There is only this single end point and data for all calculated indicators is returned as a JSON dictionary.
This endpoint requires following input parameters:
id_mode, as query parameter in the url, also see https://api.micatool.eu/id_mode
id_region, as query parameter in the url, also see https://api.micatool.eu/id_region
information about measures and optional parameters as JSON payload
Full example URL for POST request:
https://api.micatool.eu/indicator_data?id_mode=1&id_region=1
For some example payload and JavaScript code see
https://app.micatool.eu/demo_index.html
Open the developer tools of your browser (for example F12) and have a look at the source code. It demonstrates an example JSON payload, including user input about energy efficiency measures.
The API does not convert units. Energy related values need to be specified in the unit ktoe. If your user input is specified in different units or you want to visualize results in different units, you need to implement corresponding unit conversions.
Fractions need to specified (and are returned) as decimal numbers, e.g. 0.1 instead of 10 %. Therefore, you might need a conversion factor of 100 in some use cases.
Parameter default values
a) The API endpoint for generating global default parameter values is:
https://api.micatool.eu/json_parameters
This endpoint requires following input parameters:
id_mode, as query parameter in the url, also see https://api.micatool.eu/id_mode
id_region, as query parameter in the url, also see https://api.micatool.eu/id_region
Full example url:
https://api.micatool.eu/json_parameters?id_mode=1&id_region=0
b) The API endpoint for generating measure specific default parameter values is:
https://api.micatool.eu/json_measure
This enpoint requires following input parameters:
id_mode, as query parameter in the url, also see https://api.micatool.eu/id_mode
id_region, as query parameter in the url, also see https://api.micatool.eu/id_region
information about a measure as JSON payload
Full example URL for POST request:
https://api.micatool.eu/json_measure?id_mode=1&id_region=0
Example payload for POST request:
{
"2000": 0,
"2010": 0,
"2015": 0,
"2020": 10,
"2025": 20,
"2030": 30,
"id": 1,
"row_number": 1,
"active": true,
"subsector": {
"id": 1,
"label": "Average agriculture",
"_description": "Agriculture, forestry & fishing"
},
"action_type": {
"id": 8,
"label": "Cross-cutting technologies",
"_description": "Energy-efficient electric cross-cutting technologies"
},
"details": {},
"unit": {
"name": "kilotonne of oil equivalent",
"symbol": "ktoe",
"factor": 1
}
};
Descriptions
The API endpoints descriptions and single_description provide descriptions, for example for charts. A single description can be identified by a corresponding, unique key.