Carburants France

Features

• Official data from the French government's live feed, no API key, one request for all your stations
• Station search in the configuration form: around your home (adjustable radius), by postcode, town, department or station id, with the prices shown to help you choose
• Choice of the fuels to follow: Gazole (diesel), SP95, SP98, E10, E85, GPLc (LPG)
• Per station and per fuel: a Price sensor (€/L, with history) and an In stock binary sensor (temporary or permanent shortage, with its start date)
• Per fuel: a Best price sensor across your stations, with the station and the 30-day trend (average, lowest, highest, today's difference) as attributes
• Per fuel: a Target price to set yourself and a Low price binary sensor, on while the best price is at or below it — an automation trigger that needs no template
• Full tank cost per fuel at the best price, from a Tank capacity you set once, and a carburants_france_price_drop event each time a best price goes down by a cent or more
• Brand and logo of each station: 42 French networks' logos built in, the others found automatically through OpenStreetMap and Wikidata
• carburants_france.refresh action to force an update
• custom:carburants-france-card card, shipped with the integration and loaded automatically: logos, prices, shortages, best price in green, live opening status, opening hours, services and directions on click
• custom:carburants-france-mini-card mini card: the cheapest price of one fuel and the station selling it on one line, with a button that shows the full list card
• custom:carburants-france-map-card map card: your stations on a map, with the logo and the price of a fuel on each marker, your home, and the station details on click; Locate me button to see the stations around you (radius picked in the title) and search by town, without adding them to the integration
• Add or remove stations and fuels at any time from the options
• Diagnostics download (Settings > Devices & services), with positions and addresses redacted
• English, French, German, Spanish, Italian, Dutch, Portuguese (European), Polish, Romanian, Danish, Swedish, Bulgarian, Russian, Ukrainian, Hungarian, Slovak, Czech, Slovenian, Latvian, Greek and Serbian (Cyrillic and Latin)

Prerequisites

• Home Assistant 2024.12 or later
• No account or API key: the data is public (data.economie.gouv.fr)
• Your home location set in Home Assistant, for the search around your home and the distances

Configuration

Integration#

Settings → Devices & services → Add integration → Carburants France, then:

1. Name and fuels: give a name ("Fuel", "Work"…) and tick the fuels to follow.
2. Search: leave empty to search around your home within the chosen radius, or enter a postcode (35000), a town (Rennes), a department (35) or a station id (35000013).
3. Stations: tick the stations to follow. Each line shows the brand, the address, the prices of the chosen fuels (✕ when out of stock) and the distance. Tick New search to add stations elsewhere: the selection is kept.

Options (Configure button):

Several entries are possible, for example one around your home and one along your commute.

Entities#

Each station is a device, named after its brand and town (can be renamed in Home Assistant). Entity ids follow the language of Home Assistant when the entities are created; the examples below are for English (the French variant is in parentheses).

A fuel in permanent shortage (no longer sold) has no entity, nor has a fuel that is not followed.

The feed sometimes publishes neither a price nor a shortage for a fuel, usually right after a shortage ends, before a new price is entered. The fuel then shows No price, with an unknown price and availability, until the next published price.

Card#

Add the Carburants France card from the card picker: every option is set in the visual editor. In YAML:

type: custom:carburants-france-card

Click a station to see its weekly opening hours, its services and a directions button. One station is expanded at a time; a click outside the card collapses it and hides the out-of-stock stations again.

Stations where every fuel shown is out of stock are hidden: the Show the out of stock stations button at the bottom of the card brings them back.

When the Stations sensor is unavailable (feed unreachable at startup, integration reloading), with or without entity set, the card says Data unavailable instead of a station count, and the map card says so above the map; the prices come back with the next refresh. In a Sections view the list card takes at least 9 of the 12 columns, so the station names stay readable; on a narrow card the fuel tiles wrap under the station.

Mini card#

The Carburants France Mini card shows, on one line, the cheapest price of one fuel among your stations and the station selling it (with its distance). The detail button at the top right switches it to the full list card, with the same options; the button or a click outside the card brings the compact view back.

type: custom:carburants-france-mini-card
fuel: gazole

It takes every option of the list card (they apply to the full view), plus:

When the fuel is out of stock at every station, the card says so instead of a price.

Map card#

Add the Carburants France — carte card from the card picker. In YAML:

type: custom:carburants-france-map-card

Each marker shows the logo and the price: green for the best price of that fuel, orange when every followed fuel is out of stock. Click a marker to see all the prices, the opening status and the directions. The full screen button enlarges the map to the whole screen (on iPhone, where full screen is not available, it covers the page); Escape or the same button closes it.

Locate me (crosshairs button in the title) shows the stations within the radius picked next to it (5 km by default) around you: your browser's position (HTTPS or the companion app), else your person's position, else your home. The title says so, the search area is drawn and your position is marked; changing the radius searches again. The search field shows the stations of a town (or a postcode, a department) and focuses the map on that town; the cross clears it. Neither adds anything to the integration: stations you already follow keep their name and logo and are marked as followed in their popup. Clicking Locate me again, or clearing the search, brings back your followed stations.

Scroll-wheel zoom is disabled so it doesn't get in the way of scrolling the dashboard (use the buttons or pinch).

Available base maps, all without an API key:

type: custom:carburants-france-map-card
map_style: custom
tile_url: https://tiles.example.org/{z}/{x}/{y}.png
tile_attribution: © OpenStreetMap contributors

Automations#

Get notified when diesel drops below 2 € at one of your stations:

triggers:
  - trigger: numeric_state
    entity_id: sensor.carburants_best_price_gazole
    below: 2
actions:
  - action: notify.mobile_app_phone
    data:
      title: Diesel at {{ states('sensor.carburants_best_price_gazole') }} €
      message: "{{ state_attr('sensor.carburants_best_price_gazole', 'station_name') }}"

Or set Target price Gazole to 1.85 and trigger on the Low price sensor:

triggers:
  - trigger: state
    entity_id: binary_sensor.carburants_low_price_gazole
    to: "on"
actions:
  - action: notify.mobile_app_phone
    data:
      message: >
        Diesel at {{ state_attr(trigger.entity_id, 'price') }} € at {{ state_attr(trigger.entity_id, 'station_name') }}
        ({{ state_attr('sensor.carburants_best_price_gazole', 'change_30d') }} € against the month)

Or on each fall of the best price, with the carburants_france_price_drop event:

triggers:
  - trigger: event
    event_type: carburants_france_price_drop
    event_data:
      fuel: gazole
actions:
  - action: notify.mobile_app_phone
    data:
      message: >
        Diesel down {{ (trigger.event.data.drop * 100) | round(1) }} c to {{ trigger.event.data.price }} €
        at {{ trigger.event.data.station_name }}

The event fires when the best price of a followed fuel goes down by at least 0.01 €/L from its highest since the last event (a slow fall fires once it adds up to a cent). Data: entry_id, fuel (gazole, sp95, sp98, e10, e85, gplc), fuel_name, price, previous_price, drop, station_id, station_name. The first update after a restart only sets the reference.

Get notified of a shortage:

triggers:
  - trigger: state
    entity_id: binary_sensor.leclerc_rennes_gazole_in_stock
    to: "off"
actions:
  - action: notify.mobile_app_phone
    data:
      message: Diesel out of stock at Leclerc Rennes

How it works

The integration downloads the government's live feed at the update interval, in a single request for every followed station, and creates the price, availability and best-price entities from it.

Names, brands and logos#

The government feed gives neither the name nor the brand of the stations.

Name and brand come first from the community file stations_name.json of Aohzan's hass-prixcarburant project (about 9,200 stations, Apache 2.0 licence), updated every week and corrected by its users. It is downloaded at most once a week and cached. To fix or add a station for everyone, suggest a change to that file on its repository.

For stations missing from that file, the integration looks in OpenStreetMap (ref:FR:prix-carburants tag, otherwise the closest station within 300 m). If OpenStreetMap only has a generic name ("Station-service") or the brand name, the station is named after its brand and town, or failing that its address.

Name priority: custom name (Rename stations option), community file, OpenStreetMap, brand and town, address.

The logos of 42 French networks ship with the integration (frontend/brands): Leclerc, Intermarché, Carrefour, U, Auchan, Casino, Lidl, TotalEnergies, Total Access, Esso, Shell, BP, Avia, Agip… The card finds them from the brand, then from the station name ("Intermarché Cesson-Sévigné"), and uses them before the Wikidata logo, which is often missing, an old version, or the same for sister brands (Total and Total Access). The brand is also written in full on the list card and in the map card popup. Brand logos are trademarks of their owners.

The logo comes from the brand found in OpenStreetMap, through Wikidata / Wikimedia Commons. The lookup is done once, when the station is added; if OpenStreetMap can't be reached, it is retried at the next startup. Without a known logo, the card shows the brand initials.

Map#

The map card uses Leaflet and, for the ha base map, MapLibre GL with its Leaflet adapter, at the same versions as Home Assistant; everything ships with the integration, no CDN. The ha base map reuses the style served by your instance (/static/map/light.json or dark.json) and follows the light or dark theme. For the other base maps, the dark theme darkens the tiles, except aerial photos.

Data sources#

• Prices and stations: French Ministry of the Economy, live feed v2, Licence Ouverte
• Station names: hass-prixcarburant community file (Aohzan and contributors), Apache 2.0
• Brands: © OpenStreetMap contributors, ODbL
• Logos: Wikimedia Commons, through Wikidata; TotalEnergies and Total Access logos built into the cards, trademarks of TotalEnergies, used only to identify the stations
• Base maps: © OpenStreetMap contributors, OpenStreetMap France, IGN, OpenTopoMap, CyclOSM, Esri depending on the base map chosen

Support

If you find this project useful, you can support its development:

Features

• show_title and show_subtitle options (also in the visual editor) hide the stations card header's title and its subtitle (the number of stations), separately, for a card placed under a section heading of its own (asked in juju35/ha-vehicle-card#72).

Maintenance

• No code change: released again to check the installation from the Marketplace.

Features

• Tank capacity number entity (litres, set once, kept across restarts) and a Full tank sensor per fuel: what a full tank costs at the best price, with the station as attributes.
• carburants_france_price_drop event when the best price of a followed fuel goes down by at least 0.01 €/L from its highest since the last event, with the fuel, the new and previous prices, the drop and the station: a notification on each fall needs no template.

Performance

• Translations load on demand: in the release zip, the frontend files keep English only (carburants-france-card.js 210 KB → 175 KB) and each other language is its own <file>.i18n.<lang>.js file next to them, fetched the first time a card or the panel needs it. Home Assistant loads the card on every dashboard, so each page used to download and parse all 22 languages to use one. The cards and panel are defined once the page's language has arrived (a few milliseconds), so they render translated from the start.

Maintenance

• The Marketplace now installs the release zip (zip_release), like the other ha-* integrations: the split files are only in it.
• The repository keeps every language in the sources: the release runs scripts/split-frontend.mjs before building the zip, and the Validate workflow checks the split on a copy (every table is rebuilt from the split files and compared).

Fixes

• The card's cache-busting hash no longer fails on a Python built in FIPS mode, where a plain md5() is refused: it is computed with usedforsecurity=False, as in ha-parcel and ha-reverse-proxy.

Fixes

• The Target price entities stay available and settable while the fuel price feed is down.
• List and mini cards with language: auto follow a change of the Home Assistant language without a page reload.