Statistics endpoint

The Statistics endpoint provides aggregated metrics calculated from time series data, over specified time windows. This allows you to query values such as averages, minima, maxima, counts, standard deviation, etc., instead of raw data points. It is useful for downsampling data or getting summary insights over time intervals.

You can query one or multiple time series for statistics using GET:

curl "https://prism.raalabs.io/{ENVIRONMENT}/statistics/{domain}/{expression}" \
  -H "Authorization: Bearer $TOKEN"

...or POST:

curl -X POST "https://prism.raalabs.io/{ENVIRONMENT}/statistics/query" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '[
    "{domain}/{expression}",
    "{domain}/{expression}"
  ]'

As with measurements, use GET for a single domain/expression query and the POST /statistics/query (with a JSON array in the body) to retrieve multiple series in one call.

Request

Path parameters

Parameter	Description
imo	The IMO number of the vessel (if required by the domain’s format). Many domain expressions begin with the IMO number of the vessel.
domain	The contextual domain for the query (e.g. jsmea, raalabs, id).
expression	The expression identifying which time series to compute stats for (can be a specific path or include wildcards to select multiple series).

Query parameters

Like the measurements endpoint, the statistics query supports time range parameters and format selection. If a requested window doesn't both start and end in the past, the statistics for it are calculated using the available data, which may be incomplete.

It also introduces parameters to specify the type of aggregation and the window size for aggregation. If no time range is given, the default is from = -1h to to = now (last one hour). If no aggregation is specified, the default is avg (average). If no window is specified, the default window is 1 minute (1m).

• Time Range: Use from, to, from_epoch, to_epoch, since, last, year, month, day as described in the Measurements section to define the time range of data over which statistics are computed.

• Aggregation Functions: aggregations (string) – A comma-separated list of aggregation functions to compute for each time window. You can request multiple metrics at once. If this parameter is omitted, the API uses avg by default.

• Window Size: window (string) – The duration of each aggregation window. This is given as a time interval literal, e.g. 1m (1 minute), 2h (2 hours), 2d (2 days), etc. All data within each window will be used to calculate the aggregations. The default window is 1m if not specified.

• Format: format – Output format, either json or ndjson. (Parquet is not supported for statistics, see note below.)

Supported aggregations

The following aggregation functions are available to use in the aggregations parameter:

min	Minimum value in the window
max	Maximum value in the window
mean	Mean value in the window
avg	Average (time-weighted) value in the window
count	Count of data points (sample count)
sum	Sum of all values
stddev	Standard deviation of values
var	Variance of values
skewness	Statistical skewness of the values distribution
kurtosis	Statistical kurtosis of the values distribution
first_val	The first value in the time window
last_val	The last value in the time window
integral	Integral (area under the curve) over the window
first_time	Timestamp of the first data point in the window
last_time	Timestamp of the last data point in the window

You may combine multiple aggregations in one query by listing them separated with commas (e.g. aggregations=avg,max,min,count).

Response

If the request is valid, the API returns the computed statistics for each requested time series over the specified time range and window. The results are returned in time order, one object per time window, for each aggregation requested.

Note: Similar to the measurements endpoint, the id portion of the result keys will use the domain format you queried.

The format of the response depends on whether JSON or NDJSON is requested.

JSON format

For format=json (default), the response is a JSON array of objects. Each object represents the results of one time window and aggregation type. Within each object:

• There will be a field for the aggregation name requested, {DomainID}/{AggregationName}. The aggregation names and delimiter are determined by the domain that is requested.

• There will also be a timestamp field, which marks the timestamp for that window's result. The timestamp corresponds to the start of the aggregation window. (For example, if window=1h, a timestamp of 2025-09-10T09:00:00Z represents the window from 09:00 to 10:00.)

Example JSON response (for a query that requested average, max, min, and count aggregations):

