Measurements

Endpoint

Depending on your organization's region, you will need to send your measurements to the corresponding endpoint:

EU: https://analytics-api-eu.piano.io/import/measurements/v1

US: https://analytics-api-us.piano.io/import/measurements/v1

Authentication

• header name: x-api-key
• header value: an API key from your profile in the solution with the following pattern: <ACCESSKEY>_<SECRETKEY>

Payload

Parameters

Parameter	Mandatory?	Type	Comment
key	YES	string	Measurement key
period	YES	string / number	Period for the measurement. Local time. See here for available formats
values	YES	object	Measurement values
properties	NO	object	List of analytics properties to cross data with
site_id	YES / NO	int	Site ID. Mandatory for site-scoped measurements, must not be present for orga-scoped

tip

You can find a measurement example in your Data Management interface.

period Format

Depending on your measurement's configured periodicity, you must use the corresponding format:

Periodicity	Format
Minute	YYYY-MM-DDTHH:MM:00
Hour	YYYY-MM-DDTHH:MM:00
Day	YYYYMMDD or YYYY-MM-DD
Month	YYYYMMDD or YYYY-MM-DD

Limits

Feature	Limit
JSON max body size	100KB
NDJSON max body size	1GB
NDJSON max measurement size	100KB

NDJSON

tip

We highly recommend using NDJSON over JSON for your measurements ingestion

Content-type

application/x-ndjson

Body with site_id

{"key": "temperature", "period": "2023-01-01T12:00:00", "values": {"celsius": 25.5, "fahrenheit": 77.9}, "properties": {"geo_city": "Paris", "probe": "Siemens"}, "site_id": 1245695}
{"key": "temperature", "period": "2023-01-01T12:00:00", "values": {"celsius": 35.5, "fahrenheit": 95.9}, "properties": {"geo_city": "Bordeaux", "probe": "Siemens"}, "site_id": 1245695}

Body without site_id

{"key": "temperature", "period": "2023-01-01T12:00:00", "values": {"celsius": 25.5, "fahrenheit": 77.9}, "properties": {"geo_city": "Paris", "probe": "Siemens"} }
{"key": "temperature", "period": "2023-01-01T12:00:00", "values": {"celsius": 35.5, "fahrenheit": 95.9}, "properties": {"geo_city": "Bordeaux", "probe": "Siemens"} }

JSON

Content-type

application/json

Body with site_id

{
  "measurements": [
    {
      "key": "temperature",
      "period": "2023-01-01T12:00:00",
      "values": {
        "celsius": 25.5,
        "fahrenheit": 77.9
      },
      "properties": {
        "geo_city": "Paris",
        "probe": "Siemens"
      },
      "site_id": 1245695
    },
    {
      "key": "temperature",
      "period": "2023-01-01T12:00:00",
      "values": {
        "celsius": 35.5,
        "fahrenheit": 95.9
      },
      "properties": {
        "geo_city": "Bordeaux",
        "probe": "Siemens"
      },
      "site_id": 1245695
    }
  ]
}

Body without site_id

{
  "measurements": [
    {
      "key": "temperature",
      "period": "2023-01-01T12:00:00",
      "values": {
        "celsius": 25.5,
        "fahrenheit": 77.9
      },
      "properties": {
        "geo_city": "Paris",
        "probe": "Siemens"
      }
    },
    {
      "key": "temperature",
      "period": "2023-01-01T12:00:00",
      "values": {
        "celsius": 35.5,
        "fahrenheit": 95.9
      },
      "properties": {
        "geo_city": "Bordeaux",
        "probe": "Siemens"
      }
    }
  ]
}