Climkit API

The Climkit Developer API allows registered and authorized developers to obtain metering and energy data from authorized Climkit sites.

To register, developers must obtain data access rights from the installation owner and Climkit SA.

Requests for API access should be directed to service@climkit.io .

The API access information is different from the Climkit portal personal account login information.

Access information can only be used by the registered developer. Colleagues and collaborators must apply individually to obtain their own access rights.

API Endpoint: https://api.climkit.io/api/v1

1. Authentication

Climkit's API uses JSON Web Tokens ( https://jwt.io/introduction/ ) to secure the transit of information.

Once the user logs in with their credentials (username and password), they receive a token valid for 15 minutes that allows them to access authorized resources.

URL : /auth

Method : POST

Auth required : NO

 Authentication through username-password to get an access token

 Parameters (POST)
 ----------
 username: str
 The API username
 password: str
 The API password

 Returns
 -------
 {
 'access_token': <str: your-access-token>,
 'valid_until': {'$date': <int: epoch-time-in-milliseconds>},
 }

2. Sites

All sites

The list of all sites.

URL : /all_installations

Method : GET

Auth required : YES with a valid Token

Requests limit : 1/second

 Parameters (GET)
 ----------
 No parameter

 Headers
 ----------
 Content-Type: 'application/json'
 Authorization: 'Bearer {your-access-token}'

 Returns
 -------
 The list of all the sites, presented as a list of objects.

Information about a site

The settings of a specific site.

URL : /installation_infos/<site_id>

Method : GET

Auth required : YES with a valid Token

Requests limit : 1/second

 Parameters (GET)
 ----------
 site_id: str
 The object ID of the installation site

 Headers
 ----------
 Content-Type: 'application/json'
 Authorization: 'Bearer {your-access-token}'

 Returns
 -------
 The parameters of the site:

 {
 'site_ref': <str>,
 'name': <str>,
 'address': {
 'street_name': <str>,
 'street_number': <str>,
 'city': <str>,
 'postal_code': <int>
 },
 'creation_date': <datetime isoformat str>,
 'latitude': <float>,
 'longitude': <float>,
 'timezone': <str>,
 }

3. Meters

All meters of a site

The list of all meters on a site.

URL : /meter_info/<site_id>

Method : GET

Auth required : YES with a valid Token

Requests limit : 1/second

 Parameters (GET)
 ----------
 site_id: str
 The object ID of the site

 Headers
 ----------
 Content-Type: 'application/json'
 Authorization: 'Bearer {your-access-token}'

 Returns
 ----------
 The list of meters presented as a list of objects:

 [
 {
 'id': <str representing the meter's id>
 'type': {'electricity', 'heating', 'cold_water', 'hot_water'},
 'name': <str>,
 'mode': {'consumption', 'production', 'introduction', 'battery'},
 'prim_ad': <int>,
 'is_rule_meter': <boolean>
 },
 ...
 ]

Validated site data for a counting type

Validated time series data from the site for a specific metering type, for example total electricity consumption or photovoltaic production of the site.

URL : /site_data/<site_id>/<meter_type>

Method : POST

Auth required : YES with a valid Token

Requests limit : 1/second

 Parameters (GET)
 ----------
 site_id: str
 The object ID of the site
 meter_type: str
 The type of meter data:
 'electricity', 'heating', 'cooling', 'cold_water', 'hot_water' or 'charge_point'

 Parameters (POST)
 ----------
 t_s: str, optional
 The isoformatted datetime, representing the start instant of timeseries, tz-naive in UTC
 t_e: str, optional
 The isoformatted datetime, representing the stop instant of timeseries, tz-naive in UTC
 *sampling_frequency: {'15T', 'H', 'D', 'M', 'Y'}, optional
 The sampling frequency of the returned data list

 Headers
 ----------
 Content-Type: 'application/json'
 Authorization: 'Bearer {your-access-token}'

 Returns
 -------
 The validated time series data from the site for a specific type of metering, presented as a list of objects:

 [
 {
 'conso_total': <total site consumption>,
 'prod_total': <total site electricity (PV) production if type is electricity>,
 'from_ext': <total site consumption from the grid if type is electricity>,
 'self': <total site consumption from solar PV if type is electricity>,
 'to_ext': <total site electricity exported to the grid if type is electricity>,
 'timestamp': <timestamp at the end of the measured period if sampling_frequency is 15T, otherwise start of the period>
 },
 ...
 ]

