> ## 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 > The service returns the electrical consumption of a given site between two specified dates at the requested step. The number of returned consumptions in the response is limited to 1200. ## OpenAPI ````yaml /api-reference/energy-consumption.yaml get /v2/sites/{site-id}/fluids/elec/consumptions 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: /v2/sites/{site-id}/fluids/elec/consumptions: get: tags: - Electric energy consumptions summary: Consumptions description: > The service returns the electrical consumption of a given site between two specified dates at the requested step. The number of returned consumptions in the response is limited to 1200. operationId: getElecComputedConsumption parameters: - name: site-id in: path description: The site identifier required: true schema: type: string - name: beginTs in: query description: | The starting timestamp to calculate the consumption from. Accepted format: - YYYY-MM-DDThh:mm:ss - YYYY-MM-DDThh:mm:ssZ - YYYY-MM-DDThh:mm:ss+XX:XX required: true schema: type: string format: date-time example: - '2022-01-01T00:00:00' - '2021-01-01T23:00:00Z' - '2023-01-01T00:00:00+01:00' - name: endTs in: query description: > The ending timestamp (excluded) until which to calculate the consumption. Accepted format: - YYYY-MM-DDThh:mm:ss - YYYY-MM-DDThh:mm:ssZ - YYYY-MM-DDThh:mm:ss+XX:XX required: true schema: type: string format: date-time example: - '2023-01-01T00:00:00' - '2022-01-01T23:00:00Z' - '2023-01-01T00:00:00+01:00' - name: stepUnit in: query description: >- Step unit in which consumption will be returned. If not provided, the step used will be the whole period. required: false schema: type: string enum: - YEARS - MONTHS - DAYS - HOURS - MINUTES example: DAYS - name: stepValue in: query description: > Step value in which consumption will be returned. For example, if the stepUnit is MONTHS and the stepValue is 2, the consumption will be returned in a step of 2 months. required: false schema: type: integer format: int64 default: 1 example: 2 - name: indexCategories in: query description: Index categories that may be used for the consumption calculation. style: form explode: true required: false schema: type: array items: type: string enum: - RTM - SUPPLIER - SMART_METER - LEGACY_METER - SENSOR - STEREO - SELF_METER_READING - ESTIMATED - name: withEstimated in: query description: > Index strategy to filter estimated indexes. **NO_ESTIMATED**: No estimated indexes will be used for the consumption calculation. **ALL_ESTIMATED**: All estimated indexes may be used for the consumption calculation. **SURROUNDING_ESTIMATED**: Estimated indexes may be used to complete beginning or end consumption period, if the site misses non-estimated indexes at the beginning and/or end of the period. required: false schema: type: string default: SURROUNDING_ESTIMATED enum: - NO_ESTIMATED - ALL_ESTIMATED - SURROUNDING_ESTIMATED - name: sources in: query description: Data sources that may be used for the consumption calculation. style: form explode: true required: false schema: type: array default: - SMART_METER - LEGACY_INDEX - LOAD_CURVE - SENSOR items: type: string enum: - INTRADAY - SMART_METER - LEGACY_INDEX - LOAD_CURVE - SENSOR - name: withLoadCurveCompletion in: query description: >- If set to true, load curve information may be used to complete beginning or end consumption period, if the site misses non-estimated indexes at the beginning and/or end of the period. required: false schema: type: boolean default: true - name: filters in: query description: > **withoutCost**: If selected, the consumption cost will not be returned. **withGlobalConsumption**: If selected, the global consumption on the requested period will be added to the response. This parameter is limited to a period of maximum one year. **withCarbonFootprint**: If selected, the carbon footprint associated to the consumption will be returned. **withRatioByTariffHeading**: If selected, the consumption ratios by tariff heading and by tariff heading group will be returned. style: form explode: true required: false schema: type: array items: type: string enum: - withoutCost - withCarbonFootprint - withGlobalConsumption - withRatioByTariffHeading responses: '200': description: 'OK - return computed Consumptions for site-id ' content: application/json: schema: $ref: '#/components/schemas/ComputedConsumptionsDto' example: period: startTime: '2022-01-01T00:00:00+01:00' endTime: '2023-01-01T00:00:00+01:00' computationPeriod: startTime: '2022-01-13T00:00:00+01:00' endTime: '2022-12-16T00:00:00+01:00' step: P1M units: cost: EUR energyMeter: KWH carbonFootprint: KG consumptions: - period: startTime: '2022-02-01T00:00:00+01:00' endTime: '2022-03-01T00:00:00+01:00' energyMeter: total: 1300.1 byTariffHeading: HP: 969.8 HC: 330.3 cost: total: 238 standingCharge: 15.4 standingChargeByComponents: {} byTariffHeading: HP: 177.1 HC: 45.5 carbonFootprint: coefficient: 60 total: 78.4 quality: 1 errorFlags: [] indexNatures: - LINKY_OK status: COMPLETE nature: REAL aggregated: false usingLoadCurve: false globalConsumption: period: startTime: '2022-01-01T00:00:00+01:00' endTime: '2023-01-01T00:00:00+01:00' energyMeter: total: 13930.8 byTariffHeading: HP: 10447.7 HC: 3483.1 cost: total: 2561.2 standingCharge: 185 standingChargeByComponents: {} byTariffHeading: HP: 1902.5 HC: 473.7 carbonFootprint: coefficient: 63.3 total: 881.8 quality: 1 errorFlags: [] indexNatures: - LINKY_OK status: COMPLETE nature: REAL aggregated: false usingLoadCurve: false '400': description: |- Functional error. Possible values: Error code | Error case ---------|---------- INCONSISTENT_PERIOD | Start date (beginTs) more recent than the end date (endTs) INVALID_DATE_FORMAT | Incorrect date format (beginTs and/or endTs) INVALID STEP UNIT | Invalid time step unit (not part of the list: DAYS, MONTHS, YEARS, etc.) MISSING_MANDATORY_FIELD | Mandatory field not filled in UNKNOWN_INDEX_CATEGORY | Index category value (fields "indexCategories") unknown UNKNOWN_INDEX_FILTER_STRATEGY | Index filtering strategy (fields "withEstimated") unknown TOO_LONG_PERIOD | Global consumption (filters="withGlobalConsumption" ) cannot be requested with a period greater than one year OUT_OF_CALCULATION_PERIOD | Requested period is outside the 3-year consumption history UNKNOWN_CONSUMPTION_FILTER | Filter value (field "filters") unknown TOO_MANY_CONSUMPTIONS | Number of consumptions to be returned exceeds a certain threshold (parameter currently set at 1200) INVALID_REQUEST | Site must have elec This list can be expanded over time. content: application/json: schema: $ref: '#/components/schemas/ApiError' '404': description: Site or weights not found content: application/json: schema: $ref: '#/components/schemas/ApiError' '500': description: Unexpected error content: {} components: schemas: ComputedConsumptionsDto: properties: period: $ref: '#/components/schemas/ComputedConsumptionsPeriodDto' computationPeriod: $ref: '#/components/schemas/ComputedConsumptionsComputationPeriodDto' step: type: string format: ISO-8601 description: The step in which the consumption is returned. units: $ref: '#/components/schemas/ComputedConsumptionsUnitsDto' consumptions: type: array items: $ref: '#/components/schemas/ConsumptionDto' globalConsumption: $ref: '#/components/schemas/GlobalConsumptionDto' required: - consumptions - period - step - units ApiError: type: object properties: errorCode: type: string errorDescription: type: string ComputedConsumptionsPeriodDto: description: The requested period. 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 ComputedConsumptionsComputationPeriodDto: description: >- Is returned only if the period over which the consumption is actually calculated does not correspond to the requested period (incomplete 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 ComputedConsumptionsUnitsDto: properties: cost: type: string format: ISO-4217 description: Is not returned if withoutCost filter is selected in the request. energyMeter: type: string carbonFootprint: type: string description: >- Is returned if withCarbonFootprint filter is selected in the request. required: - energyMeter ConsumptionDto: properties: period: $ref: '#/components/schemas/ConsumptionPeriodDto' energyMeter: $ref: '#/components/schemas/ConsumptionEnergyMeterDto' ratioByTariffHeading: type: object additionalProperties: type: number description: >- Is returned if withRatioByTariffHeading filter is selected in the request. ratioByTariffHeadingGroup: type: object additionalProperties: type: number description: >- Is returned if withRatioByTariffHeading filter is selected in the request. cost: $ref: '#/components/schemas/ConsumptionCostDto' carbonFootprint: $ref: '#/components/schemas/ConsumptionCarbonFootprintDto' quality: type: number format: float description: >- Number between 0 (poor quality) and 1 (optimal quality). Quality level decreases when the indexes used for consumption calculation are interpolated from indexes that are distant in time. errorFlags: type: array description: > Indicates if an error has been encountered in the consumption calculation. **BAD_INDEX_INFORMATION_OR_CONTRACT_CHANGE_MISSING**: We have incoherent information in the contracts or indexes associated to the site. **ABERRANT_CONSUMPTION**: The calculated consumption is above the aberrancy threshold items: type: string enum: - BAD_INDEX_INFORMATION_OR_CONTRACT_CHANGE_MISSING - ABERRANT_CONSUMPTION uniqueItems: true indexNatures: type: array description: >- Natures of the indexes that have been used to calculate the consumption. items: type: string enum: - MKT_SMART_DISTRIBUTOR - MKT_CYCLIC_DISTRIBUTOR - MKT_CUSTOMER - DTN_CUSTOMER_ACK - MKT_ESTIMATION - MKT_SMART_DISTRIBUTOR_INVALID - MKT_CYCLIC_DISTRIBUTOR_INVALID - MKT_CUSTOMER_INVALID - DTN_CUSTOMER_ACK_INVALID - MKT_ESTIMATION_INVALID - LINKY_OK - LINKY_INTERPOLE - LINKY_SUJET_A_CAUTION - DISTRIBUTEUR - DISTRIBUTEUR_INVALIDE - MKT_SENSOR - MKT_SENSOR_INVALIDE - STEREO - RELEVE_CONFIANCE - RELEVE_CONFIANCE_INVALIDE - SCORE_RC - SCORE_RC_ACQUITTE - SCORE_RC_INVALIDE - SCORE_RC_INVALIDE_APPLIANCE - SCORE - SCORE_ACQUITTE - SCORE_INVALIDE_EDE - SCORE_INVALIDE_ACP - SCORE_INVALIDE_USER - SCORE_INVALIDE_APPLIANCE - SUIVI_CONSO - SUIVI_CONSO_INVALIDE - ESTI_EDELIA - ESTI_ACC - ESTI_ACC_INVALIDE - SCORE_INVALIDE_TRV_OM - RTM - SUPPLIER_SMART_INDEX - SUPPLIER_SMART_INDEX_SUJET_A_CAUTION uniqueItems: true status: type: string description: > Indicates if the consumption has been calculated on the whole requested period or not. **EMPTY**: No consumption is calculated. **INCOMPLETE**: The period over which the consumption is actually calculated is shorter than the requested period, due to missing indexes. **COMPLETE**: The consumption is calculated over the whole requested period. enum: - EMPTY - INCOMPLETE - COMPLETE nature: type: string description: > Indicates the type of data that has been used for the consumption calculation. **REAL**: The consumption has been calculated without interpolation, without using estimated data and without data from sensors. **ESTIMATED**: The consumption has been calculated with index interpolation and/or by using estimated data. **SENSOR**: The consumption has been calculated with data from sensors. **EMPTY**: No consumption is calculated. enum: - REAL - ESTIMATED - SENSOR - EMPTY aggregated: type: boolean description: >- Indicates if the consumption has been calculated by aggregating load curve data. usingLoadCurve: type: boolean description: >- Indicates if the consumption has been calculated by using load curve data. required: - aggregated - energyMeter - indexNatures - nature - period - quality - status - usingLoadCurve GlobalConsumptionDto: description: >- Information on the global consumption on the requested period. Is returned if withGlobalConsumption filter is selected in the request. properties: period: $ref: '#/components/schemas/ConsumptionPeriodDto' energyMeter: $ref: '#/components/schemas/ConsumptionEnergyMeterDto' ratioByTariffHeading: type: object additionalProperties: type: number description: >- Is returned if withRatioByTariffHeading filter is selected in the request. ratioByTariffHeadingGroup: type: object additionalProperties: type: number description: >- Is returned if withRatioByTariffHeading filter is selected in the request. cost: $ref: '#/components/schemas/ConsumptionCostDto' carbonFootprint: $ref: '#/components/schemas/ConsumptionCarbonFootprintDto' quality: type: number format: float description: >- Number between 0 (poor quality) and 1 (optimal quality). Quality level decreases when the indexes used for consumption calculation are interpolated from indexes that are distant in time. errorFlags: type: array description: > Indicates if an error has been encountered in the consumption calculation. **BAD_INDEX_INFORMATION_OR_CONTRACT_CHANGE_MISSING**: We have incoherent information in the contracts or indexes associated to the site. **ABERRANT_CONSUMPTION**: The calculated consumption is above the aberrancy threshold items: type: string enum: - BAD_INDEX_INFORMATION_OR_CONTRACT_CHANGE_MISSING - ABERRANT_CONSUMPTION uniqueItems: true indexNatures: type: array description: >- Natures of the indexes that have been used to calculate the consumption. items: type: string enum: - MKT_SMART_DISTRIBUTOR - MKT_CYCLIC_DISTRIBUTOR - MKT_CUSTOMER - DTN_CUSTOMER_ACK - MKT_ESTIMATION - MKT_SMART_DISTRIBUTOR_INVALID - MKT_CYCLIC_DISTRIBUTOR_INVALID - MKT_CUSTOMER_INVALID - DTN_CUSTOMER_ACK_INVALID - MKT_ESTIMATION_INVALID - LINKY_OK - LINKY_INTERPOLE - LINKY_SUJET_A_CAUTION - DISTRIBUTEUR - DISTRIBUTEUR_INVALIDE - MKT_SENSOR - MKT_SENSOR_INVALIDE - STEREO - RELEVE_CONFIANCE - RELEVE_CONFIANCE_INVALIDE - SCORE_RC - SCORE_RC_ACQUITTE - SCORE_RC_INVALIDE - SCORE_RC_INVALIDE_APPLIANCE - SCORE - SCORE_ACQUITTE - SCORE_INVALIDE_EDE - SCORE_INVALIDE_ACP - SCORE_INVALIDE_USER - SCORE_INVALIDE_APPLIANCE - SUIVI_CONSO - SUIVI_CONSO_INVALIDE - ESTI_EDELIA - ESTI_ACC - ESTI_ACC_INVALIDE - SCORE_INVALIDE_TRV_OM - RTM - SUPPLIER_SMART_INDEX - SUPPLIER_SMART_INDEX_SUJET_A_CAUTION uniqueItems: true status: type: string description: > Indicates if the consumption has been calculated on the whole requested period or not. **EMPTY**: No consumption is calculated. **INCOMPLETE**: The period over which the consumption is actually calculated is shorter than the requested period, due to missing indexes. **COMPLETE**: The consumption is calculated over the whole requested period. enum: - EMPTY - INCOMPLETE - COMPLETE nature: type: string description: > Indicates the type of data that has been used for the consumption calculation. **REAL**: The consumption has been calculated without interpolation, without using estimated data and without data from sensors. **ESTIMATED**: The consumption has been calculated with index interpolation and/or by using estimated data. **SENSOR**: The consumption has been calculated with data from sensors. **EMPTY**: No consumption is calculated. enum: - REAL - ESTIMATED - SENSOR - EMPTY aggregated: type: boolean description: >- Indicates if the consumption has been calculated by aggregating at least 2 points of load curve data. usingLoadCurve: type: boolean description: >- Indicates whether consumption is calculated using load curve data to calculate interpolation weights and/or by aggregating load curve data. required: - aggregated - energyMeter - indexNatures - nature - period - quality - status - usingLoadCurve 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 ConsumptionCostDto: description: Is not returned if withoutCost filter is selected in the request. 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: - standingCharge - total ConsumptionCarbonFootprintDto: description: Is returned if withCarbonFootprint filter is selected in the request. 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. ````