Measurements

You can find detailed information about how catalogs work in our Help center.

Import single measurement

Endpoint

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

• EU: POST https://analytics-api-eu.piano.io/import/v1/measurements
• US: POST https://analytics-api-us.piano.io/import/v1/measurements
• AP: POST https://analytics-api-ap.piano.io/import/v1/measurements

Headers

Authentication

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

Content-Type

• header name: Content-Type
• header value: application/json

Payload

The expected payload is a JSON object, following the schema below:

{
  "key": "<MEASUREMENT_KEY>",
  "period": "<DATE>",
  "values": {
    "key1": 1,
    "key2": 2
  },
  "properties": {
    "property1": "Property value 1",
    "property2": "Property value 2"
  },
  "site_id": 1245695
}

Parameters

Parameter	Mandatory?	Type	Comment
key	YES	string	Measurement key
period	YES / NO	string / number	Period for the measurement. Local time. See Period format section for available formats. You should use either period or period_utc but it is mandatory to use one.
period_utc	YES / NO	string / number	Period for the measurement. UTC time. See Period format section for available formats. You should use either period or period_utc but it is mandatory to use one.
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.

Size limits

Feature	Limit
JSON max body size	100KB

Import multiple measurements

In order to import multiple measurements, you can use a batch request. To do so, we offer a dedicated endpoint expecting ndJSON (newline-delimited JSON) as payload.

Endpoint

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

• EU: POST https://analytics-api-eu.piano.io/import/v1/measurements/batch
• US: POST https://analytics-api-us.piano.io/import/v1/measurements/batch
• AP: POST https://analytics-api-ap.piano.io/import/v1/measurements/batch

Headers

Authentication

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

Content-Type

• header name: Content-Type
• header value: application/x-ndjson

Payload

The expected payload is one-line JSON object per measurement to import, following the schema below:

{"key":"<MEASUREMENT_KEY>","period":"<DATE>","values":{"key1":1,"key2":2},"properties":{"property1":"Property value 1a","property2":"Property value 2a"},"site_id":1245695}
{"key":"<MEASUREMENT_KEY>","period":"<DATE>","values":{"key1":3,"key2":4},"properties":{"property1":"Property value 1b","property2":"Property value 2b"},"site_id":1245695}
{"key":"<MEASUREMENT_KEY>","period":"<DATE>","values":{"key1":5,"key2":6},"properties":{"property1":"Property value 1c","property2":"Property value 2c"},"site_id":1245695}
{"key":"<MEASUREMENT_KEY>","period":"<DATE>","values":{"key1":7,"key2":8},"properties":{"property1":"Property value 1d","property2":"Property value 2d"},"site_id":1245695}

Parameters

Parameter	Mandatory?	Type	Comment
key	YES	string	Measurement key
period	YES / NO	string / number	Period for the measurement. Local time. See Period format section for available formats. You should use either period or period_utc but it is mandatory to use one.
period_utc	YES / NO	string / number	Period for the measurement. UTC time. See Period format section for available formats. You should use either period or period_utc but it is mandatory to use one.
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

We highly recommend using NDJSON over JSON for your measurements ingestion.

Size limits

Feature	Limit
ndJSON max body size	1GB
ndJSON max line size	100KB

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

Notes:

• Use period for local time, or period_utc for UTC time. Exactly one of them is required.

Volume limits

Global volume limits (maximum number of ingested measurements):

• Minute granularity: 100 per minute, 140 000 per day
• Hour granularity: 1 000 per hour, 24 000 per day
• Day granularity: 100 000 per day
• Month granularity: 100 000 per month