API version 2026-09-10 has been released.
release notes
Ctrlk
raalabs.com
linkedin
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Metadata Endpoint

The Metadata endpoint returns descriptive information about time series tags. This may include identifiers across multiple naming domains, data source, unit of measure, scale factor, value ranges, associated vessel, and other contextual attributes. Use this endpoint to understand what a particular time series represents.

curl "https://portal.raalabs.io/{ENVIRONMENT}/metadata/{domain}/{expression}" \
  -H "Authorization: Bearer $TOKEN" \
  -H "x-api-version: 2026-09-10"
import requests

TOKEN = "YOUR_TOKEN"
ENVIRONMENT = "YOUR_ENVIRONMENT"

url = f"https://portal.raalabs.io/{ENVIRONMENT}/metadata/{domain}/{expression}"
headers = {
    "Authorization": f"Bearer {TOKEN}",
    "x-api-version": "2026-09-10",
}

response = requests.get(url, headers=headers)

Request

Path Parameters

Parameter
Description

domain

The contextual domain for the metadata query (e.g. jsmea, raalabs, id, vis-3-8a).

expression

The domain-specific query expression used to select which time series metadata to return. This can be a specific path or include wildcards (*) to retrieve multiple tags. In many domains, the expression begins with the vessel’s IMO number.

Query Parameters

  • Format Parameter:

    • format (string): Desired output format of the metadata. Options are:

      • json (default): JSON array response.

      • ndjson: Newline-delimited JSON, suitable for streaming large results.

  • Verbose Parameter:

    • verbose (boolean): Some domains offer more human-readable, verbose domainIds. This parameter allows you to toggle verbose domainIds on and off. If the domain does not distinguish between verbose and regular IDs, this parameter does not have any effect.

      • false (default): response includes regular domainIds

      • true: response includes verbose domainIds

Response

If the query is valid, the response will include metadata for all matching time series. The response structure depends on the chosen format. Common among all of them is the individual metadata object, which contains the following attributes:

Top-level fields:

  • id – The ID for the time series, according to the chosen domain in the request.

  • timeSeriesId – A unique UUID for the time series (internal identifier).

  • source – Source system or origin of the data (e.g., sensor or system name).

  • dataProvider – The data provider responsible for the time series.

  • unitOfMeasure – Unit of measure for the values (e.g., bar for pressure, °C for temperature).

  • scale – Scaling factor applied to the raw data.

Vessel object:

  • vessel.name – The name of the vessel the data is associated with.

  • vessel.imo – The IMO number of the vessel.

Domains object:

The domains object maps the time series across different naming domains. Each key represents a domain and contains the ID of the time series within that domain, along with domain-specific metadata.

Available domains (a time series may not include all):

  • id – Uses the unique timeSeriesId as identifier.

  • jsmea – JSMEA domain naming with the hierarchical levels as separate fields: namingRule, category, subcategory, content, position, item, and suffix.

  • maker – Includes name, description, rangeHigh, and rangeLow, specified by the maker of the machinery or equipment. The range fields specify the expected minimum and maximum values for the measurement.

  • raalabs – Raa Labs naming convention with id and shortName.

  • vis-3-8a – VIS 3-8a domain naming with codes of the primaryItem and secondaryItem. Each code can have a location specified by: number, side, vertical, transverse, longitudinal. It also includes type and category for the metadata tags.

Note that not all fields are present for every time series.

Important: Note that not all domains necessarily return unique ids. There could be multiple time series having the same id, within a domain.

Formats

For format=json (the default), the response is an array of metadata objects.

Example JSON metadata response:

For format=ndjson (Newline-Delimited JSON), the response contains one JSON metadata object per line, instead of a single array. This format is useful for streaming large result sets where each line can be processed independently. The content of each JSON object is identical to the regular JSON format.

Example NDJSON response (two lines, each a separate JSON metadata object):

Examples

Retrieve Metadata for a Single Vessel

This request returns a JSON array containing metadata objects for all time series associated with vessel IMO 1234567, using the Raa Labs domain naming convention. The trailing wildcard (*) selects all tags for the vessel.

Retrieve Metadata for Entire Fleet

This request returns metadata for all accessible time series across all vessels, using the Raa Labs domain naming convention. This is achieved by using a wildcard (*) in the IMO position of the expression.

Filtered Metadata Query (e.g., main engine tags)

This request returns metadata for all Main Engine-related time series across all vessels, using the JSMEA domain naming convention. The wildcard in the IMO position selects all vessels, while the remaining expression path filters results to time series under the jsmea_mac engine and machinery naming rule with the MainEngine category.

PreviousMeasurements Endpoint
NextStatistics Endpoint

Last updated

Was this helpful?