API endpoints

Overview

The API is organized into three main categories of endpoints, each serving a different purpose:

• Measurements (Time Series) endpoints: Retrieve actual time-series data points (raw sensor measurements over time).

• Metadata endpoints: Retrieve descriptive information (metadata) about time series tags (e.g. name, description, units, source of a sensor).

• Statistics endpoints: Retrieve aggregated statistics (computed metrics) on time-series data over specified time windows.

All endpoint URLs include a domain and an expression as path parameters, which together specify what data you are querying. The domain represents a context or naming schema (for example, a standard for tag names), and the expression is a query string identifying one or many time series within that domain.

Common path parameters

Every endpoint path includes {domain}/{expression}:

• domain: The contextual domain or naming scheme for the data. For example: jsmea (Japan Ship Machinery and Equipment Association standard for ISO 19848), raalabs (a flat naming scheme used by Raa Labs), id (the raw UUID of a time series), etc. The domain determines how the API interprets the expression part.

• expression: A query string that identifies the hierarchy or path of the data requested within the chosen domain. This could be a full specific path to a tag or include wildcard characters (*) to match multiple items.

Wildcard support: You can use * in expressions to match individual levels of the hierarchy (matching multiple hierarchy levels is not supported), allowing broad queries. This is similar to wildcards in MQTT topics. For example:

• Hierarchical path example: IMO1234567/411.1/C101.61/S203/meta/qty-mass.flow.rate – a full path locating a specific measurement in the hierarchy (for a given IMO number and subsystem).

• Wildcard example: IMO1234567/*/qty-mass.flow.rate – uses * to match any value in the second level, returning all measurements ending in qty-mass.flow.rate for the vessel IMO1234567.

When you query data, the domain and expression together determine which time series are returned. You can retrieve a single tag's data or use wildcards to retrieve multiple related tags in one query.