--- updatedAt: 2026-08-18T07:19:43.000Z agentTools: projectIndex: https://docs.toqua.ai/llms.txt --- # Electrical operating-mode distribution per vessel (Experimental) Experimental — this endpoint may change or be removed without notice. Return how each vessel supplied its electrical load over eligible time. # OpenAPI definition ```json { "openapi": "3.1.0", "info": { "title": "Toqua API", "contact": { "name": "Toqua", "url": "https://toqua.ai/", "email": "admin@toqua.ai" }, "version": "0.26" }, "servers": [ { "url": "https://api.toqua.ai", "description": "Toqua API" } ], "paths": { "/electrical/operating-modes": { "get": { "tags": [ "Electrical Systems" ], "summary": "Electrical operating-mode distribution per vessel (Experimental)", "description": "Experimental — this endpoint may change or be removed without notice. Return how each vessel supplied its electrical load over eligible time.", "operationId": "get_electrical_operating_modes", "security": [ { "APIKeyHeader": [] }, { "HTTPBearer": [] } ], "parameters": [ { "name": "start_datetime", "in": "query", "required": true, "schema": { "type": "string", "format": "date-time", "description": "Inclusive lower bound of the period (ISO 8601, timezone-aware). Required; the endpoint never defaults to all time.", "title": "Start Datetime" }, "description": "Inclusive lower bound of the period (ISO 8601, timezone-aware). Required; the endpoint never defaults to all time." }, { "name": "end_datetime", "in": "query", "required": true, "schema": { "type": "string", "format": "date-time", "description": "Inclusive upper bound of the period (ISO 8601, timezone-aware). Required; the endpoint never defaults to all time.", "title": "End Datetime" }, "description": "Inclusive upper bound of the period (ISO 8601, timezone-aware). Required; the endpoint never defaults to all time." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetOperatingModesResponse" } } } }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } } }, "components": { "schemas": { "DataProfile": { "properties": { "has_sensor_data": { "type": "boolean", "title": "Sensor Data Reported", "description": "Whether the vessel reported any sensor data at all over the period. These views are computed from sensor data only, so a vessel reporting noon reports exclusively has no figures here rather than partial ones, and every other flag below reads false for want of data rather than because a channel is missing." }, "shaft_generator_power": { "type": "boolean", "title": "Shaft Generator Power Reported", "description": "Whether any shaft generator power reading was present. Without it neither utilization nor the engagement profile can be computed." }, "turbo_generator_power": { "type": "boolean", "title": "Turbo Generator Power Reported", "description": "Whether any turbo generator power reading was present. Without it the shaft-plus-turbo-generator mode cannot be distinguished from shaft-only." }, "me_rpm": { "type": "boolean", "title": "Engine Speed Reported", "description": "Whether any main engine speed reading was present. Required for the `cut_in_rpm` basis and for the engagement profile's RPM bins." }, "sog": { "type": "boolean", "title": "Speed Over Ground Reported", "description": "Whether any speed-over-ground reading was present. Required for the `at_sea` basis, which is what vessels without a power curve fall back to." }, "aux_metering": { "type": "string", "enum": [ "per_engine_power", "per_engine_fuel", "totals", "none" ], "title": "Auxiliary Metering Level", "description": "Best auxiliary instrumentation available over the period: `per_engine_power` (individual engine power channels — the only level that yields an exact running count), `per_engine_fuel` (individual engine fuel), `totals` (fleet totals only, so a running count collapses into the auxiliary-count-unknown mode), or `none` (no auxiliary channel at all, so whether an auxiliary engine was running cannot be established and that time is reported as `no_data_percentage`)." }, "has_shaft_generator": { "type": "boolean", "title": "Configured With A Shaft Generator", "description": "Vessel configuration. When false the vessel has no shaft-generator figures of its own and is only included in the operating-mode comparison." }, "cut_in_configured": { "type": "boolean", "title": "Cut-in RPM Configured", "description": "Whether a shaft generator power curve is configured, which is where the cut-in RPM comes from. When false the vessel falls back to the `at_sea` basis, a wider and less accurate window." }, "fixed_pitch_propeller": { "type": "boolean", "title": "Fixed-pitch Propeller", "description": "Vessel configuration. The engagement profile plots engaged share against engine speed, which is only meaningful for a fixed-pitch propeller; controllable-pitch vessels hold a near-constant engine speed." }, "shaft_generator_readings_without_config": { "type": "boolean", "title": "Shaft Generator Readings Without Configuration", "description": "True when shaft generator power was reported for a vessel that is not configured with a shaft generator — the two disagree, so one of them is wrong. Until the configuration is corrected the vessel is excluded from every shaft-generator figure while its readings still drive its operating-mode split, which makes those two views contradict each other." } }, "type": "object", "required": [ "has_sensor_data", "shaft_generator_power", "turbo_generator_power", "me_rpm", "sog", "aux_metering", "has_shaft_generator", "cut_in_configured", "fixed_pitch_propeller", "shaft_generator_readings_without_config" ], "title": "DataProfile", "description": "Which inputs a vessel actually supplied over the period, and how it is configured.\n\nEvery degraded or missing figure elsewhere in these responses traces back to a\nfield here, so this is the one place to look when a metric is absent, null, or\nless accurate than expected. Signal flags describe the requested period only: a\nvessel that stopped reporting a channel last month will show it as absent for a\nwindow that covers this month." }, "GetOperatingModesResponse": { "properties": { "vessels": { "items": { "$ref": "#/components/schemas/OperatingModeVessel" }, "type": "array", "title": "Vessels", "description": "One entry per vessel in the fleet. Vessels with no classified time at all sort last, whatever their score. The rest rank on (`sg_tg` + `sg_only`) descending — time the shaft generator carried the load with no auxiliary engine running — then `sg_aux` ascending, then auxiliary time weighted by engine count (`aux_1` + 2x`aux_2` + 3x`aux_3plus` + `aux_unknown`) ascending, so heavier auxiliary use ranks lower. Every share is first scaled by the classified fraction (`1 - no_data_percentage/100`) onto *eligible* time, the same denominator the bars use, so a vessel observed for only a sliver of the period cannot outrank a fully metered one. Non-shaft-generator vessels are included so their auxiliary-engine usage can be compared." } }, "type": "object", "required": [ "vessels" ], "title": "GetOperatingModesResponse", "description": "Electrical operating-mode distribution for every vessel in the fleet." }, "HTTPValidationError": { "properties": { "detail": { "items": { "$ref": "#/components/schemas/ValidationError" }, "type": "array", "title": "Detail" } }, "type": "object", "title": "HTTPValidationError" }, "OperatingModeShares": { "properties": { "sg_tg": { "type": "number", "title": "Shaft + Turbo Generator (%)", "description": "Shaft generator engaged, turbo generator engaged, no auxiliary engine running." }, "sg_only": { "type": "number", "title": "Shaft Generator Only (%)", "description": "Shaft generator engaged, no turbo generator, no auxiliary engine running." }, "sg_aux": { "type": "number", "title": "Shaft Generator + Auxiliary (%)", "description": "Shaft generator engaged alongside at least one running auxiliary engine." }, "aux_1": { "type": "number", "title": "1 Auxiliary Engine (%)", "description": "Shaft generator off, exactly one auxiliary engine running." }, "aux_2": { "type": "number", "title": "2 Auxiliary Engines (%)", "description": "Shaft generator off, exactly two auxiliary engines running." }, "aux_3plus": { "type": "number", "title": "3+ Auxiliary Engines (%)", "description": "Shaft generator off, three or more auxiliary engines running." }, "aux_unknown": { "type": "number", "title": "Auxiliary, Count Unknown (%)", "description": "Shaft generator off and auxiliary power drawn, but the number of running engines cannot be resolved (only fleet totals are metered). Zero when per-engine data exists." }, "none": { "type": "number", "title": "No Generation (%)", "description": "Generation was metered but nothing was running: every reported channel sat at or below its threshold. This requires the auxiliary side to have been *observable* — a sample only lands here if at least one auxiliary channel (per-engine power, per-engine fuel, or a total) reported, so that 'no auxiliary running' is something measured rather than assumed. Samples that fail that test are excluded from the split and reported as `no_data_percentage`, which makes a non-zero share here a genuine finding: a real gap in supply, or a metering fault." } }, "type": "object", "required": [ "sg_tg", "sg_only", "sg_aux", "aux_1", "aux_2", "aux_3plus", "aux_unknown", "none" ], "title": "OperatingModeShares", "description": "Share of classified time a vessel spent in each electrical supply mode.\n\nValues are percentages (0-100) and sum to 100 across the modes. Modes are\nmutually exclusive and assigned per sample in priority order. The split covers\nonly the time that could be classified: samples with no generation readings at\nall are excluded, and reported separately as `no_data_percentage`." }, "OperatingModeVessel": { "properties": { "imo_number": { "type": "string", "title": "IMO Number", "description": "IMO number of the vessel." }, "name": { "type": "string", "title": "Name", "description": "Vessel name." }, "has_shaft_generator": { "type": "boolean", "title": "Has Shaft Generator", "description": "Whether the vessel is fitted with a shaft generator." }, "basis": { "type": "string", "enum": [ "cut_in_rpm", "at_sea" ], "title": "Basis", "description": "Which definition of *eligible time* the vessel's figures rest on. `cut_in_rpm`: time with the main engine at or above the vessel's cut-in RPM, taken from its configured shaft generator power curve. This is the more accurate basis, because it counts only the time the shaft generator could actually have been engaged. `at_sea`: time under way at more than 5 knots over ground, used when no power curve is configured and there is therefore no cut-in RPM to measure against. It is a wider window than `cut_in_rpm` — it includes time at sea below the cut-in, when engaging was never possible — so utilization on this basis reads lower than it would with a curve configured. Configure a power curve to move a vessel onto the `cut_in_rpm` basis." }, "data_profile": { "$ref": "#/components/schemas/DataProfile", "title": "Data Profile", "description": "Which inputs this vessel supplied over the period and how it is configured. Explains any null, zero or degraded figure in this entry." }, "eligible_hours": { "type": "number", "title": "Eligible Hours", "description": "Hours the vessel was eligible over the period, on the vessel's `basis` (above the cut-in RPM, or at sea)." }, "classified_hours": { "type": "number", "title": "Classified Hours", "description": "Hours of eligible time that could be assigned a mode: either something was seen generating (shaft or turbo generator above its threshold), or the auxiliary side was metered, so that an idle result is measured rather than assumed. The mode shares are a split of this time, not of `eligible_hours`." }, "no_data_percentage": { "type": "number", "title": "No Data (%)", "description": "Share (0-100) of eligible time that could not be assigned a mode: nothing was seen generating *and* no auxiliary channel reported, so whether anything was running is unknown. Excluded from the mode split, this is a coverage figure — the higher it is, the less of the vessel's eligible time the shares describe. Vessels with no auxiliary metering at all (`aux_count_source` = `unmetered`) concentrate here whenever their shaft generator is not running." }, "aux_count_source": { "type": "string", "enum": [ "per_engine_power", "per_engine_fuel", "totals_only", "mixed", "unmetered" ], "title": "Auxiliary Count Source", "description": "How the number of running auxiliary engines was resolved, summarised across the vessel's samples. Each sample is resolved on its own channels — `per_engine_power` (per-engine power channels present), else `per_engine_fuel` (per-engine fuel channels present), else `totals_only` (only fleet totals metered, so its engine count collapses into the auxiliary-count-unknown mode). This field reports the single source when all samples agree, or `mixed` when the vessel's samples use more than one. `unmetered` means the vessel reports no auxiliary channel at all, so its auxiliary usage cannot be assessed — expect a high `no_data_percentage`." }, "modes": { "$ref": "#/components/schemas/OperatingModeShares", "title": "Modes", "description": "Share (0-100) of eligible time spent in each electrical supply mode." } }, "type": "object", "required": [ "imo_number", "name", "has_shaft_generator", "basis", "data_profile", "eligible_hours", "classified_hours", "no_data_percentage", "aux_count_source", "modes" ], "title": "OperatingModeVessel", "description": "Operating-mode distribution for one vessel over the requested period." }, "ValidationError": { "properties": { "loc": { "items": { "anyOf": [ { "type": "string" }, { "type": "integer" } ] }, "type": "array", "title": "Location" }, "msg": { "type": "string", "title": "Message" }, "type": { "type": "string", "title": "Error Type" } }, "type": "object", "required": [ "loc", "msg", "type" ], "title": "ValidationError" } }, "securitySchemes": { "APIKeyHeader": { "type": "apiKey", "in": "header", "name": "X-API-Key" }, "HTTPBearer": { "type": "http", "scheme": "bearer" } } }, "tags": [ { "name": "Electrical Systems", "description": "**Experimental — these endpoints may change or be removed without notice.** They are published so callers can build against them early; treat the shapes and field semantics as provisional until this notice is removed.\n\nFleet-scoped views of how vessels supply their electrical load: shaft generator utilization, its engagement profile against engine speed, and the distribution of electrical operating modes. Metrics are computed at full sensor resolution over an explicit period.\n\n### What each figure needs\n\nThese endpoints degrade rather than fail: a vessel missing an input still appears, with the affected figures widened, emptied or reported as unmeasured. Every vessel entry carries a `data_profile` saying which inputs it supplied and how it is configured, so any surprising value can be traced to a cause.\n\n| Input | Missing it means |\n| --- | --- |\n| Sensor data | Nothing at all: these views read sensor data only, so a vessel reporting noon reports exclusively has no figures rather than partial ones. `data_profile.has_sensor_data` is false. |\n| Shaft generator power | No utilization and no engagement profile: whether the generator was engaged is unknown. |\n| Shaft generator power curve (config) | No cut-in RPM, so utilization falls back to the wider `at_sea` basis and reads lower. `cut_in_rpm` is null and `basis` is `at_sea`. |\n| Engine speed (RPM) | No `cut_in_rpm` basis and no engagement profile bins; eligibility must come from speed over ground instead. |\n| Speed over ground | No `at_sea` basis, so a vessel without a power curve has no eligible time at all. |\n| Any auxiliary channel | Whether an auxiliary engine was running cannot be established, so that time is excluded from the operating-mode split and reported as `no_data_percentage`; `aux_count_source` is `unmetered`. |\n| Per-engine auxiliary channels | The number of running engines collapses into the single `aux_unknown` mode instead of `aux_1` / `aux_2` / `aux_3plus`. |\n| Turbo generator power | Shaft-plus-turbo-generator time cannot be separated from shaft-only, so `sg_tg` reads zero. |\n| Fixed-pitch propeller (config) | The engagement profile is not meaningful for controllable-pitch vessels, which hold a near-constant engine speed. |\n\nA vessel reporting shaft generator power while *not* configured with a shaft generator is a configuration error, flagged as `shaft_generator_readings_without_config`: it is excluded from the shaft-generator figures while its readings still drive its operating-mode split, so those two views will disagree until the configuration is fixed." } ], "externalDocs": { "description": "API Documentation", "url": "https://docs.toqua.ai" } } ```