Eliq Energy Performance Certificate API

openapi: 3.2.0
info:
  title: Insights Energy Performance Certificate 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: Energy Performance Certificate
paths:
  /v3/locations/{locationId}/epc-rating:
    get:
      tags:
      - Energy Performance Certificate
      summary: Get EPC rating
      description: Get an Actual or Estimated Energy Performance Certificate (EPC) rating for a location.
      operationId: get-v3-locations-locationId-epc-rating
      parameters:
      - name: locationId
        in: path
        required: true
        schema:
          type: integer
          format: int32
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EpcRatingResponse'
              examples:
                Actual EPC rating:
                  value:
                    energy_rating: B
                    energy_efficiency: 90
                    type: actual
                    valid_from: '2020-05-01T00:00:00'
                    valid_to: '2030-05-01T00:00:00'
                    status: active
                Estimated EPC rating:
                  value:
                    energy_rating: C
                    energy_efficiency: 84
                    type: estimated
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Location not found:
                  value:
                    code: ENTITY_NOT_FOUND
                    transaction_id: 0HN18NIB8K5RV:00000001
                    description: Could not find the location.
                Rating not available:
                  value:
                    code: EPC_RATING_NOT_AVAILABLE
                    transaction_id: 0HN18NIB8K5RV:00000001
                    description: EPC rating data is currently not available
                Country not supported:
                  value:
                    code: COUNTRY_NOT_SUPPORTED
                    transaction_id: 0HN18NIB8K5RV:00000001
                    description: Country is not currently supported
                Profile not supported:
                  value:
                    code: PROFILE_NOT_SUPPORTED
                    transaction_id: 0HN18NIB8K5RV:00000001
                    description: Profile is not supported, check description for more details
        '500':
          description: Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Internal Error:
                  value:
                    code: INTERNAL_SERVER_ERROR
                    transaction_id: 0HN18NIB8K5RV:00000001
                    description: Internal server error.
components:
  schemas:
    EpcRatingStatus:
      enum:
      - active
      - expired
      type: string
      description: 'Current energy rating status based on the valid from and to dates


        Not available for estimated energy rating type'
    EpcRatingType:
      enum:
      - actual
      - estimated
      type: string
      description: Energy rating type
    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.
    EpcRatingResponse:
      required:
      - energy_efficiency
      - energy_rating
      - type
      type: object
      properties:
        energy_rating:
          minLength: 1
          type: string
          description: Energy rating
        energy_efficiency:
          type: integer
          description: Energy efficiency
          format: int32
        type:
          $ref: '#/components/schemas/EpcRatingType'
        valid_from:
          type: string
          description: 'Valid from date


            Not available for estimated energy rating type'
          format: date-time
          nullable: true
        valid_to:
          type: string
          description: 'Valid to date


            Not available for estimated energy rating type'
          format: date-time
          nullable: true
        status:
          $ref: '#/components/schemas/EpcRatingStatus'
      description: EPC rating
  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