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

# Consumptions simulation

> The service returns the simulated electrical consumption of a given site  between two specified dates with a given supply contract different from the current site supply contract.



## OpenAPI

````yaml /api-reference/energy-consumption.yaml post /api/v2/sites/{site-id}/consumption-simulation
openapi: 3.1.0
info:
  title: Energy consumption
  termsOfService: TODO
  contact:
    email: api@datanumia.com
  version: 2.0.0
servers:
  - url: https://api.home.datanumia.com/api
    description: Production Server
security: []
paths:
  /api/v2/sites/{site-id}/consumption-simulation:
    post:
      tags:
        - Energy consumption simulation
      summary: Consumptions simulation
      description: >-
        The service returns the simulated electrical consumption of a given
        site  between two specified dates with a given supply contract different
        from the current site supply contract.
      operationId: postConsumptionSimulation
      parameters:
        - name: site-id
          in: path
          description: The site identifier.
          required: true
          schema:
            type: string
        - name: beginTs
          in: query
          description: The starting timestamp to simulate the consumption from.
          required: true
          schema:
            type: string
            format: date-time
          example: '2023-01-01T00:00:00Z'
        - name: endTs
          in: query
          description: >-
            The ending timestamp (excluded) until which to simulate the
            consumption.
          required: true
          schema:
            type: string
            format: date-time
          example: '2024-02-01T00:00:00Z'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ContractSimulationDto'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SimulationDto'
        '400':
          description: |
            Bad request. Possible error codes:

              INCONSISTENT_PERIOD\
              INVALID_DATE_FORMAT\
              INVALID_SIMULATION_CONTRACT_PARAMETERS\
              MISSING_DATA\
              MISSING_MANDATORY_FIELD
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '404':
          description: Site not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '500':
          description: Unexpected error
          content: {}
components:
  schemas:
    ContractSimulationDto:
      properties:
        simulationContractParameters:
          type: object
          additionalProperties:
            type: string
          description: >-
            Parameters of the contract which will be used to simulate the site
            consumption calculation and valorization
          example:
            TARIFF_OPTION: OPTION
            PEAK_LOAD_GROUP: peakLoadGroup
            TARIFF: TARIFF
            SUBSCRIBED_POWER: '9'
            TPN_CATEGORY: tpnCategory
            MILLESIME: millesime
        simulationTariffCalendar:
          type: array
          description: >-
            Tariff calendar which will be used to simulate the site consumption
            calculation and valorization.
          items:
            $ref: '#/components/schemas/RangesByLabelDto'
    SimulationDto:
      properties:
        units:
          $ref: '#/components/schemas/ComputedConsumptionsSimulationUnitsDto'
        globalConsumption:
          $ref: '#/components/schemas/GlobalConsumptionSimulationDto'
    ApiError:
      type: object
      properties:
        errorCode:
          type: string
        errorDescription:
          type: string
    RangesByLabelDto:
      properties:
        label:
          type: string
        ranges:
          type: array
          items:
            $ref: '#/components/schemas/TimeRangeDto'
    ComputedConsumptionsSimulationUnitsDto:
      properties:
        cost:
          type: string
          format: ISO-4217
        energyMeter:
          type: string
        carbonFootprint:
          type: string
      required:
        - energyMeter
    GlobalConsumptionSimulationDto:
      properties:
        period:
          $ref: '#/components/schemas/ConsumptionPeriodDto'
        energyMeter:
          $ref: '#/components/schemas/ConsumptionEnergyMeterDto'
        cost:
          $ref: '#/components/schemas/ConsumptionSimulationCostDto'
        carbonFootprint:
          $ref: '#/components/schemas/ConsumptionSimulationCarbonFootprintDto'
        loadCurveCoverageRatio:
          type: number
          description: >-
            Number between 0 and 1 which corresponds to the daily load curve
            coverage ratio on the requested period
      required:
        - loadCurveCoverageRatio
        - period
    TimeRangeDto:
      properties:
        beginTime:
          type: string
        endTime:
          type: string
    ConsumptionPeriodDto:
      description: The period of each consumption
      properties:
        startTime:
          description: 'Always in format: YYYY-MM-DDThh:mm:ss+XX:XX'
          type: string
          format: date-time
        endTime:
          description: 'Always in format: YYYY-MM-DDThh:mm:ss+XX:XX'
          type: string
          format: date-time
      required:
        - startTime
        - endTime
    ConsumptionEnergyMeterDto:
      properties:
        total:
          type: number
          description: Total of the energy consumption.
        byTariffHeading:
          type: object
          additionalProperties:
            type: number
          description: Energy consumption broken down by tariff headings.
      required:
        - byTariffHeading
        - total
    ConsumptionSimulationCostDto:
      properties:
        total:
          type: number
          description: Total cost of the energy consumption on the period.
        standingCharge:
          type: number
          description: Total cost of the standing charge on the period.
        standingChargeByComponents:
          type: object
          additionalProperties:
            type: number
          description: >-
            Standing charge broken down by components (if standing charge
            components are defined for the tenant).
        byTariffHeading:
          type: object
          additionalProperties:
            type: number
          description: Energy cost broken down by tariff headings.
      required:
        - byTariffHeading
        - standingCharge
        - standingChargeByComponents
        - total
    ConsumptionSimulationCarbonFootprintDto:
      properties:
        coefficient:
          type: number
          description: >-
            Coefficient used to convert energy consumption into carbon
            footprint.
        total:
          type: number
          description: Total carbon footprint on the period.
        message:
          type: string
          description: >-
            Indicates if an information is missing to convert energy to carbon
            footprint.

````