Readings
The Readings API lets you get sensor readings data from the network. There are two ways to access it:
- Through the
readingsproperty of any Asset object, to query the readings of that asset. - Through live signals, to query a specific sensor stream with more control over the time range, sampling and aggregation.
Asset readings
Section titled “Asset readings”Every asset exposes a readings object with the following query methods:
readings: { latest(): Promise<AssetReadings> forRange(start: Date, end: Date): Promise<AssetReadings> forPeriod(): AssetReadingsCollection}Each reading is a Reading object:
type Reading = { asset: string; property: AssetProperty; value: number; date: Date; unit: string;}The properties an asset can have readings for depend on its type. See AssetReadings and the sensors property of the Asset.
forPeriod()
Section titled “forPeriod()”Returns the readings cached for the current simulation period, sampled with a 15 minute resolution.
Method signature
Section titled “Method signature”forPeriod(): AssetReadingsCollectionParameters
Section titled “Parameters”None.
Returns
Section titled “Returns”An AssetReadingsCollection: an array with one entry per 15 minute step that has readings, each containing its date and the readings for that step. It is empty when the asset has no readings.
latest()
Section titled “latest()”Retrieves the latest reading of each property measured in the asset, looking back up to 15 days from the start of the current period.
Method signature
Section titled “Method signature”latest(): Promise<AssetReadings>Parameters
Section titled “Parameters”None.
Returns
Section titled “Returns”A promise that resolves with an object with one Reading per measured property. Properties without readings in the last 15 days are not included, and the object is empty ({}) when the asset has no sensors.
Examples
Section titled “Examples”const asset = sdk.network.getAsset('Nellybay')const readings = await asset.readings.latest()console.log(readings)// {// level: { asset: 'Nellybay', property: 'level', value: 3.2, date: Date, unit: 'm' }// }forRange()
Section titled “forRange()”Retrieves the readings of an asset between two dates.
Method signature
Section titled “Method signature”forRange(start: Date, end: Date): Promise<AssetReadings>Parameters
Section titled “Parameters”start: Start date.end: End date. The range betweenstartandendcan’t be greater than 15 days.
Returns
Section titled “Returns”A promise that resolves with an object with an array of Reading objects per measured property. The object is empty ({}) when the asset has no sensors.
The promise is rejected if end is earlier than start, or if the range exceeds 15 days.
Examples
Section titled “Examples”Get readings for 24 hours for an asset.
const asset = sdk.network.getAsset('Nellybay')const readings = await asset.readings.forRange(new Date("2024-01-01"), new Date("2024-01-02"))
readings.level?.forEach((reading) => { console.log(reading)})Live signals
Section titled “Live signals”A LiveSignal is a descriptor of a sensor stream for a given asset and property. Get them from the network with getLiveSignals() or getLiveSignal().
type LiveSignal = { id: string; asset: string; property: AssetProperty; mappings: string[]; sampleIntervalMs: number; at(time: Date): Promise<ReadingPropertyValue | undefined>; inRange(timeStart: Date, timeEnd: Date): Promise<ReadingPropertyValue[]>; samplesInRange(timeStart: Date, timeEnd: Date, intervalSeconds: number): Promise<ReadingPropertyValue[]>; aggregateInRange( startDate: Date, endDate: Date, intervalSeconds: number, method: AggregationMethod ): Promise<ReadingPropertyValue[]>;}
type ReadingPropertyValue = { time: Date; value: number | boolean; unit?: Unit;}
type AggregationMethod = "first" | "last" | "sum" | "count" | "avg"Properties
Section titled “Properties”id: Unique identifier of the signal.asset: ID of the asset that produces the signal.property: Property measured by the signal, such aspressure,floworlevel.mappings: IDs of the source signals mapped to this live signal.sampleIntervalMs: Nominal sampling interval of the signal, in milliseconds.
Returns the reading nearest to (or at) the given time, or undefined if there is none.
at(time: Date): Promise<ReadingPropertyValue | undefined>inRange()
Section titled “inRange()”Returns all the readings between timeStart (inclusive) and timeEnd (exclusive).
inRange(timeStart: Date, timeEnd: Date): Promise<ReadingPropertyValue[]>samplesInRange()
Section titled “samplesInRange()”Returns the readings between timeStart (inclusive) and timeEnd (exclusive), sampled every intervalSeconds. Steps are aligned to timeStart, and each step takes the nearest available reading.
samplesInRange(timeStart: Date, timeEnd: Date, intervalSeconds: number): Promise<ReadingPropertyValue[]>aggregateInRange()
Section titled “aggregateInRange()”Returns the readings between startDate (inclusive) and endDate (exclusive), aggregated every intervalSeconds with the given method: first, last, sum, count or avg.
aggregateInRange( startDate: Date, endDate: Date, intervalSeconds: number, method: AggregationMethod): Promise<ReadingPropertyValue[]>Example
Section titled “Example”Get the hourly average pressure of a junction for the last day:
const signal = sdk.network.getLiveSignal('J1', 'pressure')if (signal) { const end = new Date() const start = new Date(end.getTime() - 24 * 60 * 60 * 1000) const hourly = await signal.aggregateInRange(start, end, 3600, 'avg')}