Table of Contents

Climkit API

Nicolas Updated by Nicolas

The Climkit Developer API allows registered and authorized developers to get meteringand energy data from permitted Climkit installations.

In order to register, developers must obtain the rights to get data from the installation's owner and from Climkit SA.

Request for API access must be adressed to info@climkit.io.

API credentials are different from Climkit portal personal account login infos.

Access information can only be used by the registered developer. Colleagues and co-workers must apply individually to get their own access rights.

API End Point: https://api.climkit.io/api/v1

1. Authentication

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>},
    }

Climkit API uses JSON Web Tokens (https://jwt.io/introduction/ ) to securely transit information.

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

2. Sites

Get all sites

Get all installation sites ids.

URL : /all_installations

Method : GET

Auth required : YES with valid Token

Requests limit : 1/second

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

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

Returns
-------
array_like

Get site infos

Get the information about an installation site.

URL : /installation_infos/<site_id>

Method : GET

Auth required : YES with 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
-------
obj
    An object formatted as follow:
    {
        '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

Get all the meters of a site

URL : /meter_info/<site_id>

Method : GET

Auth required : YES with 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
----------
array_like

    {
        'id': <str representing an ObjectID>
        'type': {'electricity', 'heating', 'cold_water', 'hot_water'},
        'prim_ad': <int>,
        'virtual': <boolean>
    }

Get timeseries data for a specific type of meters

Get the timeseries processed data of type <meter_type>, for the whole site <site_id>.

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

Method : POST

Auth required : YES with valid Token

Requests limit : 1/second

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

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
-------
array_like

Get timeseries processed data of a specific meter

Get the timeseries 'validated' or 'processed' data of meter <meter_id>.

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

Method : POST

Auth required : YES with valid Token

Requests limit : 1/second

Parameters (GET)
----------
site_id: str
    The ID of the installation site
meter_id: {'electricity', 'heating', 'cold_water', 'hot_water'}
    The type of meter data
meter_prim_ad: int
    The primary address 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', 'D', 'M', 'Y'}, optional
    The sampling frequency of the returned data list

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

Returns
-------
array_like

Get timeseries raw data of a specific meter

Get the timeseries raw data of meter <meter_id>

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

Method : POST

Auth required : YES with valid Token

Requests limit : 1/second

Parameters (GET)
----------
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
-------
array_like

4. Sensors

Get all the sensors of a site

Get all sensors of a site.

URL : /<site_id>/sensors_list

Method : GET

Auth required : YES with 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 timeseries data for a specific sensor

Get the timeseries of a sensor, for a given period. If no period is provided, the last data is returned.The t_s is limited depending on the user/site.

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

Method : GET

Auth required : YES with 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>
        },
        ...
    ]

How Did We Do?

Gateway Local API

Contact