> ## 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.

# Disaggregation

> The service returns the monthly energy disaggregation of a given site between two specified dates.



## OpenAPI

````yaml /api-reference/energy-disaggregation.yaml get /v1/sites/{site-id}/usage-breakdowns/monthly
openapi: 3.1.0
info:
  title: Energy disaggregation
  termsOfService: TODO
  contact:
    email: api@datanumia.com
  version: 2.0.0
servers:
  - url: https://api.home.datanumia.com/api
    description: Production Server
security: []
paths:
  /v1/sites/{site-id}/usage-breakdowns/monthly:
    get:
      tags:
        - Monthly energy disaggregation
      summary: Disaggregation
      description: >-
        The service returns the monthly energy disaggregation of a given site
        between two specified dates.
      operationId: getMonthlyUsageBreakdowns
      parameters:
        - name: site-id
          in: path
          description: The site identifier
          required: true
          schema:
            type: string
        - name: begin-ts
          in: query
          description: >-
            The timestamp of the starting month (included) to return monthly
            consumption disaggregation from
          required: true
          schema:
            type: string
            format: date-time
          example: >-
            2023-01-01T00:00:00Z to calculate monthly consumption disaggregation
            from January 2023
        - name: end-ts
          in: query
          description: >-
            The timestamp of the ending month (excluded) until which to return
            monthly consumption disaggregation
          required: true
          schema:
            type: string
            format: date-time
          example: >-
            2023-06-01T00:00:00Z to calculate disaggregation until June 2023
            excluded
        - name: fluid
          in: query
          description: The type of consumption (electricity or gas).
          required: false
          schema:
            type: string
            enum:
              - ELEC
              - GAS
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/YearlyUsageBreakdownDTO'
        '400':
          description: Bad request.
          content: {}
        '404':
          description: Site not found
        '500':
          description: Unexpected error
components:
  schemas:
    YearlyUsageBreakdownDTO:
      required:
        - monthlyUsageBreakdowns
        - year
      type: object
      properties:
        year:
          type: integer
          description: Year of the monthly disaggregations
        monthlyUsageBreakdowns:
          type: array
          items:
            $ref: '#/components/schemas/MonthlyUsageBreakdownDTO'
    MonthlyUsageBreakdownDTO:
      required:
        - algorithm
        - month
        - totalConsumption
        - totalCost
        - usageBreakdowns
      type: object
      properties:
        month:
          type: string
          description: Month of the disaggregation.
          format: YYYY-MM
        totalCost:
          type: integer
          description: Total cost of the energy consumption on the month.
        totalConsumption:
          type: integer
          description: Total of the energy consumption on the month.
        algorithm:
          type: string
          description: >-
            Algorithm which has been used to calculate the monthly consumption
            disaggregation.
          enum:
            - DISAGGREGATION
            - REGIME
            - SIMFAST
            - MIX_DISAGGREGATION_REGIME
            - MIX_DISAGGREGATION_SIMFAST
            - NO_ALGORITHM
        usageBreakdowns:
          type: array
          items:
            $ref: '#/components/schemas/UsageBreakdownByMonthDTO'
    UsageBreakdownByMonthDTO:
      required:
        - consumption
        - cost
        - percent
        - usage
      type: object
      properties:
        usage:
          type: string
          enum:
            - US_HEATING
            - US_SANITARY_HOT_WATER
            - US_AIR_CONDITIONING
            - US_WASHING_DRYING
            - US_FRIDGE_FREEZER
            - US_COOKING
            - US_LIGHTING
            - US_SWIMMING_POOL
            - US_AQUARIUM
            - US_ELECTRIC_VEHICLE
            - US_AUDIO
            - US_ALWAYS_ON
            - US_OTHERS
        cost:
          type: integer
          description: Cost of the usage consumption on the month.
        percent:
          type: integer
          description: Percentage of the usage consumption out of total consumption.
        consumption:
          type: integer
          description: Energy consumption of the usage on the month.
        fiability:
          $ref: '#/components/schemas/Fiability'
        connectedPartCost:
          type: number
          description: Cost of the usage consumption sent by connected devices.
          format: double
        connectedPartEnergy:
          type: number
          description: Energy of the usage consumption sent by connected devices.
          format: double
    Fiability:
      description: Indicates if the usage is reliable according to the profile information.
      type: object
      properties:
        isReliable:
          type: boolean
        equipmentsFiability:
          type: object
          additionalProperties:
            type: string

````