API integration for API Géo
We build your API Géo connector
We wire geo.api.gouv.fr into your France forms: the user types a town, your system gets the INSEE code, the EPCI, the département.
- Senior product team
- public-data connectors in production
- from scoping to monitoring
What does the API Géo provide and when should you integrate it?
The API Géo gives access to France's administrative divisions: municipalities, departments, regions, EPCIs, with INSEE codes, geometries and associated data. No registration or API key required. You integrate it into an application to build a municipality selector from a postcode, filter data by territory, or display zone boundaries on a map. It is particularly useful for public sector management tools, social benefit applications, or any software that needs to reason in terms of administrative geographic boundaries.
What our clients build on API Géo
Municipality autocomplete in a funnel
INSEE code out for the whole system. boost=population, or Nantes-en-Ratier beats Nantes.
Postcode → municipalities decode
One postcode covers n municipalities, one municipality n postcodes. SIRET / delivery form: we offer the list, we do not guess.
GPS → municipality / EPCI match
A field job point lands on the right COG, so on the right eligibility rule.
A back-office territorial filter
Region, département, EPCI on stable codes, not on an Excel table that dies at the next merger.
What it changes in your France forms
Engineering in service of a measurable outcome: an INSEE code as the key, no more town = postcode.
The right municipality from the form
Paris has 21 postcodes: storing the postcode as a town id breaks on the first arrondissement. We use the INSEE code as the key; the rest of the system aligns.
No more homonyms blocking the flow
Saint-Aubin exists in ten départements. We filter by département or prioritize populated towns: the user picks the right one, without ambiguity.
Autocomplete that stays fast
Map outlines have no place on every keystroke. We load only what is needed to suggest the municipality; the map comes later, when it is useful.
Address and boundaries, each its job
API Adresse finds the street number; API Géo attaches the municipality, EPCI and département. We chain both: complete data, no confusion.
How we ship your API Géo connector
Scoping
Autocomplete, postcode decode, GPS, outlines or not. We settle fields and geometry before writing a line.
Development
Debounce, minimal fields, boost=population, local cache of the 18 regions and ~100 départements, a proxy if volume is high.
Acceptance testing
Paris 75011 → 75056, Nantes vs Nantes-en-Ratier, a homonym, a merged municipality, manual INSEE-code fallback.
Monitoring
5xx alerts, autocomplete resolution rate, COG freshness. You see a merger before the form does.
What API Géo allows
- Municipalities and arrondissements
- Search by name, postcode, INSEE code, lat/lon. Paris 75056 is a municipality; its arrondissements are too.
- EPCI, départements, regions
- Derived from the municipality code, or lists /departements/{code}/communes, /epcis/{code}/communes, /regions/{code}/communes. 18 regions observed.
- On-demand geometries
- centre, contour, mairie, bbox. Outlines are reserved for a preloaded base map, never for typing.
- HTTP cache on the server
- cache-control public, max-age=3600, immutable (observed live). We lean on it, we do not hammer the API.
The vocabulary of API Géo
- INSEE code / COG
- The municipality identifier. That is the storage key. A postcode is not one: one postcode = n municipalities, one municipality = n postcodes, Paris 21 postcodes.
- boost=population
- Name-autocomplete parameter. Without it, Nantes-en-Ratier can rank above Nantes. Observed: scores 1 vs 0.66. This is not a detail.
- fields
- On keystroke we only ask nom, code, codesPostaux, codeDepartement. Adding geometry=contour to autocomplete is an anti-pattern (34 MB at département scale).
- millésime
- COG millésime parameter (2015, 2024, 2026…). The COG moves (new municipalities). A code stored in 2017 may be delegated. We date the observation.
- EPCI
- Public establishment for inter-municipal cooperation, derivable from the municipality code (codeEpci). Eligibility rules, development tax, commercial territory.
- API Adresse vs API Géo
- Adresse geocodes a street number (BAN). Géo decodes the administrative division. Chain: BAN citycode → Géo, without calling /communes?nom= with a string already normalised.
The real constraints of API Géo
A postcode is not an identifier
Documented in the guide: a postcode from another département, multi-postcode municipalities. Storage key: INSEE code. Paris 75011 → 75056 and 21 postcodes, checked live.
Outlines in autocomplete = 34 MB
The guide sizes the gap: département without outline ~480 KB, with outline ~34 MB. A preloaded base map, never key-up.
Quota unpublished
We lean on the 3600 s cache, debounce, a proxy if volume is high, an identifiable User-Agent. We do not promise a numeric rate.
wxs.ign.fr is dead for Admin Express
Geographic guides still cite the old WFS. Dead DNS in August 2026. Alternative: data.geopf.fr / Admin Express files. Do not copy ogr2ogr snippets without replacing the host.
API Géo or API Adresse?
Two Etalab / IGN APIs often chained, rarely interchangeable.
| Criterion | API GéoAdmin division | API AdresseBAN geocoding |
|---|---|---|
| Subject | Municipality, EPCI, département, region | Street number, POI, parcel |
| Host | geo.api.gouv.fr | data.geopf.fr/geocodage |
| Output key | INSEE code (COG) | banId + citycode |
| Postcode | Decoded to n municipalities | A field of the normalised address |
| Outlines | Yes, not on keystroke | No, not its job |
| Auth | None | None in ordinary use |
| The right case | Town form / eligibility | A deliverable address |
We combine them: Adresse for the number, Géo for EPCI and region. The abstraction layer avoids calling /communes?nom= with a citycode already there.
What we measure on an API Géo integration
The other public APIs
The bricks we most often wire up alongside administrative division.
API GéoWe build your API Géo connectorThis page
API AdresseBAN geocoding: the street number, then citycode into API Géo.
Météo FranceA warning on the département taken from the municipality code, another channel.
URSSAFStats aggregated by département, once the COG is known.
SNCF & transportWe build your SNCF connectorAPI ParticulierWe build your API Particulier connector
France TravailWe build your France Travail connector
DVF & cadastreWe build your DVF and cadastre connector
LegifranceWe build your Légifrance connectorWe combine API Géo with
The stack around administrative division on our projects.
API Géo integration: your questions
A municipality field with debounce, minimal fields (nom, code, codesPostaux, codeDepartement), boost=population, never geometry=contour on keystroke. We store the INSEE code, the label, the observation date, postcodes as an array. A local cache of the 18 regions and the départements. A server proxy if IP volume is unknown. Fallback: manual INSEE-code entry if the API 5xx. An identifiable User-Agent.
API Adresse geocodes an address (BAN): number, street, coordinates, citycode. API Géo decodes the administrative division: municipality, EPCI, département, region, optionally an outline. We chain them: Adresse → citycode → Géo for the EPCI, without calling /communes?nom= with a string already normalised. This is not cadastre, nor IGN Admin Express. For whole-of-France Admin Express and heavy outlines, we leave geo.api.gouv.fr for Géoplateforme or files, not for wxs.ign.fr.
Because a postcode does not identify a municipality. Paris has 21 postcodes and municipality code 75056: GET /communes?codePostal=75011 shows it. A postcode can also cover several municipalities, sometimes in another département. The key for the whole system is the INSEE code. The postcode stays an array of properties. A code stored in 2017 may be delegated after a merger: we date the observation, and we plan a millésime or a COG pack if the business requires it.
Free, no account, no key. A numeric official quota is not published. The server sends cache-control 3600 s immutable: we lean on it. Debounce, short fields, a proxy if volume is high. We do not publish an invented ceiling. Open-data attribution per the data.gouv sheet. An identifiable User-Agent and a server proxy are enough for most funnels. If volume explodes, we see it in monitoring, not as an undocumented 429 in production.
Access is free. The cost is the field: debounce, boost, COG persistence, cache, fallback. Municipality autocomplete in a sign-up funnel is a short job. An outline base map plus an offline field-agent tool is another project, often with the Etalab pack or COG files. We scope geometry and volume before we quote. Chaining Adresse (BAN) then Géo for the EPCI avoids a second name autocomplete, hence quota and homonyms.
An API Géo integration project?
Let's talk. 30 minutes to scope autocomplete, INSEE code and outlines, and tell you frankly what is feasible.
Discuss my API Géo project