> 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 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. {% 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: 2026-09-10" ``` {% 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": "2026-09-10", } 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`, `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. {% hint style="info" %} **Important:** Note that not all domains necessarily return unique ids. There could be multiple time series having the same id, within a domain. {% endhint %} ### Formats {% tabs %} {% tab title="JSON" %} For `format=json` (the default), the response is an array of metadata objects. **Example JSON metadata response**: ```json [ { "id": "IMO1234567/411.1/C101.31-9/meta/qty-temperature/cnt-scavenge.air", "timeSeriesId": "a8009573-5013-4d18-8e63-1ae2f91d6b80", "source": "Aconis", "dataProvider": "Raa Labs", "unitOfMeasure": "°C", "scale": 1.0, "vessel": { "name": "Flying Dutchman", "imo": "1234567" }, "domains": { "id": { "id": "a8009573-5013-4d18-8e63-1ae2f91d6b80" }, "jsmea": { "category": "MainEngine", "content": "ScavAir", "id": "IMO1234567/jsmea_mac/MainEngine/Cylinder9/ScavAir//Temp/", "item": "Temp", "namingRule": "jsmea_mac", "subcategory": "Cylinder9" }, "maker": { "description": "M/E CYL.#9 SCAV. AIR BOX FIRE", "id": "IMO1234567/Aconis/0517", "name": "0517", "rangeHigh": 200.0, "rangeLow": 0.0 }, "raalabs": { "id": "IMO1234567/ME CylinderScavAirTemp_9", "shortName": "ME CylinderScavAirTemp_9" }, "vis-3-8a": { "id": "IMO1234567/411.1/C101.31-9/meta/qty-temperature/cnt-scavenge.air", "metadata": [ { "category": "qty", "type": "temperature" }, { "category": "cnt", "type": "scavenge.air" } ], "primaryItem": [ { "code": "411.1" }, { "code": "C101.31", "number": 9 } ] } } }, { "id": "IMO1234567/511.11/C101.61/S203/meta/qty-mass.flow.rate/cnt-fuel.oil", "timeSeriesId": "a3c8954b-a3fc-4c56-8c82-63972bc9dea5", "source": "Aconis", "dataProvider": "Raa Labs", "unitOfMeasure": "l/h", "scale": 1.0, "vessel": { "name": "Flying Dutchman", "imo": "1234567" }, "domains": { "id": { "id": "a3c8954b-a3fc-4c56-8c82-63972bc9dea5" }, "jsmea": { "category": "GeneratorEngine", "content": "FuelOil", "id": "IMO1234567/jsmea_mac/GeneratorEngine/FuelOilLine/FuelOil//MassFlowRate/", "item": "MassFlowRate", "namingRule": "jsmea_mac", "subcategory": "FuelOilLine" }, "maker": { "description": "G/E F.O FLOW RATE", "id": "IMO1234567/Aconis/FO002", "name": "FO002", "rangeHigh": 120.0, "rangeLow": 0.0 }, "raalabs": { "id": "IMO1234567/AE FuelMassFlow_total", "shortName": "AE FuelMassFlow_total" }, "vis-3-8a": { "id": "IMO1234567/511.11/C101.61/S203/meta/qty-mass.flow.rate/cnt-fuel.oil", "metadata": [ { "category": "qty", "type": "mass.flow.rate" }, { "category": "cnt", "type": "fuel.oil" } ], "primaryItem": [ { "code": "511.11" }, { "code": "C101.61" }, { "code": "S203" } ] } } } ] ``` {% endtab %} {% tab title="NDJSON" %} 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): ```ndjson {"id":"IMO1234567/411.1/C101.31-9/meta/qty-temperature/cnt-scavenge.air","timeSeriesId":"a8009573-5013-4d18-8e63-1ae2f91d6b80","source":"Aconis","dataProvider":"Raa Labs","unitOfMeasure":"°C","scale":1.0,"vessel":{"name":"Flying Dutchman","imo":"1234567"},"domains":{"id":{"id":"a8009573-5013-4d18-8e63-1ae2f91d6b80"},"jsmea":{"category":"MainEngine","content":"ScavAir","id":"IMO1234567/jsmea_mac/MainEngine/Cylinder9/ScavAir//Temp/","item":"Temp","namingRule":"jsmea_mac","subcategory":"Cylinder9"},"maker":{"description":"M/E CYL.#9 SCAV. AIR BOX FIRE","id":"IMO1234567/Aconis/0517","name":"0517","rangeHigh":200.0,"rangeLow":0.0},"raalabs":{"id":"IMO1234567/ME CylinderScavAirTemp_9","shortName":"ME CylinderScavAirTemp_9"}}} {"id":"IMO1234567/511.11/C101.61/S203/meta/qty-mass.flow.rate/cnt-fuel.oil","timeSeriesId":"a3c8954b-a3fc-4c56-8c82-63972bc9dea5","source":"Aconis","dataProvider":"Raa Labs","unitOfMeasure":"l/h","scale":1.0,"vessel":{"name":"Flying Dutchman","imo":"1234567"},"domains":{"id":{"id":"a3c8954b-a3fc-4c56-8c82-63972bc9dea5"},"jsmea":{"category":"GeneratorEngine","content":"FuelOil","id":"IMO1234567/jsmea_mac/GeneratorEngine/FuelOilLine/FuelOil//MassFlowRate/","item":"MassFlowRate","namingRule":"jsmea_mac","subcategory":"FuelOilLine"},"maker":{"description":"G/E F.O FLOW RATE","id":"IMO1234567/Aconis/FO002","name":"FO002","rangeHigh":120.0,"rangeLow":0.0},"raalabs":{"id":"IMO1234567/AE FuelMassFlow_total","shortName":"AE FuelMassFlow_total"}}} ``` {% 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: 2026-09-10" ``` {% 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 {YOUR_TOKEN}", "x-api-version": "2026-09-10", } 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: 2026-09-10" ``` {% 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 {YOUR_TOKEN}", "x-api-version": "2026-09-10", } 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: 2026-09-10" ``` {% 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 {YOUR_TOKEN}", "x-api-version": "2026-09-10", } 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.