# French commune population & density (INSEE) (`donnees-france/french-commune-population`) Actor

Get official population, area, density, EPCI and coordinates for French communes (INSEE data). Query by commune code, department, postal code or name, and get the total population of your selection. Open data, no API key.

- **URL**: https://apify.com/donnees-france/french-commune-population.md
- **Developed by:** [Données France](https://apify.com/donnees-france) (community)
- **Security:** Limited permissions
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $10.00 / 1,000 commune delivereds

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

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

## French commune population & density (INSEE)

Get official **population, area, density, intermunicipality (EPCI) and
coordinates** for French communes, and the **total population of your
selection** in one run. Open data, no API key, no login.

### Why this is useful

Sizing a market in France almost always comes down to one question: *how many
people live where I sell?* This Actor answers it for any set of communes,
departments or postal codes, and returns the aggregate (total population,
median, average density) as a summary record.

Typical uses:

- sizing a local market before opening or expanding
- weighting a prospect list by population (pair it with the SIRENE Actors)
- building a pricing grid by commune size
- enriching a CRM with population and density per postcode

### What you get per commune

- INSEE code, name
- **population** (INSEE municipal population)
- **area** in km², **density** in inhabitants per km² (computed)
- postal code(s), department, region
- EPCI (intermunicipality) code and name
- centre latitude and longitude

Plus a **summary** record: number of communes, total population, median
population, total area, average density.

### Input

| Input | Purpose |
|---|---|
| `departments` | whole department at once (`69`, `2A`, `971`) |
| `communes` | specific INSEE codes (`69123` = Lyon) |
| `postalCodes` | one request per postal code (a postcode can cover several communes) |
| `nameSearch` | fuzzy name search (`Villeurbanne`) |
| `minPopulation` / `maxPopulation` | keep only communes inside a size band |
| `includeEpci`, `includeCentre` | turn optional fields off |
| `maxResults` | hard spending cap |

### Notes on the data

- Source: the official French administrative API (Etalab), which republishes
  **INSEE municipal population**.
- The API response carries **no vintage year**. If the exact vintage matters for
  your use case, check the date on insee.fr: the figures are the latest
  municipal population published, but this Actor cannot assert which year.
- `surface` is provided in hectares by the source and converted to **km²** here
  (a common source of 100× errors when consumers do it themselves).
- Population filtering is done inside the Actor: the upstream API silently
  ignores its own `minPopulation` parameter.

### Related Actors

- [French B2B prospect builder (SIRENE)](https://apify.com/donnees-france/sirene-prospect-builder) — companies by activity and department
- [French company enricher (SIREN / SIRET)](https://apify.com/donnees-france/sirene-company-enricher) — full company file per SIREN
- [French public tenders watcher (BOAMP)](https://apify.com/donnees-france/boamp-tenders-watcher) — public procurement feed
- [French company events & fresh leads (BODACC)](https://apify.com/donnees-france/bodacc-company-events) — new registrations and insolvency proceedings

# Actor input Schema

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

Codes département (ex. 69, 2A, 971). Une requête par département, plusieurs centaines de communes par appel.

## `communes` (type: `array`):

Codes à 5 caractères (ex. 69123 pour Lyon, 2A004 pour Ajaccio). Les codes inconnus sont renvoyés en ligne d'erreur.

## `postalCodes` (type: `array`):

Codes postaux à 5 chiffres. Attention : un code postal peut couvrir plusieurs communes.

## `nameSearch` (type: `string`):

Nom de commune, même partiel (ex. Villeurbanne). Laissez vide pour ne pas filtrer par nom.

## `minPopulation` (type: `integer`):

Écarte les communes sous ce seuil. Le filtrage est appliqué ici : l'API officielle ignore ce paramètre.

## `maxPopulation` (type: `integer`):

Écarte les communes au-dessus de ce seuil.

## `includeEpci` (type: `boolean`):

Code et nom de l'EPCI de rattachement.

## `includeCentre` (type: `boolean`):

Latitude et longitude du centre de la commune.

## `maxResults` (type: `integer`):

Plafond de dépense : chaque commune livrée est facturée.

## Actor input object example

```json
{
  "departments": [
    "69"
  ],
  "includeEpci": true,
  "includeCentre": true,
  "maxResults": 100
}
```

# Actor output Schema

## `communes` (type: `string`):

Commune records: INSEE code, name, population (INSEE municipal population), area in km2, density in inhabitants per km2, postal codes, department, region, EPCI code and name, centre latitude and longitude. Unknown codes are returned as explicit error items.

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

JSON summary of the selection: number of communes, total and median population, total area, average density, number of codes not found. This is the market-sizing figure.

# 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 = {
    "departments": [
        "69"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("donnees-france/french-commune-population").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 = { "departments": ["69"] }

# Run the Actor and wait for it to finish
run = client.actor("donnees-france/french-commune-population").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 '{
  "departments": [
    "69"
  ]
}' |
apify call donnees-france/french-commune-population --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,donnees-france/french-commune-population"
        }
    }
}
```

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/UbqebBinb2Dyzv3AI/builds/WCvzHzwoVOVTFq66K/openapi.json