List & Filter Historical Data

This endpoint allows you to view all the historical data in the system, and apply various required and optional filters.

A useful note: Because there is so much historical data (potentially 1M+ results for any given search), we use split the results into pages using a method called "cursor-based pagination". When you get data, the server creates an "opaque cursor", which is basically a pointer to a specific location in the data. You can use this cursor in future requests to get the next n items starting from that cursor. Leaving the cursor blank/not including it is like getting page 1.

Endpoint

GET: https://api.smart-mfg.net/historical-data

Query Parameters

Parameter	Required	Type	Description
from	Yes	date	The start of the range of data to be included. Recommended format is ISO 8601 (YYYY-MM-DD).
to	Yes	date	The end of the range of data to be included. Recommended format is ISO 8601 or (YYYY-MM-DD).
meter_numbers	No	array	An array of meter numbers. Each meter number must be a string with a maximum length of 255 chars. Defaults to null, which will show all meters in the given company.
perpage	No	integer	Number of results per page. Must be between 1 and 100. Defaults to 10.
cursor	No	string	A cursor for pagination. Must be a string with a maximum length of 255 chars.
timezone	No	string	The timezone for the data. Must be a valid timezone identifier. Defaults to America/Denver.
company_id	No **	integer	** Recommended (only if the user has multiple companies) to explicitly set what company you're getting data for.

Example Request

import requests

token = "YOUR_GENERATED_TOKEN"

headers = {
    "Authorization": f"Bearer {token}",
    "Accept": "application/json"
}

params = {
    "from": "2020-01-01",
    "to": "2024-01-01",
    "meter_numbers[]": ["123456", "789012"],  # Leave empty/exclude to get all meters
    "perpage": 10,  # Optional, defaults to 10
    "cursor": "abcdef123456",  # Leave empty/exclude to get page 1
    "timezone": "America/Denver",  # Optional, defaults to America/Denver
    "company_id": 1
}

response = requests.get("https://api.smart-mfg.net/historical-data", headers=headers, params=params)
print(response.json())

if 200 <= response.status_code < 300:
    print("Request successful!")
else:
    print("Failed to retrieve historical data.")

The API will return a JSON response with either the correct data, or a list of errors.

Example Response

The response data has two parts: data and meta.

• data contains the historical data for the requested meters.
• links contains the URLs for the first, last, previous, and next pages of data.
• meta contains pagination information required to move forward or backward between pages.

{
  "data": [
    {
      "date": "2023-12-31",
      "meter_number": "1",
      "nomination": null,
      "measured": 1
    },
    {
      "date": "2023-12-31",
      "meter_number": "2",
      "nomination": 2,
      "measured": 2
    },
    {
      "date": "2023-12-31",
      "meter_number": "3",
      "nomination": 3,
      "measured": 4
    },
    {
      "date": "2023-12-31",
      "meter_number": "4",
      "nomination": 4,
      "measured": 5
    },
    {
      "date": "2023-12-31",
      "meter_number": "5",
      "nomination": 2,
      "measured": 4
    },
    {
      "date": "2023-12-31",
      "meter_number": "6",
      "nomination": 1,
      "measured": 2
    },
    {
      "date": "2023-12-31",
      "meter_number": "7",
      "nomination": 1,
      "measured": 2
    },
    {
      "date": "2023-12-31",
      "meter_number": "8",
      "nomination": 4,
      "measured": 4
    },
    {
      "date": "2023-12-31",
      "meter_number": "9",
      "nomination": 8,
      "measured": 8
    },
    {
      "date": "2023-12-31",
      "meter_number": "10",
      "nomination": 44,
      "measured": 46
    }
  ],
  "links": {
    "first": null,
    "last": null,
    "prev": null,
    "next": "https://api.smart-mfg.net/historical-data?cursor=eyJkYXRlIjoiMjAyMy0xMi0zMSIsIm1ldGVyX251bWJlciI6IjkxMjAzIiwiX3BvaW50c1RvTmV4dEl0ZW1zIjp0cnVlfy"
  },
  "meta": {
    "path": "https://api.smart-mfg.net/historical-data",
    "per_page": 10,
    "next_cursor": "eyJkYXRlIjoiMjAyMy0xMi0zMSIsIm1ldGVyX251bWJlciI6IjkxMjAzIiwiX3BvaW50c1RvTmV4dEl0ZW1zIjp0cnVlfy",
    "prev_cursor": null,
    "has_pages": true,
    "has_more_pages": true
  }
}