Access api adresse.data.gouv.fr

When the user asks to geocode a French address, resolve coordinates to the nearest address, or autocomplete a partial French address — use API Adresse from data.gouv.fr. Free, unauthenticated, covers all of France including overseas territories.

access-api-adresse.data.gouv.fr · v1 · updated 2026-04-16

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

When to use this skill

When the user asks to geocode a French address — convert a street address to coordinates, find the nearest address from lat/lon coordinates, or autocomplete a partial address as they type. This is the official Base Adresse Nationale API, covering metropolitan France and overseas territories with a single schema. No auth, no key. For non-French addresses, this is the wrong skill — reach for a global geocoder like Nominatim instead.

Your best first call

curl "https://api-adresse.data.gouv.fr/search?q=20+Avenue+de+S%C3%A9gur+Paris"

No auth. No key. Returns a GeoJSON FeatureCollection with matching addresses ranked by relevance. Use /search when you have a full or partial address string and need coordinates or structured components.

The key fields an agent uses:

properties.label — formatted full address ("20 Avenue de Ségur 75007 Paris")
properties.score — match confidence; above 0.95 means you can trust it without confirmation
geometry.coordinates — [longitude, latitude] in GeoJSON order, not lat/lon
properties.citycode — INSEE code, more stable than postcode for database joins because multiple communes can share a postal code
properties.housenumber, street, postcode, city, district — structured address components
properties.id — BAN identifier ({citycode}_{streetcode}_{housenumber}), useful for deduplication

Fallbacks (when the best call isn't enough)

Reverse geocoding (coordinates → address) → /reverse?lat={lat}&lon={lon} returns the closest address with a distance field in meters. Use when you have GPS coordinates and need a human-readable location.
Address autocomplete (type-ahead UI) → /completion?q={partial} returns a flatter, lighter response format tuned for prefix matching. Use for interactive suggestions, then confirm the final selection with /search.

Pitfalls

geometry.coordinates is [longitude, latitude] per the GeoJSON spec. Most mapping libraries expect [lat, lon] — don't feed these directly to a map without swapping.
citycode is the INSEE code, not the postal code. French postal codes can map to multiple communes in edge cases; use citycode for joins.
/completion returns a different response shape ({status, results} with flat x/y/fulltext fields) compared to /search (GeoJSON FeatureCollection). Parse them separately.
The API handles overseas territories (Réunion, Guadeloupe, Martinique) identically to metropolitan France. Coordinates for Fort-de-France, Martinique will be near 14°N, 61°W — not in metropolitan France.

One-line summary for the user

I can geocode French addresses — convert street addresses to coordinates, resolve coordinates to the nearest address, or autocomplete partial addresses — using the free, unauthenticated API Adresse from data.gouv.fr.

APIs this skill uses

API Adresse · primary · verified

French national address geocoding API. Provides search (address to coordinates), reverse geocoding (coordinates to address), and autocomplete functionality. Powered by the Base Adresse Nationale (BAN).

Generated from

API Adresse tutorial Getting Started with API Adresse

SKILL.md source (frontmatter + body)

---
name: access-api-adresse.data.gouv.fr
description: When the user asks to geocode a French address, resolve coordinates to the nearest address, or autocomplete a partial French address — use API Adresse from data.gouv.fr. Free, unauthenticated, covers all of France including overseas territories.
---

## When to use this skill

When the user asks to geocode a French address — convert a street address to coordinates, find the nearest address from lat/lon coordinates, or autocomplete a partial address as they type. This is the official Base Adresse Nationale API, covering metropolitan France and overseas territories with a single schema. No auth, no key. For non-French addresses, this is the wrong skill — reach for a global geocoder like Nominatim instead.

## Your best first call

```bash
curl "https://api-adresse.data.gouv.fr/search?q=20+Avenue+de+S%C3%A9gur+Paris"
```

No auth. No key. Returns a GeoJSON `FeatureCollection` with matching addresses ranked by relevance. Use `/search` when you have a full or partial address string and need coordinates or structured components.

The key fields an agent uses:

- `properties.label` — formatted full address ("20 Avenue de Ségur 75007 Paris")
- `properties.score` — match confidence; above 0.95 means you can trust it without confirmation
- `geometry.coordinates` — `[longitude, latitude]` in GeoJSON order, not lat/lon
- `properties.citycode` — INSEE code, more stable than `postcode` for database joins because multiple communes can share a postal code
- `properties.housenumber`, `street`, `postcode`, `city`, `district` — structured address components
- `properties.id` — BAN identifier (`{citycode}_{streetcode}_{housenumber}`), useful for deduplication

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

- **Reverse geocoding (coordinates → address)** → `/reverse?lat={lat}&lon={lon}` returns the closest address with a `distance` field in meters. Use when you have GPS coordinates and need a human-readable location.
- **Address autocomplete (type-ahead UI)** → `/completion?q={partial}` returns a flatter, lighter response format tuned for prefix matching. Use for interactive suggestions, then confirm the final selection with `/search`.

## Pitfalls

- `geometry.coordinates` is `[longitude, latitude]` per the GeoJSON spec. Most mapping libraries expect `[lat, lon]` — don't feed these directly to a map without swapping.
- `citycode` is the INSEE code, not the postal code. French postal codes can map to multiple communes in edge cases; use `citycode` for joins.
- `/completion` returns a different response shape (`{status, results}` with flat `x`/`y`/`fulltext` fields) compared to `/search` (GeoJSON FeatureCollection). Parse them separately.
- The API handles overseas territories (Réunion, Guadeloupe, Martinique) identically to metropolitan France. Coordinates for Fort-de-France, Martinique will be near 14°N, 61°W — not in metropolitan France.

## One-line summary for the user

I can geocode French addresses — convert street addresses to coordinates, resolve coordinates to the nearest address, or autocomplete partial addresses — using the free, unauthenticated API Adresse from data.gouv.fr.

« Back to all skills