Metadata endpoint

The Metadata endpoint provides detailed metadata about time series tags. This includes information such as the human-readable name of the signal, description, units of measure, data source, scaling factor, valid range, and mappings to other naming domains. Use this endpoint to understand what a particular time series represents.

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

Note: The metadata endpoint currently supports only JSON output (no NDJSON or Parquet). Typically, you will query metadata using a broad expression (often with wildcards) to retrieve information on multiple tags at once.

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 metadata query (e.g. jsmea, raalabs, id).
expression	The query expression to filter which tags' metadata to retrieve. This can be a specific path or include wildcards (*) to get multiple tags.

Response

If the query is valid, the response will include metadata for all matching time series in JSON format. The response structure is a JSON object (dictionary) where each key is a time series ID (the domain id, according to the chosen domain) and the value is an object containing that tag’s metadata fields.

Important: Note that not all domains necessarily return unique domain ids. There could be multiple time series that map to the same domain id. In such a case the metadata endpoint returns metadata objects for different time series with the same domain id. This requires extra considerations when parsing the response with with json libraries (the standard is that duplicate object keys are not allowed in json, most software libraries follow this standard).

JSON format

Each metadata object may include the following fields (keys can vary depending on the data source):

• name – Human-friendly name of the signal.

• description – Detailed description of the measurement.

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

• scale – Scaling factor applied to the raw data (if any).

• uom – Unit of measure (abbreviation) for the values (e.g., deg for degrees, kW for kilowatts).

• mapsTo – Mappings of this tag in other domains (if available). This is an object where keys are domain names and values are the corresponding tag identifiers in those domains (e.g., mapping a JSMEA standard name to a Raa Labs short tag).

• rangeHigh / rangeLow – High and low range values (if defined) that the measurements are expected to lie within.

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

• vesselImo – The IMO number of the vessel this data is associated with.

• vesselName – The name of the vessel.

Example JSON metadata response:

{
  "IMO1000003/jsmea_nav/PositioningSystem/GPS///Longitude/": {
    "name": "Longitude",
    "description": "SHIP POSITION (LONGITUDE)",
    "source": "FurunoVDR",
    "scale": 1.0,
    "uom": "deg",
    "mapsTo": {
        "jsmea": "IMO1000003/jsmea_nav/PositioningSystem/GPS///Longitude/",
        "raalabs": "IMO1000003/GPS_LONG"
    },
    "rangeHigh": 180.0,
    "rangeLow": -180.0,
    "timeSeriesId": "11000001-0000-0000-0000-000000000000",
    "vesselImo": "1000003",
    "vesselName": "Flying Dutchman"
  },
  "IMO1000003/jsmea_nav/PositioningSystem/GPS///Latitude/": {
    "name": "Latitude",
    "description": "SHIP POSITION (LATITUDE)",
    "source": "FurunoVDR",
    "scale": 1.0,
    "uom": "deg",
    "mapsTo": {
        "jsmea": "IMO1000003/jsmea_nav/PositioningSystem/GPS///Latitude/",
        "raalabs": "IMO1000003/GPS_LAT"
    },
    "rangeHigh": 90.0,
    "rangeLow": -90.0,
    "timeSeriesId": "11000001-0000-0000-0000-000000000001",
    "vesselImo": "1000003",
    "vesselName": "Flying Dutchman"
  }
}

(This example shows two metadata entries for Longitude and Latitude tags of vessel Flying Dutchman. It includes mappings in both JSMEA and Raa Labs domains for each tag.)

Note: NDJSON and Parquet formats are not supported for the metadata endpoint at this time.

Examples

Retrieve Metadata for a Single Vessel

Get all available metadata for vessel IMO 1234567, using the Raa Labs domain (which will list Raa Labs tags for that vessel):

curl "https://prism.raalabs.io/{ENVIRONMENT}/metadata/raalabs/IMO1234567/*" \
  -H "Authorization: Bearer $TOKEN"

This returns a JSON object containing metadata for every tag of the vessel with IMO 1234567 (in the Raa Labs naming convention). The wildcard * ensures all tags for that vessel are included.

Retrieve Metadata for Entire Fleet

Get all metadata for all vessels (the entire fleet) in the Raa Labs domain:

curl "https://prism.raalabs.io/{ENVIRONMENT}/metadata/raalabs/*" \
  -H "Authorization: Bearer $TOKEN"

By using raalabs/* with no specific IMO, this will return metadata for every time series across all vessels that you have access to, using the flat tag names.

Filtered Metadata Query (e.g., Main Engine tags)

Retrieve metadata for all Main Engine related tags across the fleet in the JSMEA domain:

curl "https://prism.raalabs.io/{ENVIRONMENT}/metadata/jsmea/*/jsmea_mac/MainEngine/*" \
  -H "Authorization: Bearer $TOKEN"

In this query, jsmea/*/jsmea_mac/MainEngine/* means: for any vessel (* in IMO slot), under the JSMEA machinery domain (jsmea_mac), get anything under MainEngine. This will return metadata for all tags that are part of the main engine systems for all vessels, with their detailed descriptions, units, etc.