Accessing Metric Data (JSON)
If you are interested in access to specific data from the Nola platform, you can always send us an email or give us a call. We're more than happy to set you up for integrations.
Otherwise, if you haven't already, review Authentication to see how to talk to the Nola API.
Scenario
You venue is tracking the occupancy in a room.
You want to display the current occupancy on a screen in the room, as well as the hourly occupancy trend over the last X hours.
Tasks
1. Identify the metric ID of the occupancy metric.
Navigate to the Nola dashboard.
Select your venue's Location and then select "Metrics" from the menu.
You will see two tabs: "Simple Metrics" and "Complex Metrics". Review the available metrics and identify the metric you are interested in. Click it.
In your browser, the URL will change to something like
https://app.nolahq.com/company/XXX/locations/YYY/metrics/de/%7BZZZ%7DThe
ZZZin the above URL is the metric ID. Take note of:- The metric ID (
ZZZ) - The location ID (
YYY)
- The metric ID (
2. Get the real-time occupancy value.
There is an HTTP GET endpoint available for accessing the current value of a metric (where applicable). It can be considered as a single "gauge" value.
You will need the Location ID as well as the Metric ID from the previous step:
GET /api/v1/locations/{LOCATION_ID}/metrics/{METRIC_ID}/count
For example:
const locationID = "979956b8-5ea1-4995-bc29-ad414d7dda68";
const metricID = "58d4200d-36dc-41b6-a512-fcd455413d42";
const response = await client.fetch(
`https://app.nolahq.com/api/v1/locations/${locationID}/metrics/${metricID}/count`
);
const data = await response.json();
console.log(data);
would produce (some fields omitted for brevity):
{
"data": {
"count": 0,
"float_value": 0,
"formatted_value": "0",
"time": "2023-12-09T12:33:14Z",
},
"success": true
}
Whether you use the count or float_value field depends on the nature of the metric. For occupancy, you should use count.
3. Get the historical occupancy data for the last X hours (per hour).
There is an HTTP GET endpoint available for accessing the historical trend data of a metric. Options can be passed as a query through the q URL query parameter (which is a base64-encoded JSON string).
The schema of the `q` JSON object
| Parameter | Description | Example/Valid Values |
|---|---|---|
period | Specifies the time period for the data. | CustomRange, FixedRange, Today, Yesterday, ThisWeek, LastWeek, ThisMonth, LastMonth |
scale | Determines the time bucket for each data value. | OneMinute, TenMinute, Hour, Day |
date_from | The RFC3339 date string representing the start of the data period. It should be the local time of the venue, represented in UTC. Only used if period is CustomRange or FixedRange. | 2022-06-01T15:00:00Z means "3pm in the time zone of the venue". |
date_to | The end date for the data range. See comments above. | See above. |
show_average | A boolean indicating whether to show average values or not. | true, false |
show_min | A boolean indicating whether to show minimum values or not. | true, false |
show_max | A boolean indicating whether to show maximum values or not. | true, false |
event_value_type | Reserved. Always Count. | Count |
data_type | Reserved. Always use example value. | {"type": "Count", "value": "Count"} |
display_hours | Use Venue Operating Hours or 24 hours (when period is e.g. Today) | OH, 24H |
show_summary | A boolean indicating whether to show a summary of data or not. | true, false |
hide_zero_buckets | Valid for CSV API requests only. A boolean indicating whether to exclude rows which have zero values only. | true, false |
GET /api/v1/locations/{LOCATION_ID}/metrics/{METRIC_ID}/trend?q={QUERY}
Don't forget to JSON+base64 encode the q query parameter.
For example:
const locationID = "979956b8-5ea1-4995-bc29-ad414d7dda68";
const metricID = "58d4200d-36dc-41b6-a512-fcd455413d42";
const params = btoa(JSON.stringify({
period: "CustomRange",
scale: "Hour",
date_from: "2023-12-08T00:00:00Z",
date_to: "2023-12-09T00:00:00Z",
event_value_type: "Count",
data_type: { type: "Count", value: "Count" },
display_hours: "OH",
show_min: false,
show_max: false,
show_average: false,
show_summary: true
}));
const response = await client.fetch(
`https://app.nolahq.com/api/v1/locations/${locationID}/metrics/${metricID}/trend?q=${params}`
);
const data = await response.json();
console.log(data);
would produce something like this (some fields omitted for brevity):
Sample Metric Trend Response
{
"data": {
"time_from": 1701993600,
"time_to": 1702166399,
"timezone_offset": 39600,
"metrics": [
{
"time_from": 1701993600,
"time_to": 1702166399,
"time": [
1701997200,
1702000800,
1702004400,
1702008000,
1702011600,
1702015200,
1702018800,
1702022400,
1702026000,
1702029600,
1702033200,
1702036800,
1702040400,
1702044000,
1702047600,
1702051200,
1702054800,
1702058400,
1702062000,
1702065600,
1702069200,
1702072800,
1702076400,
1702080000,
1702083600,
1702087200,
1702090800,
1702094400,
1702098000,
1702101600,
1702105200,
1702108800,
1702112400,
1702116000,
1702119600,
1702123200,
1702126800,
1702130400,
1702134000,
1702137600,
1702141200,
1702144800,
1702148400,
1702152000,
1702155600,
1702159200,
1702162800,
1702166400
],
"values": [
0.004166666666666667,
0.004166666666666667,
0.01074074074074074,
0.0125,
0,
0.0125,
0.03791666666666667,
0.05861111111111111,
0.09305555555555557,
0.2179573512906846,
0.11904761904761904,
0.2815611471861472,
0.30278446293797173,
0.09931286549707603,
0.08597222222222224,
0.07958333333333334,
0.2940427010783048,
0.04865079365079365,
0.1075,
0.030555555555555555,
0.05785353535353535,
0.02222222222222222,
0.02,
0.01583333333333333,
0.0588888888888889,
0.2910759891410046,
0.09581140350877194,
0.021388888888888888,
0.022407407407407407,
0.030277777777777775,
0.046250000000000006,
0.034999999999999996,
0.058333333333333334,
0.11898148148148151,
0.04452380952380953,
0.05448412698412698,
0.034166666666666665,
0.0625,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0
],
}
],
"no_filter_data": false
},
"success": true
}
The time and values fields are aligned and form the data points for the metric.