> ## 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 gas 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/gas/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/gas/consumptions: get: tags: - Gas energy consumptions summary: Consumptions description: > The service returns the gas 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: getGasComputedConsumption 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. required: true schema: type: string format: date-time example: '2021-12-31T23:00:00Z' - name: endTs in: query description: >- The ending timestamp (excluded) until which to calculate the consumption. required: true schema: type: string format: date-time example: '2022-12-31T23:00:00Z' - 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 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: 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. style: form explode: true required: false schema: type: array items: type: string enum: - withoutCost - withGlobalConsumption responses: '200': description: 'OK - return computed Consumptions for site-id ' content: application/json: schema: $ref: '#/components/schemas/GasComputedConsumptions' example: period: startTime: '2025-04-01T00:00:00+02:00' endTime: '2025-05-01T00:00:00+02:00' step: P1D units: cost: EUR energyMeter: KWH rawEnergyMeter: M3 consumptions: - period: startTime: '2025-04-01T00:00:00+02:00' endTime: '2025-04-02T00:00:00+02:00' energyMeter: total: 32.61177 byTariffHeading: BASE: 32.61177 conversionFactor: 10.87059 rawEnergyMeter: total: 3 cost: total: 2.95630217316129 standingCharge: 0.7908806451612903 byTariffHeading: BASE: 2.165421528 quality: 1 indexNatures: [] status: COMPLETE nature: REAL globalConsumption: period: startTime: '2025-04-01T00:00:00+02:00' endTime: '2025-05-01T00:00:00+02:00' energyMeter: total: 1369.69434 conversionFactor: 10.87059 rawEnergyMeter: total: 126 cost: total: 115.43864148782795 standingCharge: 24.490937311827956 quality: 1 status: COMPLETE nature: REAL '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 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 gas 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: GasComputedConsumptions: 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/GasComputedConsumptionsUnitsDto' consumptions: type: array items: $ref: '#/components/schemas/GasConsumptionDto' globalConsumption: $ref: '#/components/schemas/GasGlobalConsumptionDto' 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 GasComputedConsumptionsUnitsDto: properties: cost: type: string format: ISO-4217 description: Is not returned if withoutCost filter is selected in the request. energyMeter: type: string rawEnergyMeter: type: string required: - energyMeter GasConsumptionDto: properties: period: $ref: '#/components/schemas/ConsumptionPeriodDto' energyMeter: $ref: '#/components/schemas/GasConsumptionEnergyMeterDto' rawEnergyMeter: $ref: '#/components/schemas/ConsumptionRawEnergyMeterDto' cost: $ref: '#/components/schemas/ConsumptionCostDto' 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. items: type: string enum: - BAD_INDEX_INFORMATION_OR_CONTRACT_CHANGE_MISSING 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 - MES - EST - COR - DISTRIBUTEUR - DISTRIBUTEUR_INVALIDE - INTERPOLATED - RELEVE_CONFIANCE - RELEVE_CONFIANCE_INVALIDE - SCORE_RC_ACQUITTE - SCORE_RC_INVALIDE - SCORE_RC - SCORE_ACQUITTE - SCORE_INVALIDE_ACP - SCORE_INVALIDE_EDE - SCORE - SCORE_INVALIDE_USER - SUIVI_CONSO - SUIVI_CONSO_INVALIDE - ESTI_ACC - ESTI_ACC_INVALIDE - ESTI_EDELIA 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 required: - indexNatures - nature - period - quality - status GasGlobalConsumptionDto: 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/GasConsumptionEnergyMeterDto' cost: $ref: '#/components/schemas/ConsumptionCostDto' 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. items: type: string enum: - BAD_INDEX_INFORMATION_OR_CONTRACT_CHANGE_MISSING 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 - MES - EST - COR - DISTRIBUTEUR - DISTRIBUTEUR_INVALIDE - INTERPOLATED - RELEVE_CONFIANCE - RELEVE_CONFIANCE_INVALIDE - SCORE_RC_ACQUITTE - SCORE_RC_INVALIDE - SCORE_RC - SCORE_ACQUITTE - SCORE_INVALIDE_ACP - SCORE_INVALIDE_EDE - SCORE - SCORE_INVALIDE_USER - SUIVI_CONSO - SUIVI_CONSO_INVALIDE - ESTI_ACC - ESTI_ACC_INVALIDE - ESTI_EDELIA 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 required: - indexNatures - nature - period - quality - status 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 GasConsumptionEnergyMeterDto: properties: total: type: number description: Total of the energy consumption. byTariffHeading: type: object additionalProperties: type: number description: Energy consumption broken down by tariff headings. conversionFactor: type: number description: Conversion Factor required: - conversionFactor - total ConsumptionRawEnergyMeterDto: type: object properties: total: type: number description: Total of the raw energy consumption. required: - 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 ````