{ "openapi": "3.1.0", "info": { "title": "Wia REST API reference", "description": "
A REST API to interact with Wia platform to enable external applications to analyse energy consumption and to automate internal operations relating to the capturing and grouping of energy consumption.

To get started, please ensure you have the correct permissions and appropriate key. If you have not been provided a key, please contact your representative.

The API is organised around REST. Our API has predictable resource-oriented URLs, accepts form-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.", "version": "v1" }, "components": { "securitySchemes": { "ApplicationKey": { "type": "http", "description": "An Application key for read only access", "scheme": "bearer", "bearerFormat": "Bearer" } }, "parameters": { "id": { "name": "id", "description": "Id of Object", "in": "path", "required": true, "schema": { "type": "string" } }, "spaceId": { "name": "space.id", "description": "Id of Space", "in": "query", "schema": { "type": "string" } }, "spaceIdNotRequired": { "name": "space.id", "description": "Id of Space", "in": "query", "required": false, "schema": { "type": "string" } }, "organisationId": { "name": "organisation.id", "description": "Id of Organisation", "in": "query", "required": false, "schema": { "type": "string" } }, "deviceId": { "name": "device.id", "description": "Id of Device", "in": "query", "required": false, "schema": { "type": "string" } }, "gatewayId": { "name": "gateway.id", "description": "Id of Gateway", "in": "query", "required": false, "schema": { "type": "string" } }, "flowId": { "name": "flow.id", "description": "Id of Flow", "in": "query", "required": false, "schema": { "type": "string" } }, "productId": { "name": "product.id", "description": "Id of Product", "in": "query", "required": false, "schema": { "type": "string" } }, "alertRuleId": { "name": "alertRule.id", "description": "Id of Alert Rule", "in": "query", "required": false, "schema": { "type": "string" } }, "placeId": { "name": "place.id", "description": "Id of Place", "in": "query", "required": false, "schema": { "type": "string" } }, "batchNumber": { "name": "batchNumber", "description": "batchNumber of Device", "in": "query", "required": false, "schema": { "type": "string" } }, "resourceType": { "name": "resourceType", "description": "Type of Resource", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "device", "place", "space" ] } }, "limit": { "name": "limit", "in": "query", "description": "Max number of rows to return", "required": false, "schema": { "type": "integer", "format": "int32", "example": 20 } }, "page": { "name": "page", "in": "query", "description": "Section of rows to return e.g. 0, 1 or 2", "required": false, "schema": { "type": "integer", "format": "int32" } }, "sort": { "name": "sort", "in": "query", "description": "Sort by Ascending or Descending order Default: DESC", "required": false, "schema": { "type": "string", "enum": [ "ASC", "DESC" ] } }, "order": { "name": "order", "in": "query", "description": "Order by column e.g. id", "required": false, "schema": { "type": "string" } }, "since": { "name": "since", "in": "query", "description": "Retrieve from this timestamp onwards", "required": false, "schema": { "oneOf": [ { "type": "string", "format": "date-time", "example": "2022-01-01T00:00:00Z" }, { "type": "integer", "example": 1640995200000 } ] } }, "until": { "name": "until", "in": "query", "description": "Retrieve until this timestamp", "required": false, "schema": { "oneOf": [ { "type": "string", "format": "date-time", "example": "2022-01-01T00:00:00Z" }, { "type": "integer", "example": 1640995200000 } ] } }, "continuationToken": { "name": "continuationToken", "in": "query", "description": "The continuation token to retrieve the next set of data.", "required": false, "schema": { "type": "string" } } }, "schemas": { "Alert": { "type": "object", "properties": { "id": { "type": "string", "example": "alt_abcdef12345678" }, "event": { "$ref": "#/components/schemas/Event" }, "note": { "type": "string", "example": "A window was opened" }, "resolvedAt": { "type": "string", "format": "date-time", "example": 1642759067045 }, "acknowledgedAt": { "type": "string", "format": "date-time", "example": 1642759067045 }, "firstSeenAt": { "type": "string", "format": "date-time", "example": 1642759067045 }, "lastSeenAt": { "type": "string", "format": "date-time", "example": 1642759067045 }, "device": { "$ref": "#/components/schemas/Device" }, "gateway": { "$ref": "#/components/schemas/Gateway" }, "alertRule": { "$ref": "#/components/schemas/AlertRule" }, "createdAt": { "type": "integer", "example": 1642759067045 }, "updatedAt": { "type": "integer", "example": 1642759067045 } } }, "AlertRule": { "type": "object", "properties": { "id": { "type": "string", "example": "alt_abcdef12345678" }, "name": { "type": "string", "example": "Gateway offline" }, "type": { "type": "string", "example": "email" }, "severity": { "type": "string", "example": "high" }, "enabled": { "type": "boolean", "example": true }, "autoResolve": { "type": "boolean", "example": false }, "config": { "type": "object", "example": {} }, "organisation": { "$ref": "#/components/schemas/Organisation" }, "product": { "$ref": "#/components/schemas/Product" }, "space": { "$ref": "#/components/schemas/Space" }, "notificationTemplate": { "$ref": "#/components/schemas/NotificationTemplate" }, "createdAt": { "type": "integer", "example": 1642759067045 }, "updatedAt": { "type": "integer", "example": 1642759067045 } } }, "NotificationTemplate": { "type": "object", "properties": { "id": { "type": "string", "example": "nt_abcdef12345678" }, "title": { "type": "string", "example": "Email template" }, "type": { "type": "string", "example": "email" }, "body": { "type": "string", "example": "Email body" }, "webhookUrl": { "type": "string", "example": "www.webhook-example.com" }, "webhookHeaders": { "type": "object", "example": {} }, "config": { "type": "object", "example": {} }, "createdAt": { "type": "integer", "example": 1642759067045 }, "updatedAt": { "type": "integer", "example": 1642759067045 } } }, "ApiKey": { "type": "object", "properties": { "secretKey": { "type": "string", "example": "d_sk_abc123def45678" }, "createdAt": { "type": "integer", "example": 1642759067045 } } }, "Device": { "type": "object", "properties": { "id": { "type": "string", "example": "dev_abc123" }, "isMain": { "type": "boolean", "example": true }, "isActive": { "type": "boolean", "example": true }, "name": { "type": "string", "example": "Test Device" }, "customId": { "type": "string", "example": "custom-id" }, "serialNumber": { "type": "string", "example": "abc12345678" }, "batchNumber": { "type": "string", "example": "123" }, "space": { "$ref": "#/components/schemas/Space" }, "product": { "$ref": "#/components/schemas/Product" }, "events": { "type": "array", "items": { "$ref": "#/components/schemas/Event" } }, "location": { "$ref": "#/components/schemas/Location" }, "state": { "type": "object" }, "meta": { "type": "object" }, "wifi": { "type": "object", "properties": { "macAddress": { "type": "string", "example": "00:00:00:B5:D5:A5" }, "rssi": { "type": "integer", "example": -90 } } }, "cellular": { "type": "object", "properties": { "network": { "type": "string", "example": "vodafone" }, "rssi": { "type": "integer", "example": -67 }, "imei": { "type": "string", "example": "10A12345677890" }, "iccid": { "type": "string", "example": "891004234814455936F" } } }, "bluetooth": { "type": "object", "properties": { "macAddress": { "type": "string", "example": "00:00:00:B5:D5:A5" }, "rssi": { "type": "integer", "example": -90 } } }, "lora": { "type": "object", "properties": { "devEui": { "type": "string", "example": "10A12345678910234" }, "devAddr": { "type": "string", "example": "10A123456" }, "appEui": { "type": "string", "example": "10A12345678910234567890" }, "appKey": { "type": "string", "example": "1234404C696E6B4C6F52613230313823" } } }, "sigfox": { "type": "object", "properties": { "id": { "type": "string", "example": "123456AD" } } }, "lastSeenAt": { "type": "integer", "example": 1631707207000 }, "lastUnprocessedEventTimestamp": { "type": "integer", "example": 1631707207000 }, "lastProcessedEventTimestamp": { "type": "integer", "example": 1631707207000 }, "createdAt": { "type": "integer", "example": 1631707207000 }, "updatedAt": { "type": "integer", "example": 1631707207000 } } }, "Event": { "type": "object", "properties": { "id": { "type": "string", "example": "1234-abcd-5678-efgh" }, "name": { "type": "string", "example": "Test Event" }, "data": { "type": "object", "example": { "test": true } }, "timestamp": { "type": "integer", "example": 1631707200000 } } }, "Electricity": { "type": "object", "required": [ "result" ], "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/EnergyReading" } }, "continuationToken": { "type": [ "string", "null" ], "example": "eyJ0bpo92Dd2twl7ko1=" } }, "oneOf": [ { "$ref": "#/components/schemas/EnergyDeviceReadings" }, { "$ref": "#/components/schemas/EnergyCountryReadings" } ] }, "EnergyReading": { "type": "object", "properties": { "energy": { "type": "string", "example": "1000" }, "timestamp": { "type": "integer", "example": 1631707200000 } } }, "EnergyDeviceReadings": { "type": "object", "properties": { "devices": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/EnergyReadingArray" }, "example": { "dev_abc123": [ { "energy": "1000", "timestamp": 1631707200000 } ], "dev_def456": [ { "energy": "2000", "timestamp": 1631707200000 } ] } } } }, "EnergyCountryReadings": { "type": "object", "properties": { "countries": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/EnergyReadingArray" }, "example": { "IRL": [ { "energy": "1000", "timestamp": 1631707200000 } ], "DEU": [ { "energy": "2000", "timestamp": 1631707200000 } ] } } } }, "EnergyReadingArray": { "type": "array", "items": { "$ref": "#/components/schemas/EnergyReading" } }, "Gas": { "type": "object", "required": [ "result" ], "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/GasReading" } }, "continuationToken": { "type": [ "string", "null" ], "example": "eyJ0bpo92Dd2twl7ko1=" } }, "oneOf": [ { "$ref": "#/components/schemas/GasDeviceReadings" }, { "$ref": "#/components/schemas/GasCountryReadings" } ] }, "GasReading": { "type": "object", "properties": { "energy": { "type": "string", "example": "1000" }, "timestamp": { "type": "integer", "example": 1631707200000 } } }, "GasDeviceReadings": { "type": "object", "properties": { "devices": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/GasReadingArray" }, "example": { "dev_abc123": [ { "gas": "1000", "timestamp": 1631707200000 } ], "dev_def456": [ { "gas": "2000", "timestamp": 1631707200000 } ] } } } }, "GasCountryReadings": { "type": "object", "properties": { "countries": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/GasReadingArray" }, "example": { "IRL": [ { "gas": "1000", "timestamp": 1631707200000 } ], "DEU": [ { "gas": "2000", "timestamp": 1631707200000 } ] } } } }, "GasReadingArray": { "type": "array", "items": { "$ref": "#/components/schemas/GasReading" } }, "Gateway": { "type": "object", "properties": { "id": { "type": "string", "example": "gty_123abc456" }, "serialNumber": { "type": "string", "example": "abc_23243456" }, "name": { "type": "string", "example": "Test Gateway" }, "product": { "type": "object", "properties": { "id": { "type": "string", "example": "pro_abcdef123" } } }, "isOnline": { "type": "boolean", "example": true }, "lora": { "type": "object", "properties": { "gatewayId": { "type": "string", "example": "123abc456def" } } }, "lastSeenAt": { "type": "integer", "example": 1631707207000 } } }, "Location": { "type": "object", "properties": { "id": { "type": "string", "example": "1234-abcd-5678-efgh" }, "latitude": { "type": "string", "example": "4.67" }, "longitude": { "type": "string", "example": "54.2" }, "altitude": { "type": "string", "example": "1.23" }, "timestamp": { "type": "integer", "example": 1631707200000 } } }, "Organisation": { "type": "object", "properties": { "id": { "type": "string", "example": "org_123abc456def" }, "name": { "type": "string", "example": "Test Organisation" } } }, "Product": { "type": "object", "properties": { "id": { "type": "string", "example": "pro_abc123def" }, "name": { "type": "string", "example": "Test Product" }, "description": { "type": "string", "example": "This is a Test Product" }, "manufacturer": { "type": "string", "example": "Wia" }, "model": { "type": "string", "example": "v1" }, "colour": { "type": "string", "example": "#2E7DFF" }, "category": { "type": "string", "example": "test" }, "image": { "type": "string", "example": "7170506d-5759-400e-a5d1-073c5d175abc" }, "state": { "type": "object", "example": { "state1": true } } } }, "Place": { "type": "object", "properties": { "id": { "type": "string", "example": "wpl_abc123def" }, "name": { "type": "string", "example": "Test Workplace" }, "state": { "type": "object", "example": { "state1": true } }, "config": { "type": "object", "example": { "capacity": 50, "squareMeters": 500, "maxAllowableHeadcount": 100, "currentAllocatedHeadcount": 80 } } } }, "Space": { "type": "object", "properties": { "id": { "type": "string", "example": "spc_abc123" }, "clientId": { "type": "string", "example": "client-specific-id" }, "name": { "type": "string", "example": "Test Space" }, "isPublic": { "type": "boolean", "example": false }, "disabled": { "type": "boolean", "example": false }, "avatar": { "type": "object", "properties": { "default": { "type": "string", "example": "1234-5342-5543-36AD" }, "url": { "type": "string", "example": "https://example.com/image" }, "thumbnail": { "type": "string", "example": "1234-5342-5543-36AD" } } }, "owner": { "type": "object", "properties": { "organisation": { "$ref": "#/components/schemas/Organisation" } } } } }, "Water": { "type": "object", "required": [ "result" ], "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/WaterReading" } }, "continuationToken": { "type": [ "string", "null" ], "example": "eyJ0bpo92Dd2twl7ko1=" } }, "oneOf": [ { "$ref": "#/components/schemas/WaterDeviceReadings" }, { "$ref": "#/components/schemas/WaterCountryReadings" } ] }, "WaterReading": { "type": "object", "properties": { "water": { "type": "string", "example": "1000" }, "timestamp": { "type": "integer", "example": 1631707200000 } } }, "WaterDeviceReadings": { "type": "object", "properties": { "devices": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/WaterReadingArray" }, "example": { "dev_abc123": [ { "water": "1000", "timestamp": 1631707200000 } ], "dev_def456": [ { "water": "2000", "timestamp": 1631707200000 } ] } } } }, "WaterCountryReadings": { "type": "object", "properties": { "countries": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/WaterReadingArray" }, "example": { "IRL": [ { "water": "1000", "timestamp": 1631707200000 } ], "DEU": [ { "water": "2000", "timestamp": 1631707200000 } ] } } } }, "WaterReadingArray": { "type": "array", "items": { "$ref": "#/components/schemas/WaterReading" } } }, "responses": { "NotFound": { "description": "The specified resource was not found." }, "BadRequest": { "description": "Bad Request." }, "Unauthorised": { "description": "Unauthorised." }, "ServerError": { "description": "Server Error." } } }, "servers": [ { "url": "https://api.wia.io/v1", "description": "Production" } ], "paths": { "/alerts": { "get": { "tags": [ "Alert" ], "security": [ { "ApplicationKey": [] } ], "description": "Retrieves a list of alerts in a Space", "parameters": [ { "name": "unresolved", "description": "Returns only unresolved alerts", "in": "query", "schema": { "type": "boolean" } }, { "name": "resolved", "description": "Returns only resolved alerts", "in": "query", "schema": { "type": "boolean" } }, { "$ref": "#/components/parameters/organisationId" }, { "$ref": "#/components/parameters/productId" }, { "$ref": "#/components/parameters/spaceId" }, { "$ref": "#/components/parameters/alertRuleId" }, { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/sort" }, { "$ref": "#/components/parameters/order" }, { "$ref": "#/components/parameters/since" }, { "$ref": "#/components/parameters/until" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Alert" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorised" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/alerts/{id}": { "get": { "tags": [ "Alert" ], "security": [ { "ApplicationKey": [] } ], "description": "Retrieves an alert", "parameters": [ { "name": "id", "description": "Id of the alert", "in": "path", "schema": { "type": "string" }, "required": true } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Alert" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorised" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/alerts/{id}/resolve": { "put": { "tags": [ "Alert" ], "security": [ { "ApplicationKey": [] } ], "description": "Update the resolution status of an alert", "parameters": [ { "name": "id", "description": "Id of the alert", "in": "path", "schema": { "type": "string" }, "required": true } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "resolvedAt": { "type": "number" }, "acknowledgedAt": { "type": "number" } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Alert" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorised" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/devices": { "get": { "tags": [ "Device" ], "security": [ { "ApplicationKey": [] } ], "description": "Retrieves a list of devices in a Model e.g. Device, Gateway, Flow, Workplace, Space, Organisation, Product, User, etc.", "parameters": [ { "$ref": "#/components/parameters/spaceIdNotRequired" }, { "$ref": "#/components/parameters/placeId" }, { "$ref": "#/components/parameters/gatewayId" }, { "$ref": "#/components/parameters/productId" }, { "$ref": "#/components/parameters/organisationId" }, { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/sort" }, { "$ref": "#/components/parameters/order" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Device" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorised" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/devices/{id}": { "get": { "tags": [ "Device" ], "security": [ { "ApplicationKey": [] } ], "description": "Retrieve a Device", "parameters": [ { "name": "id", "description": "Id of the device", "in": "path", "schema": { "type": "string" }, "required": true } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Device" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorised" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/energy/electricity": { "get": { "tags": [ "Energy" ], "security": [ { "ApplicationKey": [] } ], "description": "The API endpoint retrieves electricity consumption data in kilowatt-hours (kWh) from electricity meters.

The endpoint utilizes the underlying data from the meters to calculate and return the energy consumed by a customer during a given time period.

To use the API endpoint, the user will need to provide the necessary information, such as the date range for which they wish to retrieve data, the device id or space id to which a group of devices belong, and any other relevant parameters.

The endpoint will then gather underlying stores of meter readings and calculate the total energy consumed by the customer for a specified time resolution

The energy consumption data will be returned in kWh, which is the standard unit of measurement for electricity consumption and the time units are in UTC.

If the metres use current usage to read energy consumption, that is also outputted by the API endpoint with the same format as power consumption.

This API endpoint can be useful for a variety of applications, such as tracking energy usage for billing purposes, identifying energy-saving opportunities, and monitoring energy usage for sustainability initiatives.
", "parameters": [ { "$ref": "#/components/parameters/spaceIdNotRequired" }, { "$ref": "#/components/parameters/deviceId" }, { "$ref": "#/components/parameters/since" }, { "$ref": "#/components/parameters/until" }, { "$ref": "#/components/parameters/continuationToken" }, { "name": "timezone", "in": "query", "description": "The timezone to use for the data retrieval.\nIf not specified, the timezone will be set to Space timezone offset to UTC.\n", "required": false, "schema": { "type": "string", "example": "Europe/London" } }, { "name": "interval", "in": "query", "description": "Interval for the data aggregation in the format number unit,\nwhere unit can be 'minute', 'hour', 'day', 'week', or 'month'.\n", "required": false, "schema": { "type": "string", "pattern": "^\\d+\\s+(minute|hour|day|week|month)$", "default": "1 hour", "example": "2 hours" } }, { "name": "breakdown", "in": "query", "description": "The breakdown of the data to retrieve. If not specified,\nthe data will be retrieved for the entire organisation.\n", "required": false, "schema": { "type": "string", "enum": [ "device", "country" ] } }, { "name": "current", "in": "query", "description": "The current time period to retrieve data for.\nWhen specified, the return timestamps\nwill be aligned to time period for each timezone in UTC.\n", "required": false, "schema": { "type": "string", "enum": [ "hour", "day", "week", "month", "year" ] } }, { "name": "previous", "in": "query", "description": "The previous time period to retrieve data for.\nWhen specified, the return timestamps\nwill be aligned to time period for each timezone in UTC.\n", "required": false, "schema": { "type": "string", "enum": [ "hour", "day", "week", "month", "year" ] } }, { "name": "source", "in": "query", "description": "The source of the data to retrieve. Where its grid, solar or wind.\n", "required": false, "schema": { "type": "string", "enum": [ "grid", "solar", "wind", "generator", "other" ] } }, { "name": "flow", "in": "query", "description": "Whether the energy usage is consumed or produced.\n View guides for an more in-depth usage.\n", "required": false, "schema": { "type": "string", "enum": [ "consumption", "production", "import", "export" ] } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Electricity" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorised" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/energy/gas": { "get": { "tags": [ "Energy" ], "security": [ { "ApplicationKey": [] } ], "description": "The API endpoint retrieves Gas consumption data in (m³) from gas meters.

The endpoint utilizes the underlying data from the meters to calculate and return the gas consumed by a customer during a given time period.

To use the API endpoint, the user will need to provide the necessary information, such as the date range for which they wish to retrieve data, the device id or space id to which a group of devices belong, and any other relevant parameters.

The endpoint will then gather underlying stores of meter readings and calculate the total gas consumed by the customer during the specified time period such as 15 minutes, 2 hours, 1 day etc.

The gas consumption data will be returned in m³, which is the standard unit of measurement for gas consumption and the time units are in UTC.

This API endpoint can be useful for a variety of applications, such as tracking gas usage for billing purposes, identifying consumption saving opportunities, and monitoring usage for sustainability initiatives.
", "parameters": [ { "$ref": "#/components/parameters/spaceIdNotRequired" }, { "$ref": "#/components/parameters/deviceId" }, { "$ref": "#/components/parameters/since" }, { "$ref": "#/components/parameters/until" }, { "$ref": "#/components/parameters/continuationToken" }, { "name": "interval", "in": "query", "description": "Interval for the data aggregation in the format number unit,\nwhere unit can be 'minute', 'hour', 'day', 'week', or 'month'.\n", "required": false, "schema": { "type": "string", "pattern": "^\\d+\\s+(minute|hour|day|week|month)$", "default": "1 hour", "example": "2 hours" } }, { "name": "breakdown", "in": "query", "description": "The breakdown of the data to retrieve. If not specified,\nthe data will be retrieved for the entire organisation.\n", "required": false, "schema": { "type": "string", "enum": [ "device", "country" ] } }, { "name": "current", "in": "query", "description": "The current time period to retrieve data for.\nWhen specified, the return timestamps\nwill be aligned to time period for each timezone in UTC.\n", "required": false, "schema": { "type": "string", "enum": [ "hour", "day", "week", "month", "year" ] } }, { "name": "previous", "in": "query", "description": "The previous time period to retrieve data for.\nWhen specified, the return timestamps\nwill be aligned to time period for each timezone in UTC.\n", "required": false, "schema": { "type": "string", "enum": [ "hour", "day", "week", "month", "year" ] } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Gas" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorised" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/energy/water": { "get": { "tags": [ "Energy" ], "security": [ { "ApplicationKey": [] } ], "description": "The API endpoint retrieves Water consumption data in (m³) from water meters.

The endpoint utilizes the underlying data from the meters to calculate and return the water consumed by a customer during a given time period.

To use the API endpoint, the user will need to provide the necessary information, such as the date range for which they wish to retrieve data, the device id or space id to which a group of devices belong, and any other relevant parameters.

The endpoint will then gather underlying stores of meter readings and calculate the total water consumed by the customer during the specified time period such as 15 minutes, 2 hours, 1 day etc.

The water consumption data will be returned in m³, which is the standard unit of measurement for water consumption and the time units are in UTC.

This API endpoint can be useful for a variety of applications, such as tracking water usage for billing purposes, identifying consumption saving opportunities, and monitoring usage for sustainability initiatives.
", "parameters": [ { "$ref": "#/components/parameters/spaceIdNotRequired" }, { "$ref": "#/components/parameters/deviceId" }, { "$ref": "#/components/parameters/since" }, { "$ref": "#/components/parameters/until" }, { "$ref": "#/components/parameters/continuationToken" }, { "name": "timezone", "in": "query", "description": "The timezone to use for the data retrieval.\nIf not specified, the timezone will be set to Space timezone offset to UTC.\n", "required": false, "schema": { "type": "string", "example": "Europe/London" } }, { "name": "interval", "in": "query", "description": "Interval for the data aggregation in the format number unit,\nwhere unit can be 'minute', 'hour', 'day', 'week', or 'month'.\n", "required": false, "schema": { "type": "string", "pattern": "^\\d+\\s+(minute|hour|day|week|month)$", "default": "1 hour", "example": "2 hours" } }, { "name": "breakdown", "in": "query", "description": "The breakdown of the data to retrieve. If not specified,\nthe data will be retrieved for the entire organisation.\n", "required": false, "schema": { "type": "string", "enum": [ "device", "country" ] } }, { "name": "current", "in": "query", "description": "The current time period to retrieve data for.\nWhen specified, the return timestamps\nwill be aligned to time period for each timezone in UTC.\n", "required": false, "schema": { "type": "string", "enum": [ "hour", "day", "week", "month", "year" ] } }, { "name": "previous", "in": "query", "description": "The previous time period to retrieve data for.\nWhen specified, the return timestamps\nwill be aligned to time period for each timezone in UTC.\n", "required": false, "schema": { "type": "string", "enum": [ "hour", "day", "week", "month", "year" ] } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Event" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorised" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/gateways/": { "get": { "tags": [ "Gateway" ], "security": [ { "ApplicationKey": [] } ], "description": "List Gateways", "parameters": [ { "$ref": "#/components/parameters/spaceIdNotRequired" }, { "$ref": "#/components/parameters/organisationId" }, { "$ref": "#/components/parameters/productId" }, { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/sort" }, { "$ref": "#/components/parameters/order" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Gateway" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorised" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/gateways/{id}": { "get": { "tags": [ "Gateway" ], "security": [ { "ApplicationKey": [] } ], "description": "Retrieve a Gateway", "parameters": [ { "name": "id", "description": "Id of the Gateway", "in": "path", "schema": { "type": "string" }, "required": true } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Gateway" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorised" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/spaces": { "get": { "tags": [ "Space" ], "security": [ { "ApplicationKey": [] } ], "parameters": [ { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/sort" }, { "$ref": "#/components/parameters/order" }, { "name": "country", "description": "ISO 3166-1 alpha-3 country code", "in": "query", "schema": { "type": "string", "pattern": "^[A-Z]{3}$" }, "required": false } ], "description": "Retrieve list of all Spaces", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Space" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorised" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/spaces/{id}": { "get": { "tags": [ "Space" ], "security": [ { "ApplicationKey": [] } ], "description": "Retrieve a Space", "parameters": [ { "name": "id", "description": "Id of the space", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Space" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorised" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } } }, "tags": [ { "name": "Alert", "description": "Alerts provide information about devices that have gone offline or exhibited anomalies in their data, helping to monitor system health and identify potential issues.
Alerts can be resolved by acknowledging them, and can be filtered by their resolution status." }, { "name": "Device", "description": "Devices are a representation of objects that are connected to the Wia platform and can be used to collect data from the environment. The objects can be physical sensors, cloud integrations or manual uploads." }, { "name": "Energy", "description": "Energy consumption data is used to track the amount of energy used by a customer over a given time period.
The data can be used to identify energy-saving opportunities, monitor energy usage for sustainability initiatives, and track energy usage for billing purposes." }, { "name": "Gateway", "description": "Gateways are devices that connect to the Wia platform and are used to transport data from other devices in the environment to the Wia platform." }, { "name": "Space", "description": "Spaces are physical locations that are monitored by the Wia platform and house all devices and gateways that represent that location." } ] }