> 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/2025-10-31/docs/supported-domains.md). # Supported Domains Raa Labs supports multiple **domains** for organizing and querying time series data. A domain defines how a time series is named and structured. Knowing the domains helps you form expressions for queries. The current supported domains include: | Domain | Description | Example DomainId | | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- | | **id** | The raw time series UUID. This is a unique identifier assigned by Raa Labs for each signal. Use this for a direct lookup if you know the UUID. | `62e23903-9db5-43cc-949d-78452ffb81bc` | | **jsmea** | JSMEA (Japan Ship Machinery and Equipment Association) naming standard, based on ISO 19848 for ship sensor data. This is a hierarchical naming scheme with multiple levels (e.g., system, subsystem, component, parameter). | `IMO1234567/jsmea_mac/MainEngine/DrivingShaft/Output//Power/` | | **raalabs** | Raa Labs flat tag schema. A simpler, flattened naming convention that usually includes just the IMO number and a short descriptive tag. | `IMO1234567/ME ShaftPower` | | **parameters** | Parameter grouping schema. It includes the IMO number, a parameter group name, and a short name. This groups related signals under a category. | `IMO1234567/ME Power/ME ShaftPower` | | **maker** | The name given to a tag by the maker of the machinery or equipment. Includes the maker name and a tag name. | `IMO1234567/Maker/12345` | | **vis-3-8a** | The VIS (Vessel Information Structures) naming convention from DNV is a standardized way to uniquely identify vessel functions and onboard equipment. It uses a hierarchical structure based on GMOD (Generic Product Model). | `IMO1234567/913/S130.1-1/S121/sec/406i/H233/meta/qty-power` | {% hint style="info" %} **Note:** For the `jsmea` and `vis-3-8a` domains, some signals may not yet have been mapped. If an expected signal is unavailable in these domains, use the `raalabs` domain. For specific requests, please contact us at . {% endhint %} ## Querying Within Each Domain This section describes the query expression structure for each supported domain. All domains support wildcard queries. Wildcards (`*`) can be used to match partial names or hierarchy levels, allowing you to retrieve data without specifying the full expression. ### The ID Domain **Query Expression Format:** `{timeseries_id}` In this domain, the query expression consists solely of the UUID of the time series. * `62e23903-9db5-43cc-949d-78452ffb81bc` Retrieves the time series with this exact UUID. * `*` Retrieves all time series from *all vessels* ### The JSMEA Domain **Query Expression Format:** `{imo_number}/{naming_rule}/{category}/{sub_category}/{content}/{position}/{item}/{modifier}` For a comprehensive explanation of the JSMEA naming scheme, refer to the [Description of Local ID Definitions (JSMEA Codebook)](https://www.jsmea.or.jp/ssap/topics/jsmea_codebook.html). In a hierarchical domain such as **`jsmea`**, wildcards may be applied at multiple levels: * `IMO1234567/*/*/*/*/*/Power/` Retrieves all time series under vessel IMO1234567 whose final component is "Power" (regardless of which subsystem or component). * `IMO1234567/jsmea_mac/MainEngine/*` Retrieves all Main Engine-related time series for vessel IMO1234567 (wildcard at the level below MainEngine to get everything under it). * `IMO1234567/jsmea_mac/MainEngine/Fuel*` Retrieves all Main Engine with some kind of fuel component related time series for vessel IMO1234567 (wildcard at the level below MainEngine to get everything under it). ### The Raalabs Domain **Query Expression Format:** `{imo_number}/{tag_name}` In a flat domain like **`raalabs`**, you can query multiple vessels or tags: * `*/ME ShaftPower` Retrieves the **Main Engine ShaftPower** measurements for *all vessels* ( `*` in place of the IMO number matches every vessel). * `raalabs/IMO1000002/ME* Shaft*` Retrieves all tags that start with ME and have the word Shaft in them. ### The Parameters Domain **Query Expression Format:** `{imo_number}/{parameter_group_name}` A parameter represents a logical grouping of related time series, from one or more vessels. This enables analysis of specific operational topics (e.g., fuel consumption), either within a single vessel or across multiple vessels. * `parameters/IMO1000001/AE Fuel Oil Consumption` Retrieves all time series in the AE Fuel Oil Consumption parameter group, for vessel IMO1000001. * `parameters/{IMO1000001, IMO1000002}/AE Fuel Oil Consumption` Retrieves the same parameter group for multiple vessels. ### The Maker Domain **Query Expression Format:** `{imo_number}/{maker_name}{maker_tag_name}` * `IMO1234567/Enamor/*` Retrieves all time series for vessel IMO1234567 originating from the Enamor system. * `IMO1234567/Enamor/Water Depth` Retrieves the water depth time series for vessel IMO1234567 originating from the Enamor system. ### The VIS-3-8a Domain **Query Expression Format:** `{imo_number}/{primary_item_vis_path}/sec/{secondary_item_vis_path}/meta/{metadata}` The **`vis-3-8a`** domain utilizes the hierarchical GMOD (Generic Product Model) framework to define VIS-paths for vessel items. DNV provides a comprehensive [learning tool](https://vista.dnv.com/learning-tool) for generating VIS-paths and metadata, along with detailed [naming rule documentation](https://docs.vista.dnv.com/docs/standards/dnv-naming-rule). Wildcards (`*`) can be applied at multiple levels within VIS-paths, as well as at the metadata type and IMO number specifications: * `*` Retrieves all time series from *all vessels* * `IMO1234567/411.1` Retrieves all time series under vessel IMO1234567 with primary path root 411.1 ("Propulsion Driver") and arbitrary amounts of descendants in the VIS-path. The latter means that specifying {primary\_item\_vis\_path} = 411.1 is equal to specifying {primary\_item\_vis\_path} = 411.1/\* * `IMO1234567/400a` Retrieves all time series under vessel IMO1234567 with primary path root being a code that lies within the group 400a ("Propulsion and steering arrangements") in the hierarchy tree, and arbitrary amounts of descendants in the VIS-path. * `IMO1234567/*/S130-2AMOS` Retrieves all time series for vessel IMO1234567 with arbitrary primary path root and includes S130 (code for "fan unit") anywhere in the VIS-path of their primary item, except root position. Note that the code we require can be both exactly S130 or a code that is under it in the hierarchy, e.g. S130.2. In addition this code is required to have Location 2AMOS. * `*/*/sec/*/H233` Retrieves all time series from *all vessels* with secondary item VIS-path including H233, and wildcard root. * `IMO1234567/meta/qty-temperature` Retrieves all time series for vessel IMO1234567 which have the metadata element "qty-temperature". * `IMO1234567/meta/qty-*` Retrieves all time series for vessel IMO1234567 which have the metadata category "qty" and any metadata type. #### Notes * Wildcards in primary or secondary VIS-paths match zero or more path segments, except at the root position where they match one or more segments to ensure a valid root is specified * You can combine vessel, path, and meta wildcards: `*/400a/*/C663/sec/*/meta/qty-*` * Use `{IMO1234567, IMO7654321}/*` to query multiple specific vessels #### Verbose DomainIds Add the query parameter `?verbose=true` to include human-readable names for the corresponding VIS path elements in vis-3-8a domainIds. This optional parameter is disabled by default and is intended solely to improve readability of the output. Including verbose in the query expression will not affect the resolver behavior. **Example (verbose=true):** `IMO1234567/411.1-2P/C101.31-4/~propulsion.engine.2P/~cylinder.4/meta/qty-pressure` In this example, the verbose segments (prefixed with \~) show that the time series represents the pressure of cylinder 4 in propulsion engine 2 on the port side. The verbose parameter is available across all endpoints and domains, but its use outside the vis-3-8a domain is only useful when querying metadata. {% hint style="info" %} **Note:** Wildcards are currently under development, not all functionality is available in all domains. {% endhint %} ## Finding Domain Mappings If you are unsure how a time series ID appears in different domains, you can use the metadata endpoint on the `id` domain to see its mappings. For example, you can fetch all metadata using the raw `id` domain and look at the `mapsTo` field in the response. The `mapsTo` object will show equivalent identifiers in other domains for each time series. For instance, a metadata query like `GET https://portal.raalabs.io/{ENVIRONMENT}/metadata/id/*` might return: ```json { "46fd4739-ad03-43c3-b027-7db0d0b093ec": { "name": "12153", "description": "ENGINE ROOM TEMP.", "source": "Aconis", "scale": 1.0, "vesselName": "Happy Wanderer", "vesselImo": "1000005", "uom": "°C", "timeSeriesId": "46fd4739-ad03-43c3-b027-7db0d0b093ec", "rangeLow": -40.0, "rangeHigh": 60.0, "mapsTo": { "jsmea": "IMO1000005/jsmea_mac/EngineRoomAmbience/RoomSpace/AmbientAir//Temp/", "maker": "IMO1000005/Aconis/12153", "raalabs": "IMO1000005/EngineRoom AmbientAirTemp", "vis-3-8a": "IMO1000005/406i/H233/meta/cnt-ambient.air/qty-temperature" } } } ``` ## Returning DomainIds in Another Domain The `/measurements` and `/statistics` endpoints accept an `output_domain` query parameter. It sets the domain that the results are named in, independently of the domain that was queried. This lets you query in whichever naming scheme is most convenient, and get the results labelled in the scheme of your choice. Without the parameter, results are named in the domain that was queried. For example, this query selects a time series by its flat `raalabs` tag name, but asks for JSMEA names in the response: ```sh curl -X GET "https://portal.raalabs.io/{ENVIRONMENT}/measurements/raalabs/IMO1234567/ME%20ShaftPower?last=1hour&output_domain=jsmea" \ -H "Authorization: Bearer YOUR_TOKEN" \ -H "x-api-version: 2025-10-31" ``` It returns the same measurements as the query without `output_domain`, but each `domainId` is the JSMEA name of the time series instead of the `raalabs` one: ```json [ { "timestamp": "2025-06-12T07:42:03.361000Z", "id": "IMO1234567/jsmea_mac/MainEngine/DrivingShaft/Output//Power/", "value": 12351.4 } ] ``` {% hint style="info" %} **Note:** A time series that has no name in the requested output domain is left out of the response, so a query can return fewer time series with `output_domain` set than without it. The `id` domain is defined for every time series, so `output_domain=id` never leaves anything out. {% endhint %}