Table of Contents
Climkit API
Updated
by Nicolas Vodoz
The Climkit Developer API allows registered and authorized developers to retrieve metering and energy data from authorized Climkit sites.
To register, developers must obtain data access rights from the facility owner and Climkit SA.
API access requests should be sent to service@climkit.io.
API access credentials are different from the personal account login credentials for the Climkit portal.
Access credentials may only be used by the registered developer. Colleagues and collaborators must submit an individual request to obtain their own access rights.
API Endpoint: https://api.climkit.io/api/v1
1. Authentication
The Climkit API uses JSON Web Tokens (https://jwt.io/introduction/) to secure information transit.
Once the user is logged in with their credentials (username and password), they receive a token valid for 15 minutes, which grants access to 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 on a Site
The parameters 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 for a Site
The list of all meters for 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 Metering Type
The validated time series data for the site for a specific metering type, for example total electricity consumption or PV 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 for a Specific Meter
The validated time series data for 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 for a Specific Meter
The raw data, incremental (meter index) or differential (interval of a load profile), in time series for a meter for the selected period, directly from the meter without validation. Only available for physical meters and not for 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 for 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 the time series of a sensor, for a given period. If no period is provided, the latest data is returned. t_s is limited based on the 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>
},
...
]