# France DPE by commune: energy labels & hogs (`westbrook_data/dpe-france-communes`) Actor

French energy performance (DPE) statistics per commune: labels A to G, energy hogs F and G, building types, periods. No addresses. / Statistiques DPE par commune, sans adresse.

- **URL**: https://apify.com/westbrook_data/dpe-france-communes.md
- **Developed by:** [Lucas Rincent](https://apify.com/westbrook_data) (community)
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $14.00 / 1,000 commune dpe statistics

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## France DPE by commune: energy labels & energy hogs / DPE par commune

Get the energy performance (DPE) profile of French communes: number of diagnostics per label **A to G**, the share of **energy hogs (F and G, "passoires thermiques")**, and the split by building type and construction period. Computed from the official ADEME open dataset, **without any address or identity**. Independent tool, unaffiliated with ADEME.

Obtenez le profil DPE de communes françaises : nombre de diagnostics par étiquette **A à G**, part des **passoires thermiques (F et G)**, répartition par type de bâtiment et période de construction. Calculé sur le jeu de données ouvert de l'ADEME, **sans adresse ni identité**. Outil indépendant, sans affiliation à l'ADEME.

### Try it / Essayer

Offline synthetic demo: one row marked `isDemo: true`, no network, no charge. / Démo fictive : une ligne `isDemo: true`, sans réseau ni facturation.

```json
{"mode":"demo"}
```

Live statistics for three communes, diagnostics since 2024 / Statistiques réelles pour trois communes depuis 2024 :

```json
{"mode":"live","communeCodes":["59350","75101","13201"],"sinceYear":2024}
```

Whole department / Un département entier : `{"mode":"live","departments":["59"],"sinceYear":2025}`. Files / Fichiers : `examples/`.

### Output / Sortie

One row per commune: `communeCode`, `communeName`, `totalDiagnostics`, `byLabel` (A to G: `count`, `share`), `withoutLabel`, `energyHogs` (`count`, `share`), `byBuildingType` (maison, appartement, immeuble: `total`, `energyHogs`, `energyHogShare`), `byConstructionPeriod` (chronological), `datasetUpdatedAt`, `source`, `sourceApiUrl`, `fetchedAt`, `isDemo`, `attribution`. Shares are fractions from 0 to 1. Export JSON, CSV or Excel through Apify.

`SUMMARY` (key-value store): communes requested, processed and delivered, `empty` (no diagnostic), `belowThreshold`, invalid codes, duplicates, `datasetUpdatedAt`, budget limits, status, and `complete: false` for failed or aborted runs.

### Read this before using the numbers / À lire avant d'utiliser les chiffres

- **Diagnostics, not dwellings.** A dwelling diagnosed several times counts several times; the source holds every DPE established since July 2021. / **Des diagnostics, pas des logements.** Un logement diagnostiqué plusieurs fois compte plusieurs fois.
- The data covers only dwellings that had a diagnostic (sales, rentals, new builds), so it is **not a census of the housing stock**. Labels are declared by diagnosticians. / Seuls les logements diagnostiqués sont comptés : ce n'est **pas un recensement du parc**.
- **Paris, Lyon, Marseille: use arrondissement codes** (75101 to 75120, 69381 to 69389, 13201 to 13216). A city code returns no diagnostics; department mode adds the arrondissements for you. / Utilisez les codes d'arrondissement ; le mode département les ajoute.
- Communes with **fewer than 10 diagnostics** are not delivered (listed in `belowThreshold`, not charged) to avoid describing individual dwellings. / Les communes de moins de 10 diagnostics ne sont pas livrées (listées, non facturées).
- Data are refreshed weekly by ADEME; `datasetUpdatedAt` tells you the version used. Not a valuation, not legal or energy advice. / Mise à jour hebdomadaire ; pas une estimation ni un conseil.

### Billing and limits / Facturation et limites

- One result event per **returned commune row**. Empty communes, communes below the threshold, invalid codes and duplicates produce **no row and no charge**. The demo has no result event. See the Pricing tab for the current price. Your spending limit is applied as the run goes (`limitedByBudget`, `skippedByBudget`). / Un événement par **commune livrée** ; vides, sous le seuil, invalides et doublons : aucune ligne, aucune facturation.
- Up to 500 codes and 5 departments, 1,000 communes per run, about 3 official requests per commune (roughly 2 seconds each). / 1 000 communes au plus par run.
- If the official service fails after retries, the run **fails explicitly**; delivered rows stay valid and `SUMMARY` says how far it went. A rerun cannot resume: remove the communes already delivered. / En cas de panne, le run échoue explicitement ; retirez les communes déjà livrées avant de relancer.
- Source: ADEME, "DPE Logements existants (depuis juillet 2021)", Licence Ouverte 2.0; attribution included in each row. Commune list: geo.api.gouv.fr (departments only). / Source ADEME, Licence Ouverte 2.0.

### Privacy / Données personnelles

Only counts per commune are exported: no street, number, building, coordinates, owner or diagnostician. The dataset itself contains address-level lines; this Actor never outputs them. / Seuls des comptes par commune sont exportés ; jamais d'adresse, de numéro, de coordonnées ni de propriétaire.

### MCP and n8n / MCP et n8n

Run with Apify's MCP server or API using the input above and read `get-dataset-items`. In n8n, use "Run Actor and get dataset", then filter on `energyHogs.share`. Keep the Apify token in your client's credentials, never in the input. / Gardez le jeton Apify dans les credentials du client.

# Actor input Schema

## `mode` (type: `string`):

Demo: one synthetic row, no network, no result charge. Live: official ADEME data. / Démo : une ligne fictive, sans réseau ni événement facturé. Réel : données officielles ADEME.

## `communeCodes` (type: `array`):

Up to 500 five-character INSEE codes (59350 for Lille, 2A004 for Ajaccio). For Paris, Lyon and Marseille use the arrondissement codes (75101, 69381, 13201); a city code returns nothing. Invalid codes and duplicates are listed in SUMMARY, never charged. / Jusqu'à 500 codes INSEE à cinq caractères (59350 pour Lille, 2A004 pour Ajaccio). Pour Paris, Lyon et Marseille, utilisez les codes d'arrondissement (75101, 69381, 13201) ; le code de la ville ne renvoie rien. Codes invalides et doublons listés dans SUMMARY, jamais facturés.

## `departments` (type: `array`):

Up to 5 department codes (59, 2A, 971): every commune of the department is added (Paris, Lyon and Marseille by arrondissement). At most 1,000 communes per run in total. / Jusqu'à 5 codes de département (59, 2A, 971) : toutes les communes du département sont ajoutées (Paris, Lyon et Marseille par arrondissement). 1 000 communes au plus par run.

## `sinceYear` (type: `integer`):

Keeps only diagnostics established from January 1 of this year (2021 to current year). Empty: all diagnostics since July 2021. / Ne garde que les diagnostics établis depuis le 1er janvier de cette année (2021 à l'année en cours). Vide : tous les diagnostics depuis juillet 2021.

## Actor input object example

```json
{
  "mode": "demo",
  "communeCodes": [],
  "departments": []
}
```

# Actor output Schema

## `results` (type: `string`):

DPE counts per commune; isDemo identifies synthetic data. / Comptes DPE par commune ; isDemo identifie toute donnée fictive.

## `summary` (type: `string`):

Communes processed, empty, below the disclosure threshold, budget limits, dataset date and status. / Communes traitées, vides, sous le seuil de diffusion, limites de budget, date du jeu de données et statut.

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {};

// Run the Actor and wait for it to finish
const run = await client.actor("westbrook_data/dpe-france-communes").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {}

# Run the Actor and wait for it to finish
run = client.actor("westbrook_data/dpe-france-communes").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{}' |
apify call westbrook_data/dpe-france-communes --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,westbrook_data/dpe-france-communes"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/LdSNh60b26xTkkRHV/builds/U5Yx9bvu4S5DOn1Qb/openapi.json