Validated data from a specific meter

The validated time series data of a meter for the selected period.

URL : /meter_data/<site_id>/<meter_id>

Method : POST

Auth required : YES with a valid Token

Requests limit : 1/second

 Parameters (GET)
 ----------
 site_id: str
 The ID of the site
 meter_id: str
 The ID of the meter

 Parameters (POST)
 ----------
 t_s: str, optional
 The isoformatted datetime, representing the start instant of timeseries, tz-naive in UTC
 t_e: str, optional
 The isoformatted datetime, representing the stop instant of timeseries, tz-naive in UTC
 sampling_frequency: {'15T', 'H', 'D', 'M', 'Y'}, optional
 The sampling frequency of the returned data list

 Headers
 ----------
 Content-Type: 'application/json'
 Authorization: 'Bearer {your-access-token}'

 Returns
 -------
 The validated time series meter data for the selected period, presented as a list of objects:

 [
 {
 'total': <total consumption. If type is electricity, total = self + ext>,
 'self': <total consumption from solar PV if type is electricity>,
 'ext': <total consumption from grid if type is electricity>,
 'timestamp': <timestamp at the end of the measured period if sampling_frequency is 15T, otherwise start of the period>
 },
 ...
 ]

Raw data from a specific meter

Raw data, incremental (meter index) or differential (interval of a charge curve), in time series of a meter for the selected period, directly from the meter without validation. Available only for physical meters and not rule meters.

URL : /meter_data_raw/<site_id>/<meter_id>

Method : POST

Auth required : YES with a valid Token

Requests limit : 1/second

 Parameters (GET)
 ----------
 site_id: str
 The ID of the site
 meter_id: str
 The ID of the meter

 Parameters (POST)
 ----------
 t_s: str, optional
 The isoformatted datetime, representing the start instant of timeseries, tz-naive in UTC
 t_e: str, optional
 The isoformatted datetime, representing the stop instant of timeseries, tz-naive in UTC

 Headers
 ----------
 Content-Type: 'application/json'
 Authorization: 'Bearer {your-access-token}'

 Returns
 -------
 The raw time series meter data for the selected period, presented as a list of objects:

 [
 {
 'en_im': <electricity imported meter index if type is electricity>,
 'en_ex': <electricity exported meter index if type is electricity>,
 'heat_energy_kwh': <thermal energy index if type is heating or cooling>,
 'vol_m3': <water volume index if type is cold_water or hot_water>,
 'timestamp': <timestamp at the end of the measured period>
 },
 ...
 ]

4. Sensors

Get all sensors of a site

URL : /<site_id>/sensors_list

Method : GET

Auth required : YES with a valid Token

 Parameters (URL)
 ----------
 site_id: str
 The ID of the installation site

 Headers
 ----------
 Content-Type: 'application/json'
 Authorization: 'Bearer {your-access-token}'

 Returns
 -------
 array_like

 The list of sensors info formatted as follow:

 [
 {
 'id': <str representing an ObjectID>
 'name': <str>,
 'type': <str describing the type of measured quantity>,
 'unit': <str describing the unit of the measured quantity>,
 'model': <str describing the model of the sensor>
 },
 ...
 ]

Get time series data for a specific sensor

Retrieves time series from a sensor, for a given period. If no period is provided, the latest data is returned. t_s is limited based on user/site.

URL : /<site_id>/sensor_data/<sensor_id>

Method : GET

Auth required : YES with a valid Token

Requests limit : 1/second

 Parameters (URL)
 ----------
 site_id: str
 The ID of the installation site
 sensor_id: str
 The ID of the sensor object

 Parameters (GET)
 ----------
 t_s: str, optional
 The isoformatted datetime, representing the start instant of the requested timeseries, tz-naive in UTC
 t_e: str, optional
 The isoformatted datetime, representing the end instant of the requested timeseries, tz-naive in UTC

 Headers
 ----------
 Content-Type: 'application/json'
 Authorization: 'Bearer {your-access-token}'

 Returns
 -------
 array_like

 The timeseries sensor data of the selected period as a list of objects:

 [
 {
 'timestamp': <int timestamp>,
 'value': <float, int>
 },
 ...
 ]