> ## Documentation Index
> Fetch the complete documentation index at: https://docs.datanumia.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Comparison of the annual electricity consumption of similar households

> This service returns the comparison of the annual consumption in kWh of a given site compared to its average similar households and the lowest consumers.




## OpenAPI

````yaml /api-reference/elec-similar-home.yaml get /sites/{site-id}/similar-home-yearly-elec-comparisons
openapi: 3.0.3
info:
  title: Similar home elec comparisons lifecycle
  description: |
    This API manages the consumption comparison elec with neighbors.
  termsOfService: TODO
  contact:
    email: api@datanumia.com
  version: 2.0.0
servers:
  - url: https://api.home.datanumia.com/api/v2
    description: Production Server
security: []
paths:
  /sites/{site-id}/similar-home-yearly-elec-comparisons:
    get:
      tags:
        - households consumption comparaison
      summary: Comparison of the annual electricity consumption of similar households
      description: >
        This service returns the comparison of the annual consumption in kWh of
        a given site compared to its average similar households and the lowest
        consumers.
      operationId: similarHomeYearlyComparisons
      parameters:
        - name: site-id
          in: path
          description: Site identifier
          required: true
          schema:
            type: string
        - name: begin-year
          in: query
          description: Year of the beginning of the comparison
          required: true
          schema:
            type: string
          example: '2014'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                title: arrayOfYearlySimilarHomeComparison
                type: array
                items:
                  $ref: '#/components/schemas/YearlySimilarHomeComparison'
        '400':
          description: >-
            Functional error. Possible values:<table><tr><td><b>Error
            code</b></td><td><b>Error case</b></td></tr>
            <tr><td>YEARS_MANDATORY</td><td>Missing years parameter</td></tr>
            <tr><td>INVALID_YEARS</td><td>Invalid years format</td></tr></table>
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                errorCode: YEARS_MANDATORY
                errorDescription: The year is mandatory.
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Unknown resource
          content: {}
        '500':
          description: Unexpected error
          content: {}
components:
  schemas:
    YearlySimilarHomeComparison:
      required:
        - beginMonth
        - endMonth
        - energies
        - percentComparison
        - year
      type: object
      properties:
        year:
          type: integer
          description: Year on which the comparison was made. format YYYY
          example: 2021
        beginMonth:
          type: string
          description: Month of the beginning of the comparison. format YYYY-MM
          example: 2021-01
        endMonth:
          type: string
          description: >-
            Month (included) of the end of the comparison on the year. format
            YYYY-MM
          example: 2021-08
        energies:
          type: object
          description: >-
            The yearly consumption power comparison (in KWh) between the site
            and the similar households
          additionalProperties:
            $ref: '#/components/schemas/ConsumptionComparison'
        costs:
          type: object
          description: >-
            The yearly consumption cost comparison between the site and the
            similar households
          additionalProperties:
            $ref: '#/components/schemas/ConsumptionComparison'
        percentComparison:
          type: object
          additionalProperties:
            type: integer
            description: >-
              Percentage difference in consumption between the site and
              neighbors, by type of neighbors (example "SH_AVERAGE_CONSUMING" :
              -12, "SH_LEAST_CONSUMING" : 12).
            format: int32
          example:
            SH_AVERAGE_CONSUMING: -20
        fromDate:
          type: string
          description: begin date of the comparison (format YYYY-MM-JJ)
          example: '2021-01-01'
        toDate:
          type: string
          description: end date of the comparison (the date is included, format YYYY-MM-JJ)
          example: '2021-08-05'
        comparisonCriteria:
          $ref: '#/components/schemas/ComparisonCriteriaMap'
    ErrorResponse:
      required:
        - errorCode
        - errorDescription
      type: object
      properties:
        errorCode:
          type: string
          description: >-
            error code - short string (example INVALID_PARAMETER_KEY
            INCONSISTENT_PERIOD)
        errorDescription:
          type: string
          description: >-
            complete error description (example "The parameter with key
            analysis-status is invalid")
    ConsumptionComparison:
      required:
        - site
        - similarHomes
      type: object
      properties:
        site:
          type: integer
          description: The consumption of the the site
          example: 984
        similarHomes:
          type: object
          additionalProperties:
            type: integer
            description: The average consumption of the neighbors
            format: int32
          example:
            SH_AVERAGE_CONSUMING: 1236
    ComparisonCriteriaMap:
      type: object
      additionalProperties:
        type: string
        description: criteria used to group sites to compare
      description: Map of the criteria used in comparison
      example:
        DEPARTMENT: '93'
        OFFER_TYPE: TRV
        SANITORY_HOT_WATER_TYPE: ELECTRICITE
        CLIMATE_ZONE: H1
        RESIDENCE_TYPE: Pas_Secondaire
        SUBSCRIBED_POWER: '9'
        PRINCIPAL_HEATING_SYSTEM_TYPE: ELECTRICITE
        CLIMATE_SUBZONE: H1a
        TARIFF: BLEU
        HOUSING_TYPE: MAISON
        OPTION: HPHC

````