Getting Started with API Adresse — API Adresse

When to use this API

When you need to geocode French addresses — convert street addresses to coordinates, find addresses from lat/lon, or autocomplete partial addresses as a user types. This is the official French national address API (Base Adresse Nationale), so it covers metropolitan France and overseas territories with the same schema. No auth. No key. The API also handles "communes anciennes" (merged municipalities that still have distinct postal addresses), a quirk most geocoders silently drop.

Geocoding a French street address

"What's the coordinate for the Ministry of Health in Paris?" The /search endpoint returns full address records with lat/lon coordinates, structured components, and relevance scores. Use it for any address-to-coordinate lookup.

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

{
  "type": "FeatureCollection",
  "features": [{
    "type": "Feature",
    "geometry": {
      "type": "Point",
      "coordinates": [2.308628, 48.850699]
    },
    "properties": {
      "label": "20 Avenue de Ségur 75007 Paris",
      "score": 0.9716,
      "housenumber": "20",
      "street": "Avenue de Ségur",
      "postcode": "75007",
      "citycode": "75107",
      "city": "Paris",
      "district": "Paris 7e Arrondissement",
      "context": "75, Paris, Île-de-France",
      "type": "housenumber",
      "importance": 0.6881,
      "id": "75107_8909_00020"
    }
  }]
}

The response follows GeoJSON conventions — geometry.coordinates is [longitude, latitude] (not lat/lon). The score field tells you match confidence; above 0.95 usually means you can trust it without confirmation. The citycode is the INSEE code, which is more stable than postal codes for database joins — France has multiple postcodes per INSEE code in some edge cases. Note that the id follows the BAN format: {citycode}_{streetcode}_{housenumber}.

20 Avenue de Ségur is at coordinates 48.850699°N, 2.308628°E in Paris's 7th arrondissement. The address ID in the Base Adresse Nationale is 75107_8909_00020.

Reverse geocoding from coordinates

"What address is at these coordinates?" The /reverse endpoint takes lat and lon parameters and returns the closest matching address. Use it when you have GPS coordinates and need a human-readable location.

curl "https://api-adresse.data.gouv.fr/reverse?lat=48.8507&lon=2.3086" | head -c 10000

{
  "type": "FeatureCollection",
  "features": [{
    "type": "Feature",
    "geometry": {
      "type": "Point",
      "coordinates": [2.308628, 48.850699]
    },
    "properties": {
      "label": "20 Avenue de Ségur 75007 Paris",
      "score": 0.9981,
      "housenumber": "20",
      "street": "Avenue de Ségur",
      "postcode": "75007",
      "citycode": "75107",
      "city": "Paris",
      "district": "Paris 7e Arrondissement",
      "context": "75, Paris, Île-de-France",
      "type": "housenumber",
      "distance": 19,
      "id": "75107_8909_00020"
    }
  }]
}

The distance field — present only in reverse geocoding — tells you how far the result is from your query point in meters. A score above 0.99 with a distance under 50 meters means you've likely hit the exact building. The reverse endpoint searches across all address types; if you only want house numbers and not street-level matches, add &type=housenumber as a filter.

The closest address to those coordinates is 20 Avenue de Ségur, 75007 Paris — about 19 meters from the queried point.

Autocompleting partial addresses

"Show me suggestions as the user types '8 Boulevard du Port'." The /completion endpoint is optimized for autocomplete UIs. It returns a flatter, lighter response format than /search and is tuned for prefix matching.

curl "https://api-adresse.data.gouv.fr/completion?q=8+Boulevard+du+Port+Cergy" | head -c 10000

{
  "status": "OK",
  "results": [{
    "x": 2.062821,
    "y": 49.031624,
    "city": "Cergy",
    "zipcode": "95000",
    "street": "Boulevard du Port",
    "kind": "housenumber",
    "fulltext": "8 Boulevard du Port, 95000 Cergy",
    "classification": 7
  }]
}

Note the different response shape: x/y instead of GeoJSON geometry, fulltext instead of label, and a simpler flat structure. The classification field (1-7) is an internal ranking — 7 means high-confidence match. The completion endpoint is faster but less precise than /search; use it for interactive type-ahead, then switch to /search for the final confirmed address.

8 Boulevard du Port, 95000 Cergy — coordinates 49.031624°N, 2.062821°E.

Pitfalls

Coordinates are [longitude, latitude] in the GeoJSON geometry.coordinates array. Most mapping libraries expect [lat, lon] — don't feed these directly to a map without swapping.
The citycode is INSEE, not postal. French postal codes (postcode) can map to multiple communes in edge cases. Use citycode for database joins.
/completion and /search have different response shapes. /search returns GeoJSON FeatureCollections; /completion returns {status, results} with flat objects. Don't assume they're interchangeable.
Overseas territories use the same schema but coordinates are in their native CRS. The API handles Réunion, Guadeloupe, Martinique, etc. identically to metropolitan France.

One-line summary for the user

I can geocode French addresses — convert street addresses to coordinates and vice versa — using the free, unauthenticated API Adresse service from data.gouv.fr, which covers all of France including overseas territories.