[
  {
    "IMO1000001/ME ShaftPower/Avg": 13.12,
    "timestamp": "2025-09-10T09:00:00.000000Z"
  },
  {
    "IMO1000001/ME ShaftPower/Max": 15.47,
    "timestamp": "2025-09-10T09:00:00.000000Z"
  },
  {
    "IMO1000001/ME ShaftPower/Min": 10.85,
    "timestamp": "2025-09-10T09:00:00.000000Z"
  },
  {
    "IMO1000001/ME ShaftPower/Count": 3600,
    "timestamp": "2025-09-10T09:00:00.000000Z"
  }
]

(This example indicates that between 08:00 and 09:00 on Sept 10, 2025, the average ShaftPower was 13.12, the max was 15.47, the min was 10.85, and there were 3600 data points in that hour.)

If multiple time series were matched by the query (e.g., using a wildcard expression), the results will be returned as individual JSON objects.

NDJSON format

For format=ndjson, the output is similar to the JSON format, but each aggregation object is written on a separate line (newline-delimited). This is helpful for streaming or incremental processing of large results.

Each line will be a JSON object containing one or more {id/Aggregation} fields and a timestamp field, identical in structure to the objects shown in the JSON example above.

Parquet format

Parquet output is not available for the statistics endpoint at this point. If you request format=parquet (or the corresponding Accept header), the API will return an error message:

{ "error": "Parquet is not implemented for statistics" }

Examples

Aggregated Statistics (Average & Max over time)

Retrieve the average and maximum Main Engine Shaft Power for all vessels, aggregated in 1-hour windows, over the last day:

curl "https://prism.raalabs.io/{ENVIRONMENT}/statistics/raalabs/*/ME ShaftPower\
    ?aggregations=avg,max&window=1h&last=1day" \
    -H "Authorization: Bearer $TOKEN"

In this example:

• raalabs/*/ME ShaftPower targets the ShaftPower measurement for all vessels (* wildcard for IMO) in Raa Labs naming.

• aggregations=avg,max asks for Average and Maximum values.

• window=1h sets 1-hour aggregation windows.

• last=1day requests data for the last full day (24 hours).

The response will be a series of time-windowed results, each with an Avg and Max for that hour, along with a timestamp for the hour.

Statistics for a Specific Vessel (Multiple Metrics)

Get the mean and standard deviation of fuel oil consumption (mass flow rate) for a specific vessel (IMO 1234567), calculated over daily windows for the last 30 days:

curl "https://prism.raalabs.io/{ENVIRONMENT}/statistics/jsmea\
    /IMO1234567/jsmea_mac/MainEngine/FuelOilLine/*/*/MassFlowRate\
    ?aggregations=mean,stddev&window=1d&last=30days" \
    -H "Authorization: Bearer $TOKEN"

In this example:

• The domain/expression targets the MassFlowRate in the Main Engine Fuel Oil Line for vessel 1234567 (using wildcards for any sub-levels under FuelOilLine).

• aggregations=mean,stddev will return the daily average and daily standard deviation of that measurement.

• window=1d uses a one-day window for each data point (each result represents one day’s stats).

• last=30days means the last 30 full days (approximately the previous month).

The output will list one JSON object per day and aggregation type, each containing an aggragation name, and a timestamp(likely the start of the day).

Fleet-wide Comparative Statistics

Compare minimum and maximum engine temperatures across the fleet with 15-minute aggregation windows for the past week:

curl "https://prism.raalabs.io/{ENVIRONMENT}/statistics/raalabs\
    /*/ME*Temp*?aggregations=min,max&window=15m&since=1week" \
    -H "Authorization: Bearer $TOKEN"

In this example:

• The expression raalabs/*/ME*Temp* uses wildcards to match any Raa Labs tag that contains "ME" and "Temp" (e.g., it could match tags like "ME ExhaustTemp" or "ME CoolingTemp" depending on naming). This effectively tries to fetch engine temperature-related metrics for all vessels.

• aggregations=min,max will produce two values per window: the minimum and maximum temperature observed in each 15-minute interval.

• window=15m sets the aggregation interval to 15 minutes.

• since=1week retrieves data from one week ago up until now.

The result will show 15-minute snapshots of the lowest and highest recorded values among those temperature measurements, across the fleet, for the last week.