Eliq Breakdown API

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.

    API has predictable resource oriented URLs, accepts JSON-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes and verbs.

    Insights API contains endpoints for two entities: Users and Locations.


    # Date and Time


    Dates and Datetimes follow ISO 8601 format.

    All dates and times are in `local time zone` - no UTC or other timezone specification is allowed for the queries and will result in error. Local timezone was chosen to make the data ready for presentation.


    # Responses and Errors


    Eliq insights API uses standard HTTP response codes to indicate success or failure of a request:

    - 2xx indicate success

    - 4xx indicate error due to invalid input

    - 5xx indicates an internal error of Eliq Insights API


    ## Status codes


    *Status code* | *Description*

    --- | ---

    200 - OK | Everything worked as expected.

    201 - Created | Resource created.

    204 - No Content | Successful request. Used in successful delete requests

    302 - Found | Resource requested has been temporarily moved to the URL given by the Location header.

    400 - Bad Request | Request input data is invalid.

    401 - Unauthorized | Access token invalid for the given request. E.g. access token expired.

    404 - Not Found | Requested resource not found.

    500, 502, 503, 504 | Something wrong with the Insights API.


    ## Error body


    Eliq Insights API returns an error response body on failures to provide additional information on the error.


    Some fields have been deprecated. Deprecated fields will continue to be used in existing endpoints, but will not show up in any new additions.


    | *Field* | *Type* | *Deprecated* | *Description* |

    | --- | --- | --- | --- |

    | type | String | Yes | Type of error. One of `third_party_error`, `internal_error`, `client_error` and `end_user_error`. |

    | category | String | Yes | Category of the error. E.g. `invalid_parameter`. Used to guide developers. |

    | code | String | | Error code specific to each issue. |

    | description | String | | A description of the error for more context and easier debugging.|

    | message | String | Yes | A message related to the error which can be shown to end users. |

    | transaction_id | String | | Transaction identifier with which request is associated. Pass this when contacting support |


    Example:


    ```json

    {

    "type":"client_error",

    "category":"invalid_parameter",

    "code":"MISSING_TO",

    "description":"Invalid parameter ''to''. Cannot be null",

    "message":"Something went wrong, please try again later. If problem remains, please contact support (error: 1ad3a534117d4).",

    "transaction_id":"1ad3a534117d4",

    }

    ```'
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:
    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.
    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.
    SimilarHomesGroupFilterType:
      enum:
      - limit_values
      - limit_range
      type: string
      description: Describes whether 'limit_values' or 'limit_range' should be used.
    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
    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.
    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.
    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
    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
    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
    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