​
What is a Reading?

A Reading represents a single snapshot of the state of an Entity. Using the Readings API, you can retrieve a list of Readings within a timespan, with each reading representing a single moment in time.

Entities of the same type, produce similarly structured Readings. This allows you to process them uniformly, regardless of type of device or vehicle your working with. However, it is important to note that depending on the type of Entity or it’s manufacturer, some properties can be unavailable (omitted) due to manufacturer limitations.

​
Aggregations

The amount of time between each Reading (the resolution) varies per Entity type and manufacturer and mostly depends on manufacturer limitations. Some Entities produce many of Readings in a relatively short amount of time. The more Readings are produced within a given timespan, the greater the detail with which you can observe changes on the state of that Entity. But, it can also make it more cumbersome to process them.

That’s why our Readings API supports Aggregations right out the box. Aggregations reduce the resolution of a list of Readings, combining multiple Readings into one by statistically averaging them.

Aggregations are currently only supported for certain types of Entities.

​
Retrieving Readings

To retrieve Readings, we’re using the Get /entities/{entityId}/readings endpoint.

​
Parameters

startrequired

Start (date & time) of the timespan for which you want to list all Readings.

endoptional (defaults to current date & time)

End (date & time) of the timespan for which you want to list all Readings.

Note: input and output of time on the re.alto platform is in Zulu time (UTC)

Access the full list of available parameters through the API References.

​
Example Request

curl --request GET \
     --url 'https://platform.realto.io/api/v1/entities/[entityId]/readings \
     --header 'accept: application/json'
     --data '
{
  "start": "2024-01-01 00:00:00Z",
  "end": "2024-02-01 00:00:00Z"
}
'

​
Example Responses

Note: The values marked ‘positive’ relate to consumed energy, while ‘negative’ power always relates to the production of energy.

Example of an EV Reading:

{
    "id": "79649e1c-e23e-[...]",
    "entityId": "35509f52-1034-[...]",
    "measured": "2024-09-03T05:49:21Z",
    "received": "2024-09-03T05:50:09.2077509Z",
    "processed": "2024-09-03T05:50:10.8994326Z",
    "data": {
        "instantaneousCurrent": {
            "total": 0,
            "unit": "A"
        },
        "instantaneousVoltage": {
            "total": 0,
            "unit": "V"
        },
        "isCharging": false,
        "isPluggedIn": false,
        "odometer": {
            "unit": "km",
            "value": 67380
        },
        "positiveActiveInstantaneousPower": {
            "total": 0,
            "unit": "W"
        },
        "range": {
            "unit": "km",
            "value": 179
        },
        "stateOfCharge": {
            "unit": "percent",
            "value": 49
        }
    }
}

Example of a Retrofitmeter Reading:

{
    "id": "71795703-1d72-[...]",
    "entityId": "bd297b95-5579-[...]",
    "measured": "2024-09-03T02:06:39Z",
    "received": "2024-09-03T02:06:44.6020711Z",
    "processed": "2024-09-03T02:06:44.9891195Z",
    "data": {
        "instantaneousCurrent": {
            "l1": 2.95,
            "total": 2.95,
            "unit": "A"
        },
        "instantaneousVoltage": {
            "l1": 242.3,
            "total": 242.3,
            "unit": "V"
        },
        "negativeActiveEnergy": {
            "t1": 12794452,
            "t2": 5067134,
            "total": 17861586,
            "unit": "Wh"
        },
        "negativeActiveInstantaneousPower": {
            "total": 715,
            "unit": "W"
        },
        "positiveActiveEnergy": {
            "t1": 6538224,
            "t2": 8590571,
            "total": 15128795,
            "unit": "Wh"
        },
        "positiveActiveInstantaneousPower": {
            "total": 0,
            "unit": "W"
        }
    }
}

​
Retrieving Aggregations

To retrieve Readings, we’re using the Get /entities/{entityId}/aggregations endpoint.

​
Parameters

startrequired

Start (date & time) of the timespan for which you want to list Aggregations.

endoptional (defaults to current date & time)

End (date & time) of the timespan for which you want to list Aggregations.

resolutionrequired

The granularity at which Readings are combined or summarised. It determines the size of the time intervals over which data is Aggregated.

Note: input and output of time on the re.alto platform is in Zulu time (UTC)

Access the full list of available parameters through the API References.

​
Example Request

curl --request GET \
     --url 'https://platform.realto.io/api/v1/entities/.../aggregations \
     --header 'accept: application/json'
     --data '
{
  "start": "2024-09-02 07:00:00Z",
  "end": "2024-09-02 08:00:00Z",
  "resolution": "30 minutes"
}

​
Example Response

{
    "data": [
        {
            "id": "81529121-a78f-[...]",
            "entityId": "bd297b95-5579-[...]",
            "timeframe": {
                "start": "2024-09-02T07:00:00Z",
                "end": "2024-09-02T07:30:00Z"
            },
            "data": {
                "negativeActiveEnergy": {
                    "t1": 0,
                    "t2": 3,
                    "total": 3,
                    "unit": "Wh"
                },
                "positiveActiveEnergy": {
                    "t1": 36,
                    "t2": 31,
                    "total": 67,
                    "unit": "Wh"
                }
            }
        },
        {
            "id": "4b9e7495-a411-[...]",
            "entityId": "bd297b95-5579-[...]",
            "timeframe": {
                "start": "2024-09-02T07:30:00Z",
                "end": "2024-09-02T08:00:00Z"
            },
            "data": {
                "negativeActiveEnergy": {
                    "t1": 0,
                    "t2": 3,
                    "total": 3,
                    "unit": "Wh"
                },
                "positiveActiveEnergy": {
                    "t1": 36,
                    "t2": 31,
                    "total": 67,
                    "unit": "Wh"
                }
            }
        },
    ],
    "meta": {
        "pageSize": 25
    }
}

Was this page helpful?

Guided OnboardingCommands