PyGazpar

PyGazpar is a Python library for getting natural gas consumption from GrDF French provider.

Their natural gas meter is called Gazpar. It is wireless and transmit the gas consumption once per day.

All consumption data is available on the client account at GrDF Web Site (https://monespace.grdf.fr).

PyGazpar automatically goes through the Web Site and download the consumption data, and make it available in a Python structure.

Installation

Requirements

PyGazpar does not require Selenium and corresponding geckodriver to work.

With the new GrDF web site, it is possible to load the consumption data far easily than before.

PyGazpar uses Poetry for dependency and package management.

Create your virtual environment

$ cd /path/to/my_project_folder/

$ poetry install

PyGazpar installation

Use the package manager pip to install PyGazpar.

pip install pygazpar

You can also download the source code and install it manually.

cd /path/to/pygazpar/

$ poetry install

Usage

Command line:

Credentials can be omitted from the command line. PyGazpar then reads GRDF_USERNAME, GRDF_PASSWORD and PCE_IDENTIFIER from the environment, or from a .env file in the working directory. Command line options take precedence. A PCE identifier is a 14-digit number; the examples use 12345678901234 as a dummy value.

For the raw datasources, the version banner goes to stderr, so stdout only contains the JSON payload.

1. Standard usage (using Json GrDF API).

$ pygazpar -u 'your login' -p 'your password' -c '12345678901234' --datasource 'json'

2. Alternate usage (using Excel GrDF document).

$ pygazpar -u 'your login' -p 'your password' -c '12345678901234' -t 'temporary directory where to store Excel file (ex: /tmp)' --datasource 'excel'

3. Test usage (using local static data files, do not connect to GrDF site).

$ pygazpar -u 'your login' -p 'your password' -c '12345678901234' --datasource 'test'

4. Raw usage (output the GrDF API response as received, without PyGazpar post processing; --frequency is ignored).

# Consumption (informative data by default, use --consumption-type PUBLISHED for published data)
$ pygazpar -u 'your login' -p 'your password' -c '12345678901234' --datasource 'raw-consumption'
$ pygazpar -u 'your login' -p 'your password' -c '12345678901234' --datasource 'raw-consumption' --consumption-type 'PUBLISHED'

# Temperatures (meteo)
$ pygazpar -u 'your login' -p 'your password' -c '12345678901234' --datasource 'raw-temperature'

Library:

1. Standard usage (using Json GrDF API).

import pygazpar

client = pygazpar.Client(pygazpar.JsonWebDataSource(
    username='your login',
    password='your password')
)

# Returns the list of your PCE identifiers attached to your account.
pce_identifiers = client.get_pce_identifiers()

# Returns the daily and monthly consumptions for the last 60 days on your PCE identifier.
data = client.load_since(pce_identifier='12345678901234',
                        last_n_days=60,
                        frequencies=[pygazpar.Frequency.DAILY, pygazpar.Frequency.MONTHLY])

See samples/jsonSample.py file for the full example.

By default, JsonWebDataSource requests GrDF's informative consumption readings. Some PCE identifiers do not expose any (or only the latest) history through that endpoint, while a longer history remains available as published consumption on the GrDF customer portal. In that case, pass consumption_type=pygazpar.ConsumptionType.PUBLISHED to read from the published readings instead:

import pygazpar

client = pygazpar.Client(pygazpar.JsonWebDataSource(
    username='your login',
    password='your password',
    consumption_type=pygazpar.ConsumptionType.PUBLISHED)
)

A published reading covers a period of several days. PyGazpar spreads its volume evenly across the days of the period, and its energy in proportion to that volume, so the totals match GrDF's publication. A day's energy can differ from its volume times the coefficient by a little more than 1 kWh, because of whole-kWh rounding and small differences in the publication itself. The indexes of those days are interpolated, and their type is Calculé, meaning calculated rather than measured. The rules and examples are in Published readings: period computation.

2. Alternate usage (using Excel GrDF document).

import pygazpar

client = pygazpar.Client(pygazpar.ExcelWebDataSource(
    username='your login',
    password='your password')
)

# Returns the list of your PCE identifiers attached to your account.
pce_identifiers = client.get_pce_identifiers()

# Returns the daily and monthly consumptions for the last 60 days on your PCE identifier.
data = client.load_since(pce_identifier='12345678901234',
                        last_n_days=60,
                        frequencies=[pygazpar.Frequency.DAILY, pygazpar.Frequency.MONTHLY])

See samples/excelSample.py file for the full example.

3. Test usage (using local static data files, do not connect to GrDF site).

import pygazpar

client = pygazpar.Client(pygazpar.TestDataSource())

data = client.load_since(pce_identifier='12345678901234',
                        last_n_days=10,
                        frequencies=[pygazpar.Frequency.DAILY, Frequency.MONTHLY])

See samples/testSample.py file for the full example.

Typed readings:

load_readings_since and load_readings_date_range return the models instead of dicts, so the fields are attributes with their types:

import pygazpar

client = pygazpar.Client(pygazpar.JsonWebDataSource(username='your login', password='your password'))

readings = client.load_readings_since(pce_identifier='12345678901234', last_n_days=60,
                                      frequencies=[pygazpar.Frequency.DAILY])
for reading in readings[pygazpar.Frequency.DAILY.value]:
    print(reading.start_date, reading.volume_m3, reading.energy_kwh)

If the PCE identifier is not one of the PCEs of the account, the web sources raise pygazpar.datasource.UnknownPceError (a ServerError) instead of returning no data. A PCE of the account that has no data for the period returns no readings.

Raw sources:

The raw sources return the GrDF API responses as received, without PyGazpar's post processing:

from datetime import date, timedelta

import pygazpar

end_date = date.today()
start_date = end_date - timedelta(days=30)

consumption = pygazpar.RawConsumptionWebDataSource(
    'your login', 'your password', pygazpar.ConsumptionType.PUBLISHED
).load('12345678901234', start_date, end_date)

temperatures = pygazpar.RawTemperatureWebDataSource(
    'your login', 'your password'
).load('12345678901234', start_date, end_date)

consumption is the consumption response and temperatures is the meteo response. Both are dictionaries, as returned by GrDF.

Output:

data =>
{
  "daily": [
    {
      "start_date": "2022-10-13",
      "end_date": "2022-10-14",
      "frequency": "daily",
      "time_period": "13/10/2022",
      "start_index_m3": 15724,
      "end_index_m3": 15725,
      "volume_m3": 2,
      "energy_kwh": 17,
      "timestamp": "2022-12-13T23:58:35.606763",
      "converter_factor_kwh/m3": 11.16,
      "temperature_degC": null,
      "type": "Mesur\u00e9"
    },
    ...
    {
      "start_date": "2022-12-11",
      "end_date": "2022-12-12",
      "frequency": "daily",
      "time_period": "11/12/2022",
      "start_index_m3": 16081,
      "end_index_m3": 16098,
      "volume_m3": 18,
      "energy_kwh": 201,
      "timestamp": "2022-12-13T23:58:35.606763",
      "converter_factor_kwh/m3": 11.27,
      "temperature_degC": -1.47,
      "type": "Mesur\u00e9"
    }
  ],
  "monthly": [
    {
      "start_date": "2022-11-01",
      "end_date": "2022-12-01",
      "frequency": "monthly",
      "time_period": "Novembre 2022",
      "start_index_m3": 15750,
      "end_index_m3": 15950,
      "volume_m3": 204,
      "energy_kwh": 2227,
      "timestamp": "2022-12-13T23:58:35.606763"
    },
    {
      "start_date": "2022-12-01",
      "end_date": "2023-01-01",
      "frequency": "monthly",
      "time_period": "D\u00e9cembre 2022",
      "start_index_m3": 15950,
      "end_index_m3": 16098,
      "volume_m3": 148,
      "energy_kwh": 1664,
      "timestamp": "2022-12-13T23:58:35.606763"
    }
  ]
}

Output fields:

The type values are:

Data model:

The readings are models, shared by the parser, the converters and the Excel and test datasources. load_since and load_date_range return them in the dict form shown above, and load_readings_since and load_readings_date_range return the models.

• PeriodReading covers a period of any frequency: start_date (included), end_date (excluded), the frequency, the time period label, the indexes, the volume, the energy and the timestamp.
• DailyReading adds the converter factor, the temperature and the GrDF type of the day.

The rules are checked when a reading is built:

• A period lies inside one bucket of its frequency: a day, a week from Monday to Sunday (a partial first or last week keeps the days it covers), a calendar month or a calendar year.
• The time_period label is computed from the dates. A label given by a source must match the dates.
• A GrDF record is checked when it is read. A published period must give its indexes, volume, energy and coefficient, and negative consumption or an empty period is refused. An invalid record is skipped with a warning.
• A GrDF response is checked as it arrives. A malformed response raises an error that names the field at fault.
• An Excel file gives the dates through its labels, and an empty cell stays empty.

Temperatures:

Temperatures come from GrDF's meteo data. PyGazpar asks for the period ending yesterday at the latest, and for 10 to 730 days, to avoid HTTP 500 errors. For the json datasource, a failed meteo request is not an error: the temperatures are null. The raw-temperature datasource raises the error instead.

Each daily row takes its temperature as follows:

• A record that covers exactly one day, such as an informative reading, keeps GrDF's own temperature when it has one. Otherwise, the day takes its meteo value.
• A record that covers several days, such as a published period, never gives its temperature to each day. Each day takes its meteo value, or stays empty when meteo has none.
• A gap day takes its meteo value.

# Informative reading (journeeGaziere is set)
temperature = releve["temperature"]
if temperature is None:
    temperature = meteo.get(reading_date)

# Published period (journeeGaziere is null): the period's own temperature is ignored
temperature = meteo.get(day)

Published readings: period computation

GrDF publishes some consumption as periods rather than days. A published reading gives the volume and energy used between dateDebutReleve and dateFinReleve, and the indexes at both ends. PyGazpar turns each period into one row per calendar day, so published and informative data share the same daily model.

Steps

For a period from dateDebutReleve (included) to dateFinReleve (excluded), with days calendar days between them, V the published volume, E the published energy, and indexDebut and indexFin the published indexes:

1. Days. The dates are read as written, with no time zone conversion. GrDF's 06:00 UTC timestamps fall on the same calendar day in France.
2. Volume is the reference. It is split in whole units of its published precision: bounds b_i = V × i ÷ days (integer division, in those units), so day i gets b_(i+1) − b_i units. For whole m³ data, each day gets either ⌊V ÷ days⌋ or ⌈V ÷ days⌉ m³.
3. Energy follows the volume. It is split the same way, in units of its own published precision, with bounds e_i = E × b_i ÷ V, so day i gets e_(i+1) − e_i units. A period with no volume has its energy spread evenly over the days instead.
4. Indexes are interpolated: start_j = indexDebut + (indexFin − indexDebut) × j ÷ days. The end of a day is the start of the next day.
5. Temperature of each day comes from the meteo data. The period's own temperature is not used.
6. Type is Calculé, and converter_factor_kwh/m3 is the period's coeffConversion.
7. Gaps between two periods are rebuilt as a derived period, and so are the informative days without data (Absence de Données) between two known indexes. The volume is the index difference between the end of the previous period and the start of the next one. The energy is that volume times the average of the two coefficients, rounded to whole kWh. When the dates or the indexes cannot be used, nothing is filled, and PyGazpar logs a warning.

Integer division works on whole units, so the parts never drift from the total, and each part is written back with the decimal places of its published total. For example, 10.3 m³ gives parts of 3.4, 3.4 and 3.5 m³. The bounds start at 0 and end at the period total, so the daily differences add up to the published totals exactly.

Examples

1. Three-day period

Volume 10 m³, energy 100 kWh, indexes 100 → 110, from 1 January to 4 January 2026.

The volume bounds are 0, 3, 6 and 10, so the days get 3, 3 and 4 m³. Energy follows: 100 × (0, 3, 6, 10) ÷ 10 gives 0, 30, 60 and 100, so the days get 30, 30 and 40 kWh. The indexes are 100, 103, 106 and 110.

2. Rounding

Volume 7 m³, energy 50 kWh over 3 days, indexes 1000 → 1007, coefficient 7.14.

Volume gives 2, 2 and 3 m³. Energy gives 50 × (0, 2, 4, 7) ÷ 7 = 0, 14, 28, 50, so 14, 14 and 22 kWh. The exact shares are 14.29, 14.29 and 21.43 kWh, so every day is within 1 kWh of its share. The totals are still exactly 7 m³ and 50 kWh.

3. Temperature per day

Volume 4 m³, energy 40 kWh, indexes 100 → 104, from 1 January to 3 January 2026. The meteo data has 5.5 °C for 2 January only.

Each day takes its own meteo value. Day 1 has none, so its temperature is null.

4. No volume

A period with zero volume and zero energy keeps one row per day, so the days stay visible.

5. Empty period

When dateDebutReleve equals dateFinReleve, or either date is missing, the period produces no rows. A warning is written to the log.

6. Informative readings are unchanged

A reading with a journeeGaziere date is already one day. It keeps GrDF's own type.

7. A two-day period from the sample

From 1 to 3 December 2019: volume 29 m³, energy 323 kWh, coefficient 11.12, indexes 10380 → 10409.

The exact energy shares are 155.9 and 167.1 kWh. Against the coefficient, the first day is 0.7 kWh off and the second is 1.2 kWh off. That second gap is in the publication: its energy is 0.5 kWh above 29 × 11.12.

8. The first period in the sample

From 10 October 2017 to 9 April 2018 (181 days): volume 2025 m³, energy 22417 kWh, indexes 5089 → 7114. The first two days:

Each day gets 11 m³ or 12 m³ over the 181 days, and the energy of the whole period is 22417 kWh.

9. A gap in the publication

Between the period ending on 3 October 2019 and the one starting on 3 November 2019, the publication has no records. The meter indexes still show that 107 m³ were used (10,103 − 9,996). The gap is rebuilt as a period: its volume is that index difference, and its energy is that volume times the average of the two neighbouring coefficients, (11.2 + 11.12) ÷ 2 = 11.16. So the energy is 1,194 kWh.

10. Decimal values

Volume 10.3 m³, energy 100.5 kWh, indexes 100 → 110.3, from 1 January to 4 January 2026. Each total is split in its own precision, so the parts keep one decimal place.

The volumes sum to 10.3 m³ and the energies to 100.5 kWh. The energies follow the volumes, so each day is within 0.1 kWh of its share.

Invariants

These are the rules the code enforces, and what the sample shows for each.

Invariants 6 and 9 depend on what GrDF publishes, so they are not guaranteed for every period. The code keeps each period's totals exact in all cases.

Tests for the invariants

Gaps between periods: test_gap_between_published_periods_is_rebuilt_from_the_indexes and test_synthetic_gap_is_rebuilt_from_the_index_difference. Days without data: test_informative_day_without_data_is_rebuilt_from_the_indexes and test_informative_day_without_data_at_the_start_stays_without_data.

Periods with no days, or without dates, produce no rows: test_published_period_without_days_is_ignored and test_readings_without_any_date_are_ignored.

Weekly, monthly and yearly buckets

The weekly, monthly and yearly outputs group the daily rows and keep only complete buckets: at least 7 days for a week, 28 days for a month and 360 days for a year. The last bucket is always kept, even when it is incomplete. An incomplete first bucket is dropped.

Weeks run from Monday to Sunday, on the calendar. The week of 30 December 2019 to 5 January 2020 is one week, even though it crosses the new year. Months and years are calendar months and calendar years.

For example, daily data from 20 January to 15 February 2026 at 1 m³ per day gives 27 m³ in total. The monthly output is:

January has only 12 days, so it is dropped, and the output totals 15 m³ rather than 27 m³. See Known exceptions.

Known exceptions

• Gap energy: the energy of a gap is an estimate: its volume times the average of the two neighbouring coefficients. In the sample, the coefficients are 11.2 and 11.12, so the estimate is 1,194 kWh.
• Informative readings: GrDF's own data does not always satisfy invariants 6 and 9. In the sample, the index difference differs from the volume in 244 of 1,096 rows, and energy differs from volume × coeffConversion by up to 6 kWh. PyGazpar passes these values through and does not correct them.
• Totals at weekly, monthly and yearly frequencies: these outputs keep only complete buckets, so their totals can be lower than the daily total. In the sample, the yearly total is 9,736 m³ against 10,664 m³ daily, because 2017 is incomplete (see Weekly, monthly and yearly buckets).

Limitation

PyGazpar relies on how GrDF Web Site is built.

Any change in the Web site may break this library.

We expect in close Future that GrDF makes available an open API from which we can get safely their data.

Contributing

Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.

Please make sure to update tests as appropriate.

License

MIT

Project status

PyGazpar has been initiated for integration with Home Assistant.

Corresponding Home Assistant integration custom component is available here.