> ## 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 monthly electricity consumption of similar households

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




## OpenAPI

````yaml /api-reference/elec-similar-home.yaml get /sites/{site-id}/similar-home-monthly-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-monthly-elec-comparisons:
    get:
      tags:
        - households consumption comparaison
      summary: Comparison of the monthly electricity consumption of similar households
      description: >
        This service returns the comparison of the monthly consumption in kWh of
        a given site in relation to its average similar households and the
        lowest consumers.
      operationId: similarHomeMonthlyComparisons
      parameters:
        - name: site-id
          in: path
          description: Site identifier
          required: true
          schema:
            type: string
        - name: begin-month
          in: query
          description: >-
            The month (inculded) from which we wish to recover data. format
            YYYY-MM.
          required: true
          schema:
            type: string
          example: 2021-01
        - name: end-month
          in: query
          description: >-
            The month (excluded) up to which we wish to recover data. format
            YYYY-MM.
          required: true
          schema:
            type: string
          example: 2021-02
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                title: arrayOfMonthlySimilarHomeComparison
                type: array
                items:
                  $ref: '#/components/schemas/MonthlySimilarHomeComparison'
        '400':
          description: >-
            Functional error. Possible values:<table><tr><td><b>Error
            code</b></td><td><b>Error case</b></td></tr>
            <tr><td>BEGIN_MONTH_MANDATORY</td><td>Missing begin-month
            parameter</td></tr> <tr><td>END_MONTH_MANDATORY</td><td>Missing
            end-month parameter</td></tr>
            <tr><td>INCONSISTENT_PERIOD</td><td>begin-month>end-month</td></tr>
            <tr><td>INVALID_BEGIN_MONTH</td><td>Invalid begin-month
            format</td></tr> <tr><td>INVALID_END_MONTH</td><td>Invalid end-month
            format</td></tr></table>
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                errorCode: BEGIN_YEAR_MANDATORY
                errorDescription: The begin-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:
    MonthlySimilarHomeComparison:
      required:
        - energies
        - month
        - percentComparison
      type: object
      properties:
        month:
          type: string
          description: Month comparison.
          example: 2021-01
        fromDate:
          type: string
          description: begin date of the comparison
          example: '2021-01-01'
        toDate:
          type: string
          description: end date of the comparison (the date is excluded, format YYYY-MM-JJ)
          example: '2021-02-01'
        energies:
          type: object
          description: >-
            The monthly consumption power comparison (in KWh) between the site
            and the similar households
          additionalProperties:
            $ref: '#/components/schemas/ConsumptionComparison'
        costs:
          type: object
          description: >-
            The monthly 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: -56
    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

````