Search french addresses

When the user asks about a French address, postal code, city, coordinates, or INSEE code — or wants to geocode a French street address — reach for the Base Adresse Nationale via api-adresse.data.gouv.fr. No key required.

search-french-addresses · v2 · updated 2026-04-16

Agents: This page is a SKILL.md-style capability guide. For JSON, call GET /api/skills/search-french-addresses. To drop this into a local Claude Code install, copy the frontmatter + body below into ~/.claude/skills/search-french-addresses/SKILL.md.

When to use this skill

When the user asks about a French address — postal codes, city names, coordinates, INSEE commune codes, administrative regions — or wants to geocode a French street address to latitude/longitude, or has coordinates and needs the nearest French address. This is metropolitan France and overseas departments only; for Belgian or Swiss addresses across the border, reach for Nominatim instead. For non-French European geocoding, this is the wrong skill.

Your best first call

curl "https://api-adresse.data.gouv.fr/search/?q=Place+de+la+Concorde+Paris&limit=5"

No auth. No key. Returns a GeoJSON FeatureCollection with up to limit matching addresses. Each feature's properties object carries the fields an agent actually uses:

label — full formatted address string (e.g. "Place de la Concorde 75008 Paris")
score — confidence from 0 to 1; below ~0.7 the match is approximate
housenumber, street — parsed house number and street name
postcode — French postal code (5 digits)
citycode — INSEE commune code (unique administrative identifier, more stable than city names which can merge or rename)
city — commune name
context — department number and name, region (e.g. "75, Paris, Île-de-France")
type — result granularity: housenumber, street, locality, or municipality
geometry.coordinates — [longitude, latitude] in that order (GeoJSON convention)

Use &type= to filter: housenumber for precise addresses, street for street-level, municipality for commune-only results. Use &postcode= to narrow to a postal code area.

Fallbacks (when the best call isn't enough)

Reverse geocoding (coordinates to address) → curl "https://api-adresse.data.gouv.fr/reverse/?lon=2.3223&lat=48.8645" — same API, same response shape. Use when you have GPS coordinates and need the address.
Non-French addresses or broader European coverage → Nominatim (nominatim.openstreetmap.org) handles worldwide geocoding but lacks citycode and French-specific administrative context. Use when the address is outside France.
Cadastral parcels → The same API with type=cadastral returns parcel identifiers instead of street addresses. Use when the user specifically asks about land parcels.

Pitfalls

Coordinates are [longitude, latitude], not [lat, lng]. GeoJSON mandates x-then-y. If you pass coordinates to another API that expects [lat, lng] — or read them out of order for a mapping link — Versailles lands in the wrong ocean.
score below ~0.7 means the match is unreliable. A search for "rue de la Paix" with score 0.4 is probably not the street the user meant. Treat low scores as "no confident match found" rather than as usable results.
The type filter is strict. Setting type=housenumber excludes street and municipality results entirely, even when no house-number match exists. If you get zero results with type=housenumber, retry without the type filter.
Only France. The API covers metropolitan France and overseas departments (Guadeloupe, Martinique, Guyane, La Réunion, Mayotte). Addresses in Monaco, Andorra, or border towns in Belgium/Germany/Switzerland return nothing.

One-line summary for the user

I can look up any French address and return its coordinates, postal code, INSEE code, and administrative context — no key required — via the French government's Base Adresse Nationale, but it only covers France.

APIs this skill uses

French Address Search · primary · verified

Geocoding service providing French address search, reverse geocoding, and point of interest lookup. This is the official French government geocoding service that allows obtaining geographic coordinates from an address or place name, or find…

SKILL.md source (frontmatter + body)

---
name: search-french-addresses
description: When the user asks about a French address, postal code, city, coordinates, or INSEE code — or wants to geocode a French street address — reach for the Base Adresse Nationale via api-adresse.data.gouv.fr. No key required.
---

## When to use this skill

When the user asks about a French address — postal codes, city names, coordinates, INSEE commune codes, administrative regions — or wants to geocode a French street address to latitude/longitude, or has coordinates and needs the nearest French address. This is metropolitan France and overseas departments only; for Belgian or Swiss addresses across the border, reach for Nominatim instead. For non-French European geocoding, this is the wrong skill.

## Your best first call

```bash
curl "https://api-adresse.data.gouv.fr/search/?q=Place+de+la+Concorde+Paris&limit=5"
```

No auth. No key. Returns a GeoJSON `FeatureCollection` with up to `limit` matching addresses. Each feature's `properties` object carries the fields an agent actually uses:

- `label` — full formatted address string (e.g. "Place de la Concorde 75008 Paris")
- `score` — confidence from 0 to 1; below ~0.7 the match is approximate
- `housenumber`, `street` — parsed house number and street name
- `postcode` — French postal code (5 digits)
- `citycode` — INSEE commune code (unique administrative identifier, more stable than city names which can merge or rename)
- `city` — commune name
- `context` — department number and name, region (e.g. "75, Paris, Île-de-France")
- `type` — result granularity: `housenumber`, `street`, `locality`, or `municipality`
- `geometry.coordinates` — `[longitude, latitude]` in that order (GeoJSON convention)

Use `&type=` to filter: `housenumber` for precise addresses, `street` for street-level, `municipality` for commune-only results. Use `&postcode=` to narrow to a postal code area.

## Fallbacks (when the best call isn't enough)

- **Reverse geocoding (coordinates to address)** → `curl "https://api-adresse.data.gouv.fr/reverse/?lon=2.3223&lat=48.8645"` — same API, same response shape. Use when you have GPS coordinates and need the address.
- **Non-French addresses or broader European coverage** → Nominatim (`nominatim.openstreetmap.org`) handles worldwide geocoding but lacks `citycode` and French-specific administrative context. Use when the address is outside France.
- **Cadastral parcels** → The same API with `type=cadastral` returns parcel identifiers instead of street addresses. Use when the user specifically asks about land parcels.

## Pitfalls

- **Coordinates are `[longitude, latitude]`, not `[lat, lng]`.** GeoJSON mandates x-then-y. If you pass coordinates to another API that expects `[lat, lng]` — or read them out of order for a mapping link — Versailles lands in the wrong ocean.
- **`score` below ~0.7 means the match is unreliable.** A search for "rue de la Paix" with score 0.4 is probably not the street the user meant. Treat low scores as "no confident match found" rather than as usable results.
- **The `type` filter is strict.** Setting `type=housenumber` excludes street and municipality results entirely, even when no house-number match exists. If you get zero results with `type=housenumber`, retry without the type filter.
- **Only France.** The API covers metropolitan France and overseas departments (Guadeloupe, Martinique, Guyane, La Réunion, Mayotte). Addresses in Monaco, Andorra, or border towns in Belgium/Germany/Switzerland return nothing.

## One-line summary for the user

I can look up any French address and return its coordinates, postal code, INSEE code, and administrative context — no key required — via the French government's Base Adresse Nationale, but it only covers France.

« Back to all skills