openapi: 3.2.0 info: title: Insights Breakdown API version: 3.4.1 contact: name: Insights Team email: support_b2b@eliq.com description: '# API Reference The Eliq insights API is organized around REST.' servers: - url: http://localhost:3000 security: - BearerAuth: [] tags: - name: Breakdown paths: /v3/locations/{locationId}/breakdown: parameters: - schema: type: string name: locationId in: path required: true description: Location identifier get: summary: Get location energy usage breakdown responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/ResultWrapper' examples: Breakdown: value: result: accuracy: MEDIUM total_value: 100450 from: '2019-10-01T00:00:00' to: '2019-11-01T00:00:00' unit: energy breakdown: - category: cooking value: 25047 - category: fridge_freezer value: 35623 - category: washing value: 18188 - category: heating value: 4223 - category: always_on value: 6365 - category: lightning value: 11000 result_status: code: ok action: null '400': description: 'Bad Request Possible errors | *type* | *category* | *description* | | --- | --- | --- | | client_error | invalid_parameter | Timespan too large, one month is maximum allowed | | client_error | invalid_parameter | Request input data is invalid | | client_error | invalid_parameter | CUSTOM_PERIOD_MUST_BE_AT_LEAST_28_DAYS |' content: application/json: schema: $ref: '#/components/schemas/Error' examples: Error example: value: type: client_error category: invalid_parameter description: Timespan too large, one month is maximum allowed message: 'Something went wrong, please try again later. If problem remains, please contact support (error: 1ad3a534117d4).' transaction_id: 37c4ef86-d525-42c8-b65f-9b4cfcce0df6 '501': description: 'Not Implemented Possible errors | *type* | *category* | *description* | | --- | --- | --- | | internal_error | breakdown_error | Breakdown for current month is not supported | | internal_error | breakdown_error | House type required for breakdown | | internal_error | breakdown_error | Not enough data points | | internal_error | breakdown_error | Solar panels are not supported in breakdown | | internal_error | breakdown_error | House type required for breakdown | | internal_error | breakdown_error | DAILY_RESOLUTION_OR_BETTER_REQUIRED_FOR_CUSTOM_PERIOD |' content: application/json: schema: $ref: '#/components/schemas/Error' examples: Error example: value: type: internal_error category: breakdown_error description: Not enough data points message: 'Something went wrong, please try again later. If problem remains, please contact support (error: 1ad3a534117d4).' transaction_id: 37c4ef86-d525-42c8-b65f-9b4cfcce0df6 operationId: get-v3-locations-locationId-breakdown description: '### This Endpoint is deprecated DEPRECATED “The new EUC endpoint "Get location energy usage categories (EUC)" should be used to get Energy Usage Categories instead. Eliq will continue to support this endpoint and will communicate a date when this endpoint will no longer be supported once a date has been set.” Get energy usage breakdown for a location. Energy usage is analyzed and broken down into a list of different usage categories. Energy Usage Categories helps homeowners to better understand their energy usage and learn what appliances consume the most energy. The endpoint returns 400 errors when there is an obvious implementation mistake and 501 errors when the error is caused by missing data. So please note that 501 errors are expected from this endpoint and this needs to be handled on the client side. All possible errors are listed below. `NOTE!` For cost to be available as a unit type, the location prices must be set in our database. If no location prices are available there will be an error response. `NOTE!` As default the from and to date are always rounded down to the nearest start of the month and returns full months. Max one month can be return in each call. However for locations that have daily data it is also possible to request EUC between two dates. We support a range between 28 - 31 days. Please set the custom_period to true to make this call. ### Data requirements **Required data** * Monthly data: Minimum 1 month * Geo location: Address information * Home profile: Minimum house type **Optional (improved accuracy)** * Hourly data: Minimum 30 days of hourly´or sub-hourly data ### Possible breakdown categories electricity | *Field* | *Description* | | --- | --- | | heating | Electricity usage used for space heating | | washing | Electricity usage used for laundry | | water_heating | Electricity usage used for water heating | | lightning | Electricity usage used for lighting. OBS! Please note that the key is misnamed to ligthning and not lighting :) | | consumer_electronics | Electricity usage used for home electronics | | cooking | Electricity usage used for cooking | | always_on | Electricity usage used for always on appliances | | fridge_freezer | Electricity usage used by fridge and freezers | | cooling | Electricity usage used to cool the home | | electric_vehicle | Electricity usage used for charging of cars | | other | Electricity usage used by appliances not matching other categories | | standing_charge | If unit is set to "cost", the cost for the standing charge is presented in a separate category | ### Possible breakdown categories gas | *Field* | *Description* | | --- | --- | | heating | Gas usage used for heating | | water_heating | Gas usage used for heating water | | cooking | Gas usage usage used for cooking | | standing_charge | If unit is set to "cost", the cost for the standing charge is presented in a separate category |' parameters: - schema: type: string example: energy enum: - energy - cost default: energy in: query name: unit description: Unit to receive result in. allowEmptyValue: true - schema: type: string default: elec enum: - elec - gas example: elec in: query name: fuel description: Fuel to get breakdown for. Currently 'elec' and 'gas' is supported. - schema: type: string example: '2021-01-01T00:00:00' in: query name: from description: 'From which date to retrieve breakdown ' - schema: type: string example: '2021-02-01' in: query name: to description: To which date to retrieve breakdown for (exclusive) - schema: type: string default: 'false' enum: - 'false' - 'true' example: 'false' in: query name: custom_period description: Set to true to be able to get a custom range between two dates. tags: - Breakdown deprecated: true components: schemas: ResultWrapper: description: Responses from the similar homes and breakdown endpoint are wrapped in an object called result wrapper. The result status will contain information about the response and whether it is an ok or not ok result. The object also contains information of what needs to be done to get an ok response, for example enter more properties to the home profile. type: object x-examples: breakdown-example: result: accuracy: medium total_value: 100450 from: '2019-10-01T00:00:00' to: '2019-11-01T00:00:00' unit: energy breakdown: - category: cooking value: 25047 - category: fridge_freezer value: 35623 - category: washing value: 18188 - category: cleaning value: 4223 - category: always_on value: 6365 - category: lightning value: 11000 result_status: code: ok title: Result wrapper examples: - result: accuracy: medium total_value: 100450 from: '2019-10-01T00:00:00' to: '2019-11-01T00:00:00' unit: energy breakdown: - category: cooking value: 25047 - category: fridge_freezer value: 35623 - category: washing value: 18188 - category: cleaning value: 4223 - category: always_on value: 6365 - category: lightning value: 11000 result_status: code: ok action: null properties: result: oneOf: - $ref: '#/components/schemas/Breakdown' - $ref: '#/components/schemas/SimilarHomesGroup' - $ref: '#/components/schemas/TimeseriesData' - $ref: '#/components/schemas/SimilarHomesReport' result_status: type: object description: Contains information about the result, and whether it was successful or not required: - code properties: code: type: string minLength: 1 description: Either "ok" or "not_ok". Used to decide whether there is a result or not. enum: - ok - not_ok example: ok action: type: - object - 'null' description: Available in cases where there are actions that can be done to make the result become ok, such as entering info in home profile options. properties: code: type: string description: 'A code for the action that should be taken. Please refer to documentation of specific endpoint for more information. ' description: type: string description: A description of the action that should be taken. required: - result_status Error: type: object properties: type: type: string description: Type of error. nullable: true example: internal_error category: type: string description: Error category. nullable: true example: internal_error code: type: string description: Code describing the issue. nullable: true example: INTERNAL_ERROR transaction_id: type: string description: Identifier for the session. Please provide this when contacting support. nullable: true example: 0HN18NN5QB401:00000001 message: type: string description: A message related to the error. nullable: true example: Something went wrong. Please try again later. If problem remains, please contact support. description: type: string description: A description of the error for developers. nullable: true example: Internal server error, please try again later. If problem remains, please contact support. description: Model returned for error responses. SimilarHomesGroupFilter: required: - description - key - type type: object properties: key: minLength: 1 type: string description: This key refers to keys in home profile, for example 'house_type', 'heating_type_primary' or 'living_area'. example: house_type description: minLength: 1 type: string description: Description for the filter. example: House type: $ref: '#/components/schemas/SimilarHomesGroupFilterType' limit_range: $ref: '#/components/schemas/LimitRange' limit_values: type: array items: type: string description: Available if type is 'limit_values'. For example, for key 'house_type', this would include the list of house types the location is compared with. nullable: true description: Similar homes group filter. BreakdownItem: description: Breakdown item contain usage information for a specific usage category type: object x-examples: example-1: category: cooking value: 25047 properties: category: type: string minLength: 1 example: cooking description: The breakdown category, eg. 'cooking' or 'always_on' value: type: number example: 25047 description: The amount of usage for the category (either in energy or cost) required: - category - value examples: - category: cooking value: 25047 Breakdown: description: 'The breakdown model contains information about the location breakdown (aka. Energy usage categories (EUC)). ' type: object x-examples: example-1: accuracy: medium total_value: 100450 from: '2019-10-01T00:00:00' to: '2019-11-01T00:00:00' unit: energy breakdown: - category: cooking value: 25047 - category: fridge_freezer value: 35623 - category: washing value: 18188 - category: cleaning value: 4223 - category: always_on value: 6365 - category: lightning value: 11000 title: Breakdown result properties: accuracy: type: string minLength: 1 enum: - LOW - MEDIUM - HIGH example: MEDIUM description: How certain we are of the result. Can be either 'low', 'medium' or 'high'. Could be used to let user know the accuracy of the breakdown, or whether to show it the application or not. total_value: type: number description: The total usage during the period example: 100450 from: type: string minLength: 1 format: date-time example: '2019-10-01T00:00:00' description: Start date of the consumption period, matches with the value passed in query parameters of the request. to: type: string minLength: 1 example: '2019-11-01T00:00:00' format: date-time description: 'End date of the consumption period, matches with the value passed in query parameters of the request. ' unit: type: string minLength: 1 enum: - energy - cost example: energy description: Can be ‘cost’ or ‘energy’. Matches with the value passed in query parameters of the request if provided, otherwise default. breakdown: type: array uniqueItems: true minItems: 1 items: $ref: '#/components/schemas/BreakdownItem' required: - accuracy - total_value - from - to - unit - breakdown examples: - accuracy: medium total_value: 100450 from: '2019-10-01T00:00:00' to: '2019-11-01T00:00:00' unit: energy breakdown: - category: cooking value: 25047 - category: fridge_freezer value: 35623 - category: washing value: 18188 - category: cleaning value: 4223 - category: always_on value: 6365 - category: lightning value: 11000 SimilarHomesGroupFilterType: enum: - limit_values - limit_range type: string description: Describes whether 'limit_values' or 'limit_range' should be used. TimeseriesData: description: Model containing time series data. Different parameters will be available depending on the data requested, see below for more information type: object x-examples: example-1: consumption: - 446.37 - null import: - 446.37 - null export: - 446.37 - null production: - 446.37 - null fuel: elec unit: energy resolution: month from: '2019-01-01T00:00:00' to: '2019-03-01T00:00:00' examples: - consumption: - 446.37 - null fuel: elec unit: energy resolution: month from: '2021-01-01T00:00:00' to: '2021-03-01T00:00:00' title: Time series data properties: consumption: type: array description: Available if consumption has been queried. Will always contain the exact amount of elements as there are time frames between ‘to’ and ‘from’ with the given ‘resolution’. Values inside the array can be null if no energy data exists (One day always contains 24 values). The consumption values are floating-point numbers. items: type: - number - 'null' import: type: array description: Available if import has been queried. Will always contain the exact amount of elements as there are time frames between ‘to’ and ‘from’ with the given ‘resolution’. Values inside the array can be null if no energy data exists (One day always contains 24 values). The import values are floating-point numbers. items: type: - number - 'null' export: type: array description: Available if export has been queried. Will always contain the exact amount of elements as there are time frames between ‘to’ and ‘from’ with the given ‘resolution’. Values inside the array can be null if no energy data exists (One day always contains 24 values). The export values are floating-point numbers. items: type: - number - 'null' production: type: array description: Available if production has been queried. Will always contain the exact amount of elements as there are time frames between ‘to’ and ‘from’ with the given ‘resolution’. Values inside the array can be null if no energy data exists (One day always contains 24 values). The production values are floating-point numbers. items: type: - number - 'null' forecast: type: array description: Available if forecast has been queried. Will always contain the exact amount of elements as there are time frames between ‘to’ and ‘from’ with the given ‘resolution’. Values inside the array can be null if no energy data exists. The forecast values are floating-point numbers. items: type: - number - 'null' fuel: type: string minLength: 1 description: Can be ‘elec’, ‘gas’ or ‘district_heating’. Matches with the value passed in query parameters of the request if provided enum: - elec - gas - district_heating example: elec unit: type: string minLength: 1 description: 'Can be ‘cost’, ‘energy’ or ''m3''. Matches with the value passed in query parameters of the request if provided, otherwise default. Only return m3 if the unit is available.' enum: - energy - cost example: energy resolution: type: string minLength: 1 description: Can be '6min','15min', '30min', 'hour', 'day' or 'month'. Matches with the value passed in query parameters of the request. enum: - 6min - 15min - 30min - hour - day - month from: type: string minLength: 1 description: From date example: '2021-01-01T00:00:00' to: type: string minLength: 1 description: To date example: '2021-02-01T00:00:00' required: - fuel - unit - resolution - from - to LimitRange: required: - max - min type: object properties: min: type: number description: Minimum number in the range. For example, if key is 'living_area' and min is 150, it means minimum 150 square meters. format: double example: 150 max: type: number description: Maximum number in the range. For example, if key is 'living_area' and max is 200, it means maximum 200 square meters. format: double example: 200 description: Available if type is 'limit_range'. Contains minimum and maximum values for the given key. SimilarHomesGroup: required: - contributors - filters type: object properties: filters: minItems: 1 type: array items: $ref: '#/components/schemas/SimilarHomesGroupFilter' description: A list of filters that was used when finding a similar homes group. contributors: type: integer description: Number of contributors in the group. format: int32 example: 1 description: Description of similar homes that a location is compared to. SimilarHomesReport: required: - distribution_values - from - to - value type: object properties: value: type: number description: Average energy in Wh or cost for similar homes over the requested period format: double distribution_values: type: array items: type: number format: double description: Similar homes consumption data deciles. Contains values for all 10 ranks of deciles - starting from 1st and ending with 10th decile. The 1st decile has 10 per cent of the data set below it, the 2nd decile has 20 per cent of the data set below and so on. The 10th decile has 100 per cent of the data set below, making it a maximum value for the dataset. energy_wh: type: integer description: Average energy Wh for similar homes over the requested period format: int32 nullable: true deprecated: true distribution: type: array items: type: integer format: int32 description: Distribution of similar homes energy Wh consumption in deciles nullable: true deprecated: true from: type: string description: From date format: date-time to: type: string description: To date format: date-time description: Similar homes report for the requested period. securitySchemes: BearerAuth: type: http scheme: bearer description: The Eliq insights API uses bearer tokens to authenticate requests. Read more under Authentication tag. x-tagGroups: - name: Authentication tags: - Authentication - name: Users tags: - Users - name: Locations tags: - Locations - Location Profile - Energy Data - Energy Usage Categories - Energy Performance Certificate - Similar Homes - Budgets - Advice - Anomalies - Market Price - Price Formulas - name: Eliq Connect tags: - Eliq Connect - name: Health tags: - Health - name: Deprecated tags: - Breakdown - Home Profile