Skip to content

Implementation example

This section gives a step-by-step example for collecting sensors, specifications, pricing, measurement series, and uploading consumption. Refer to the API Reference for additional filtering, sorting, and search options.

Step 1: Sensors

Sensors are referenced when uploading consumption.

Endpoint: GET /measurements/sensors/sensor/list/

GET .../measurements/sensors/sensor/list/?_page=1&_page_size=500&apartment__isnull=false

Query parameters:

  • _page — Page number (e.g. 1)
  • _page_size — Page size (e.g. 500)
  • apartment__isnull — false for sensors linked to apartments; use other space filters for unlinked or different spaces

Step 2: Sensor specifications

From each sensor's specification attribute, build a set of specification IDs, then fetch measurements.sensorspecification items.

  • Attributes such as output mode and granularity affect how you upload consumption (see Step 8).

Endpoint: GET /measurements/sensors/sensorspecification/list/

GET .../measurements/sensors/sensorspecification/list/?id__in=<spec-id-1>,<spec-id-2>&_page=1&_page_size=500

Query parameters:

  • id__in — Comma-separated specification IDs from sensors (step 1)
  • _page — Page number (e.g. 1)
  • _page_size — Page size (e.g. 500)

Step 3: Price groups

From sensors or specifications, build a set of specification IDs, then fetch measurements.pricegroup items.

Endpoint: GET /measurements/sensors/pricegroup/list/

GET .../measurements/sensors/pricegroup/list/?sensor_specification__in=<spec-id-1>,<spec-id-2>&_page=1&_page_size=500

Query parameters:

  • sensor_specification__in — Comma-separated specification IDs from step 2
  • _page — Page number (e.g. 1)
  • _page_size — Page size (e.g. 500)

Step 4: Price items

From price groups, build a set of price group IDs, then fetch measurements.priceitem items.

  • The latest valid (in-range) price item is used as the price for a given consumption date.

Endpoint: GET /measurements/sensors/priceitem/list/

GET .../measurements/sensors/priceitem/list/?price_group__in=<price-group-id-1>,<price-group-id-2>&_page=1&_page_size=500

Query parameters:

  • price_group__in — Comma-separated price group IDs from step 3
  • _page — Page number (e.g. 1)
  • _page_size — Page size (e.g. 500)

Step 5 (optional): Price group filters (Price Group Only Enabled For)

Endpoint: GET /measurements/sensors/pricegrouponlyenabledfor/list/

GET .../measurements/sensors/pricegrouponlyenabledfor/list/?price_group__in=<price-group-id-1>,<price-group-id-2>&_page=1&_page_size=500

Query parameters:

  • price_group__in — Comma-separated price group IDs from step 3
  • _page — Page number (e.g. 1)
  • _page_size — Page size (e.g. 500)

Step 6: Measurement series

From sensors, build a set of sensor IDs, then fetch measurements.measurementseries items.

  • Each series has a values array: one entry per day (granularity d) or per hour (granularity h). For example, January with daily granularity has 31 values. null means no consumption registered.

Endpoint: GET /measurements/measurementseries/list/

GET .../measurements/measurementseries/list/?sensor__in=<sensor-id-1>,<sensor-id-2>&_page=1&_page_size=500

Query parameters:

  • sensor__in — Comma-separated sensor IDs from step 1
  • _page — Page number (e.g. 1)
  • _page_size — Page size (e.g. 500)

Step 7 (optional): Other write actions

For other operations (e.g. connecting sensors, managing price groups and items), use the entities' normal create/update/delete or bulk endpoints and ensure your integration has the required permissions.

See API Reference for measurement entity endpoints.

Step 8: Consumption uploading

Upload consumption for the given sensors (no pricing).

  • use_external_id: false = keys in data are measurements.sensor IDs; true = keys are the sensor's external_id attribute.
  • Granularity: d (daily): one value per day; use 00:00:00 for measured_at. h (hourly): one value per hour; use xx:00:00.
  • Output mode (on measurements.sensorspecification): c (cumulative): stored consumption is the difference between consecutive values; d (delta): values are stored as consumption.

On success, the response includes how many measurement values were added per sensor (by ID) and the serialized sensors used.

Endpoint: POST /measurements/measurementseries/values/

{
  "data": {
    "<sensor-id-or-external-id>": [
      { "measured_at": "2024-01-01T00:00:00.000Z", "value": 1.1 },
      { "measured_at": "2024-01-02T00:00:00.000Z", "value": 1.5 }
    ]
  },
  "use_external_id": false
}
© Pigello. All rights reserved.