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" \
  -H "x-api-version: 2025-10-31"

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
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. In many domains, the expression begins with the vessel’s IMO number.

Query Parameters

• Verbose Parameter:

  • verbose (boolean): Some domains offer more human-readable, verbose domainIds. This parameter allows to toggle on and off verbose domainIds. 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 in JSON format. The response structure is a JSON object (dictionary) where each key is a time series ID (the domainId, 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 domainIds. There could be multiple time series that map to the same domainId. In such a case the metadata endpoint returns metadata objects for different time series with the same domainId. This requires extra considerations when parsing the response 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

curl "https://prism.raalabs.io/{ENVIRONMENT}/metadata/raalabs/IMO1234567/*" \
  -H "Authorization: Bearer {YOUR_TOKEN}" \
  -H "x-api-version: 2025-10-31"

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

curl "https://prism.raalabs.io/{ENVIRONMENT}/metadata/raalabs/*" \
  -H "Authorization: Bearer {YOUR_TOKEN}" \
  -H "x-api-version: 2025-10-31"

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)

curl "https://prism.raalabs.io/{ENVIRONMENT}/metadata/jsmea/*/jsmea_mac/MainEngine/*" \
  -H "Authorization: Bearer {YOUR_TOKEN}" \
  -H "x-api-version: 2025-10-31"

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.