Indice dei contenuti

Climkit API

Nicolas Vodoz Aggiornato da Nicolas Vodoz

L'API per sviluppatori di Climkit permette agli sviluppatori registrati e autorizzati di ottenere dati di misurazione e di energia dai siti Climkit autorizzati.

Per registrarsi, gli sviluppatori devono ottenere i diritti di accesso ai dati dal proprietario dell'installazione e da Climkit SA.

Le richieste di accesso all'API devono essere indirizzate a service@climkit.io.

Le informazioni di accesso all'API sono diverse dalle informazioni di connessione all'account personale del portale Climkit.

Le informazioni di accesso possono essere utilizzate solo dallo sviluppatore registrato. I colleghi e i collaboratori devono presentare una richiesta individuale per ottenere i propri permessi di accesso.

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

1. Autenticazione

L'API di Climkit utilizza token Web JSON (https://jwt.io/introduction/) per proteggere il transito delle informazioni.

Una volta che l'utente ha effettuato l'accesso con le proprie credenziali (nome utente e password), riceve un token valido per 15 minuti che gli consente di accedere alle risorse autorizzate.

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. Siti

Tutti i siti

L'elenco di tutti i siti.

URL: /all_installations

Method: GET

Auth required: YES con un Token valido

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.

Informazioni su un sito

I parametri di un sito specifico.

URL: /installation_infos/<site_id>

Method: GET

Auth required: YES con un Token valido

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. Contatori

Tutti i contatori di un sito

L'elenco di tutti i contatori di un sito.

URL: /meter_info/<site_id>

Method: GET

Auth required: YES con un Token valido

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

I dati convalidati del sito per un tipo di misurazione

I dati di misurazione convalidati in serie temporale del sito per un tipo di misurazione specifico, ad esempio il consumo elettrico totale o la produzione fotovoltaica del sito.

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

Method: POST

Auth required: YES con un Token valido

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

I dati convalidati di un contatore specifico

I dati di misurazione convalidati in serie temporale di un contatore per il periodo selezionato.

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

Method: POST

Auth required: YES con un Token valido

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

I dati grezzi di un contatore specifico

I dati di misurazione grezzi, incrementali (indice del contatore) o differenziali (intervallo di una curva di carico), in serie temporale di un contatore per il periodo selezionato, direttamente estratti dal contatore senza convalida. Disponibile solo per i contatori fisici e non per i contatori virtuali.

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

Method: POST

Auth required: YES con un Token valido

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. Sensori

Ottenere tutti i sensori di un sito

URL: /<site_id>/sensors_list

Method: GET

Auth required: YES con un Token valido

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

Ottenere dati di serie temporali per un sensore specifico

Recupera le serie temporali di un sensore per un determinato periodo. Se non viene fornito alcun periodo, vengono restituiti gli ultimi dati. t_s è limitato in base all'utente/sito.

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

Method: GET

Auth required: YES con un Token valido

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?

API locale del Gateway

Contatto