> For the complete documentation index, see [llms.txt](https://docs.raalabs.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.raalabs.io/docs/api-endpoints/metadata-endpoint.md). # 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. {% tabs %} {% tab title="cURL" %} {% code lineNumbers="true" %} ```bash curl "https://portal.raalabs.io/{ENVIRONMENT}/metadata/{domain}/{expression}" \ -H "Authorization: Bearer $TOKEN" \ -H "x-api-version: 2025-10-31" ``` {% endcode %} {% endtab %} {% tab title="Python" %} {% code lineNumbers="true" %} ```python 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": "2025-10-31", } response = requests.get(url, headers=headers) ``` {% endcode %} {% endtab %} {% endtabs %} ## 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 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 in JSON format. The response structure is a **JSON object**, 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. Each individual metadata object contains 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. {% hint style="info" %} **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). {% endhint %} ### Formats {% tabs %} {% tab title="JSON" %} Example JSON metadata response: ```json { "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.) {% endtab %} {% endtabs %} ## Examples ### **Retrieve Metadata for a Single Vessel** {% tabs %} {% tab title="cURL" %} {% code lineNumbers="true" %} ```bash curl "https://portal.raalabs.io/{ENVIRONMENT}/metadata/raalabs/IMO1234567/*" \ -H "Authorization: Bearer YOUR_TOKEN" \ -H "x-api-version: 2025-10-31" ``` {% endcode %} {% endtab %} {% tab title="Python" %} {% code lineNumbers="true" %} ```python import requests TOKEN = "YOUR_TOKEN" ENVIRONMENT = "YOUR_ENVIRONMENT" url = f"https://portal.raalabs.io/{ENVIRONMENT}/metadata/raalabs/IMO1234567/*" headers = { "Authorization": f"Bearer {TOKEN}", "x-api-version": "2025-10-31", } response = requests.get(url, headers=headers) ``` {% endcode %} {% endtab %} {% endtabs %} 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** {% tabs %} {% tab title="cURL" %} {% code lineNumbers="true" %} ```bash curl "https://portal.raalabs.io/{ENVIRONMENT}/metadata/raalabs/*" \ -H "Authorization: Bearer YOUR_TOKEN" \ -H "x-api-version: 2025-10-31" ``` {% endcode %} {% endtab %} {% tab title="Python" %} {% code lineNumbers="true" %} ```python import requests TOKEN = "YOUR_TOKEN" ENVIRONMENT = "YOUR_ENVIRONMENT" url = f"https://portal.raalabs.io/{ENVIRONMENT}/metadata/raalabs/*" headers = { "Authorization": f"Bearer {TOKEN}", "x-api-version": "2025-10-31", } response = requests.get(url, headers=headers) ``` {% endcode %} {% endtab %} {% endtabs %} 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)** {% tabs %} {% tab title="cURL" %} {% code lineNumbers="true" %} ```bash curl "https://portal.raalabs.io/{ENVIRONMENT}/metadata/jsmea/*/jsmea_mac/MainEngine/*" \ -H "Authorization: Bearer YOUR_TOKEN" \ -H "x-api-version: 2025-10-31" ``` {% endcode %} {% endtab %} {% tab title="Python" %} {% code lineNumbers="true" %} ```python import requests TOKEN = "YOUR_TOKEN" ENVIRONMENT = "YOUR_ENVIRONMENT" url = f"https://portal.raalabs.io/{ENVIRONMENT}/metadata/jsmea/*/jsmea_mac/MainEngine/*" headers = { "Authorization": f"Bearer {TOKEN}", "x-api-version": "2025-10-31", } response = requests.get(url, headers=headers) ``` {% endcode %} {% endtab %} {% endtabs %} 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.