French addresses and territories
Turn a French address into coordinates and coordinates into the nearest address, geocode a whole CSV file at once, and look up communes, departments, regions and intercommunalities with the free public APIs of the French State (Base Adresse Nationale, API Decoupage administratif). Overseas departments and merged communes are handled. Typical uses: place clients on a map, check a postcode typed in a form, list the communes of a department with their population.
geo geocode_frgeo geocode_frgeo reverse_frgeo reverse_frgeo geocode_fr_csvgeo geocode_fr_csvfr communefr communefr communes_by_postcodefr communes_by_postcodefr departementfr departementfr regionfr regionfr communes_offr communes_of

geo geocode_fr <address>


Description

    The coordinates of a French address (3 to 200 characters, starting with a letter or a digit). Returns {query, count, results, source}; each result: label, score (0 to 1), type (housenumber, street, locality, municipality), housenumber, street, name, postcode, city, citycode (INSEE code), department_code, district, oldcitycode and oldcity (former commune of a commune nouvelle), context, latitude, longitude, x, y, id (BAN key), ban_id. count is 0 when nothing is found

Parameters

    address:   The address - String - required
admin
geo geocode_fr "12 rue de Rivoli Paris"
mentdb
{"query": "12 rue de Rivoli Paris", "count": 1, "results": [{"label": "12 Rue de Rivoli 75004 Paris", "score": 0.9702, "type": "housenumber", "housenumber": "12", "street": "Rue de Rivoli", "name": "12 Rue de Rivoli", "postcode": "75004", "city": "Paris", "citycode": "75104", "department_code": "75", "district": "Paris 4e Arrondissement", "oldcitycode": null, "oldcity": null, "context": "75, Paris, Île-de-France", "latitude": 48.855602, "longitude": 2.35995, "x": 653036.75, "y": 6861919.65, "id": "75104_8249_00012", "ban_id": "524ec8d9-cfa2-48ee-a284-5a2a46a4156b"}], "source": "Base Adresse Nationale, geocoding service of the Geoplateforme (data.geopf.fr/geocodage), Etalab licence 2.0"}

geo geocode_fr <address> <json_params>


Description

    Geocode with parameters: limit (1 to 20, 1 by default), postcode (5 digits) and citycode (INSEE code) to filter, type (housenumber, street, locality, municipality), latitude and longitude (a point that favours the near results), autocomplete (false: true for the text typed by a user), min_score (0: the results under it are removed), timeout_ms (20000), endpoint, block_private (false)

Parameters

    address:   The address - String - required
    json_params:   The parameters - String - required
admin
geo geocode_fr "1 avenue Lenine Pierrefitte" "{\"limit\": 2, \"postcode\": \"93380\"}"
mentdb
{"query": "1 avenue Lenine Pierrefitte", "count": 1, "results": [{"label": "1 Avenue Lénine (Pierrefitte-sur-Seine) 93380 Saint-Denis", "score": 0.7265, "type": "housenumber", "housenumber": "1", "street": "Avenue Lénine (Pierrefitte-sur-Seine)", "name": "1 Avenue Lénine (Pierrefitte-sur-Seine)", "postcode": "93380", "city": "Saint-Denis", "citycode": "93066", "department_code": "93", "district": null, "oldcitycode": "93059", "oldcity": "Pierrefitte-sur-Seine", "context": "93, Seine-Saint-Denis, Île-de-France", "latitude": 48.962804, "longitude": 2.359647, "x": 653111.19, "y": 6873840.34, "id": "93066_5132_00001", "ban_id": "be22e222-213b-4c9c-99e0-f1af830732e6"}], "source": "Base Adresse Nationale, geocoding service of the Geoplateforme (data.geopf.fr/geocodage), Etalab licence 2.0"}

geo reverse_fr <latitude> <longitude>


Description

    The nearest French address of a point (WGS84). Returns {latitude, longitude, count, results, source}; each result has the fields of geo geocode_fr and distance_m (meters). count is 0 far from any address (at sea)

Parameters

    latitude:   The latitude - Number - required
    longitude:   The longitude - Number - required
admin
geo reverse_fr "-21.3393" "55.4781"
mentdb
{"latitude": -21.3393, "longitude": 55.4781, "count": 1, "results": [{"label": "15 Rue Augustin Archambaud 97410 Saint-Pierre", "score": 0.9992, "type": "housenumber", "housenumber": "15", "street": "Rue Augustin Archambaud", "name": "15 Rue Augustin Archambaud", "postcode": "97410", "city": "Saint-Pierre", "citycode": "97416", "department_code": "974", "district": null, "oldcitycode": null, "oldcity": null, "context": "974, La Réunion", "latitude": -21.339246, "longitude": 55.478156, "distance_m": 8, "x": 342182.97, "y": 7639543.53, "id": "97416_0030_00015", "ban_id": "a1e890a7-8df5-4ed5-9118-8a7a5b64a56d"}], "source": "Base Adresse Nationale, geocoding service of the Geoplateforme (data.geopf.fr/geocodage), Etalab licence 2.0"}

geo reverse_fr <latitude> <longitude> <json_params>


Description

    Reverse geocoding with parameters: limit (1 to 20, 1 by default), type (housenumber, street, locality, municipality), timeout_ms (20000), endpoint, block_private (false)

Parameters

    latitude:   The latitude - Number - required
    longitude:   The longitude - Number - required
    json_params:   The parameters - String - required
admin
geo reverse_fr "48.8566" "2.3522" "{\"type\": \"street\", \"limit\": 2}"
mentdb
{"latitude": 48.8566, "longitude": 2.3522, "count": 2, "results": [{"label": "Place de l'Hôtel de Ville-esplanade de la Libération 75004 Paris,Paris 4e Arrondissement", "score": 0.994, "type": "street", "housenumber": null, "street": null, "name": "Place de l'Hôtel de Ville-esplanade de la Libération", "postcode": "75004", "city": "Paris", "citycode": "75104", "department_code": "75", "district": "Paris 4e Arrondissement", "oldcitycode": null, "oldcity": null, "context": "75, Paris, Île-de-France", "latitude": 48.856772, "longitude": 2.351429, "distance_m": 60, "x": 652412.61, "y": 6862054.85, "id": "75104_4664", "ban_id": "095bd404-57a3-4482-a089-7ab481cceca7"}, {"label": "Rue de Lobau 75004 Paris,Paris 4e Arrondissement", "score": 0.991, "type": "street", "housenumber": null, "street": null, "name": "Rue de Lobau", "postcode": "75004", "city": "Paris", "citycode": "75104", "department_code": "75", "district": "Paris 4e Arrondissement", "oldcitycode": null, "oldcity": null, "context": "75, Paris, Île-de-France", "latitude": 48.856305, "longitude": 2.353341, "distance_m": 90, "x": 652552.47, "y": 6862001.77, "id": "75104_5722", "ban_id": "92525494-6bc9-48f9-93db-47658aeaef72"}], "source": "Base Adresse Nationale, geocoding service of the Geoplateforme (data.geopf.fr/geocodage), Etalab licence 2.0"}

geo geocode_fr_csv <csv_path> <out_path>


Description

    Geocode a whole CSV file (UTF-8, 50 MB and 200 000 lines at most, separator ; , tab or |) with the batch service and write the result file: the columns of the input, then longitude, latitude and the result_ columns (result_score, result_label, result_type, result_citycode, result_status: ok, not-found...). The parameter columns (the columns joined to form the address) is required. Returns {out_path, rows, status (count of each result_status), bytes, source}

Parameters

    csv_path:   The CSV file to geocode - String - required
    out_path:   The CSV file to write - String - required
admin
geo geocode_fr_csv "tmp/doc_frgov/clients.csv" "tmp/doc_frgov/clients_geo.csv"
mentdb
Sorry, an error appears (the parameter 'columns' is required: the columns that form the address, ex: {"columns": ["address", "city"]} (columns found: id, address, postcode)).

geo geocode_fr_csv <csv_path> <out_path> <json_params>


Description

    Geocode a CSV file with parameters: columns (required: a column name or an array, joined in this order), postcode and citycode (a column used as a filter), result_columns (the result columns to keep, among latitude, longitude, result_score, result_score_next, result_label, result_type, result_id, result_banId, result_housenumber, result_name, result_street, result_postcode, result_city, result_context, result_citycode, result_oldcitycode, result_oldcity, result_district, result_status), timeout_ms (300000), endpoint, block_private (false). The whole file is uploaded (keep only the id and address columns). The file is written only when the whole answer is received. A line that matches badly still has status ok: check result_score

Parameters

    csv_path:   The CSV file to geocode - String - required
    out_path:   The CSV file to write - String - required
    json_params:   The parameters - String - required
admin
geo geocode_fr_csv "tmp/doc_frgov/clients.csv" "tmp/doc_frgov/clients_geo.csv" "{\"columns\": [\"address\"], \"postcode\": \"postcode\"}"
mentdb
{"out_path": "tmp/doc_frgov/clients_geo.csv", "rows": 4, "status": {"ok": 4}, "bytes": 1294, "source": "Base Adresse Nationale, geocoding service of the Geoplateforme (data.geopf.fr/geocodage), Etalab licence 2.0"}
Fixed result from a real call to the geocoding service of the Geoplateforme on 2026-11-11: a few result columns only
admin
geo geocode_fr_csv "tmp/doc_frgov/clients.csv" "tmp/doc_frgov/clients_geo2.csv" "{\"columns\": [\"address\"], \"postcode\": \"postcode\", \"result_columns\": [\"latitude\", \"longitude\", \"result_score\", \"result_citycode\", \"result_status\"]}"
mentdb
{"out_path": "tmp/doc_frgov/clients_geo2.csv", "rows": 4, "status": {"ok": 4}, "bytes": 349, "source": "Base Adresse Nationale, geocoding service of the Geoplateforme (data.geopf.fr/geocodage), Etalab licence 2.0"}

fr commune <code_or_name>


Description

    A commune by its INSEE code (5 characters, ex: 97411, 2A004; a municipal district of Paris, Lyon or Marseille too: 75108, 13201) or by its name (case, accents and hyphens ignored; the most populated first). Returns {found, code, name, type (commune or municipal_district), parent_code, postcodes, department_code, department_name, region_code, region_name, epci_code, epci_name, siren, population, area_ha, centre_latitude, centre_longitude, town_hall_latitude, town_hall_longitude, zone (metro, drom, com), source}; by name also match (exact or approximate) and homonyms (number of communes with this name). A code of a former commune gives found false and former {name, type, merged_into}

Parameters

    code_or_name:   The INSEE code or the name - String - required
admin
fr commune "97411"
mentdb
{"found": true, "code": "97411", "name": "Saint-Denis", "type": "commune", "parent_code": null, "postcodes": ["97400", "97417", "97490"], "department_code": "974", "department_name": "La Réunion", "region_code": "04", "region_name": "La Réunion", "epci_code": "249740119", "epci_name": "CA Intercommunale du Nord de la Réunion (CINOR)", "siren": "219740115", "population": 155634, "area_ha": 14233.04, "centre_latitude": -20.9434, "centre_longitude": 55.4444, "town_hall_latitude": -20.8794, "town_hall_longitude": 55.4478, "zone": "drom", "source": "API Decoupage administratif (geo.api.gouv.fr), INSEE and IGN data, Etalab licence 2.0"}
Fixed result from a real call to the API Decoupage administratif on 2026-11-11: Pierrefitte-sur-Seine, merged into Saint-Denis (93066) on 2025-01-01
admin
fr commune "93059"
mentdb
{"found": false, "code": "93059", "former": {"name": "Pierrefitte-sur-Seine", "type": "delegated_commune", "merged_into": "93066"}, "source": "API Decoupage administratif (geo.api.gouv.fr), INSEE and IGN data, Etalab licence 2.0"}

fr commune <code_or_name> <json_params>


Description

    A commune with parameters: department (code, to choose between communes of the same name), contour (false: true adds the GeoJSON outline of the commune), timeout_ms (20000), endpoint, block_private (false)

Parameters

    code_or_name:   The INSEE code or the name - String - required
    json_params:   The parameters - String - required
admin
fr commune "Saint-Denis" "{\"department\": \"93\"}"
mentdb
{"found": true, "code": "93066", "name": "Saint-Denis", "type": "commune", "parent_code": null, "postcodes": ["93200", "93210", "93380"], "department_code": "93", "department_name": "Seine-Saint-Denis", "region_code": "11", "region_name": "Île-de-France", "epci_code": "200054781", "epci_name": "Métropole du Grand Paris", "siren": "929939411", "population": 149077, "area_ha": 1577.25, "centre_latitude": 48.9378, "centre_longitude": 2.3657, "town_hall_latitude": 48.9362, "town_hall_longitude": 2.3584, "zone": "metro", "match": "exact", "homonyms": 1, "source": "API Decoupage administratif (geo.api.gouv.fr), INSEE and IGN data, Etalab licence 2.0"}

fr communes_by_postcode <postcode>


Description

    The communes of a postcode (5 digits; several communes may share a postcode, and a commune may have several postcodes). Returns {postcode, count, communes, source}, each commune with the fields of fr commune

Parameters

    postcode:   The postcode - String - required
admin
fr communes_by_postcode "97400"
mentdb
{"postcode": "97400", "count": 1, "communes": [{"code": "97411", "name": "Saint-Denis", "type": "commune", "parent_code": null, "postcodes": ["97400", "97417", "97490"], "department_code": "974", "department_name": "La Réunion", "region_code": "04", "region_name": "La Réunion", "epci_code": "249740119", "epci_name": "CA Intercommunale du Nord de la Réunion (CINOR)", "siren": "219740115", "population": 155634, "area_ha": 14233.04, "centre_latitude": -20.9434, "centre_longitude": 55.4444, "town_hall_latitude": -20.8794, "town_hall_longitude": 55.4478, "zone": "drom"}], "source": "API Decoupage administratif (geo.api.gouv.fr), INSEE and IGN data, Etalab licence 2.0"}

fr communes_by_postcode <postcode> <json_params>


Description

    The communes of a postcode with parameters: municipal_districts (false: true adds the districts of Paris, Lyon and Marseille), timeout_ms (20000), endpoint, block_private (false)

Parameters

    postcode:   The postcode - String - required
    json_params:   The parameters - String - required
admin
fr communes_by_postcode "75008" "{\"municipal_districts\": true}"
mentdb
{"postcode": "75008", "count": 2, "communes": [{"code": "75108", "name": "Paris 8e Arrondissement", "type": "municipal_district", "parent_code": "75056", "postcodes": ["75008"], "department_code": "75", "department_name": "Paris", "region_code": "11", "region_name": "Île-de-France", "epci_code": null, "epci_name": null, "siren": null, "population": 35317, "area_ha": 387.8, "centre_latitude": 48.8732, "centre_longitude": 2.3111, "town_hall_latitude": 48.8775, "town_hall_longitude": 2.3176, "zone": "metro"}, {"code": "75056", "name": "Paris", "type": "commune", "parent_code": null, "postcodes": ["75001", "75002", "75003", "75004", "75005", "75006", "75007", "75008", "75009", "75010", "75011", "75012", "75013", "75014", "75015", "75016", "75017", "75018", "75019", "75020", "75116"], "department_code": "75", "department_name": "Paris", "region_code": "11", "region_name": "Île-de-France", "epci_code": "200054781", "epci_name": "Métropole du Grand Paris", "siren": "217500016", "population": 2103778, "area_ha": 10536.03, "centre_latitude": 48.8589, "centre_longitude": 2.347, "town_hall_latitude": 48.8564, "town_hall_longitude": 2.3525, "zone": "metro"}], "source": "API Decoupage administratif (geo.api.gouv.fr), INSEE and IGN data, Etalab licence 2.0"}

fr departement <code_or_name>


Description

    A department by its code (01 to 95, 2A, 2B, 971 to 976, and the collectivities 975, 977, 978) or its name. Returns {found, code, name, region_code, region_name, zone, source}; by name also match

Parameters

    code_or_name:   The code or the name - String - required
admin
fr departement "974"
mentdb
{"found": true, "code": "974", "name": "La Réunion", "region_code": "04", "region_name": "La Réunion", "zone": "drom", "source": "API Decoupage administratif (geo.api.gouv.fr), INSEE and IGN data, Etalab licence 2.0"}

fr departement <code_or_name> <json_params>


Description

    A department with parameters: timeout_ms (20000), endpoint, block_private (false)

Parameters

    code_or_name:   The code or the name - String - required
    json_params:   The parameters - String - required
admin
fr departement "Corse-du-Sud" "{\"timeout_ms\": 30000}"
mentdb
{"found": true, "code": "2A", "name": "Corse-du-Sud", "region_code": "94", "region_name": "Corse", "zone": "metro", "match": "exact", "source": "API Decoupage administratif (geo.api.gouv.fr), INSEE and IGN data, Etalab licence 2.0"}

fr region <code_or_name>


Description

    A region by its code (11 to 94, and 01, 02, 03, 04, 06 overseas) or its name, with its departments. Returns {found, code, name, zone, departements [{code, name}], source}; by name also match

Parameters

    code_or_name:   The code or the name - String - required
admin
fr region "04"
mentdb
{"found": true, "code": "04", "name": "La Réunion", "zone": "drom", "departements": [{"code": "974", "name": "La Réunion"}], "source": "API Decoupage administratif (geo.api.gouv.fr), INSEE and IGN data, Etalab licence 2.0"}

fr region <code_or_name> <json_params>


Description

    A region with parameters: timeout_ms (20000), endpoint, block_private (false)

Parameters

    code_or_name:   The code or the name - String - required
    json_params:   The parameters - String - required
admin
fr region "Corse" "{\"timeout_ms\": 30000}"
mentdb
{"found": true, "code": "94", "name": "Corse", "zone": "metro", "departements": [{"code": "2A", "name": "Corse-du-Sud"}, {"code": "2B", "name": "Haute-Corse"}], "match": "exact", "source": "API Decoupage administratif (geo.api.gouv.fr), INSEE and IGN data, Etalab licence 2.0"}

fr communes_of <kind> <code>


Description

    All the communes of a department, a region or an EPCI (intercommunality, by its SIREN of 9 digits). kind: departement, region or epci. Returns {kind, code, count, communes, source}, each commune with the fields of fr commune; count is 0 for an unknown code

Parameters

    kind:   departement, region or epci - String - required
    code:   The code - String - required
admin
fr communes_of "epci" "249740119"
mentdb
{"kind": "epci", "code": "249740119", "count": 3, "communes": [{"code": "97411", "name": "Saint-Denis", "type": "commune", "parent_code": null, "postcodes": ["97400", "97417", "97490"], "department_code": "974", "department_name": "La Réunion", "region_code": "04", "region_name": "La Réunion", "epci_code": "249740119", "epci_name": "CA Intercommunale du Nord de la Réunion (CINOR)", "siren": "219740115", "population": 155634, "area_ha": 14233.04, "centre_latitude": -20.9434, "centre_longitude": 55.4444, "town_hall_latitude": -20.8794, "town_hall_longitude": 55.4478, "zone": "drom"}, {"code": "97418", "name": "Sainte-Marie", "type": "commune", "parent_code": null, "postcodes": ["97438"], "department_code": "974", "department_name": "La Réunion", "region_code": "04", "region_name": "La Réunion", "epci_code": "249740119", "epci_name": "CA Intercommunale du Nord de la Réunion (CINOR)", "siren": "219740180", "population": 37093, "area_ha": 8900.28, "centre_latitude": -20.9463, "centre_longitude": 55.5234, "town_hall_latitude": -20.8969, "town_hall_longitude": 55.5493, "zone": "drom"}, {"code": "97420", "name": "Sainte-Suzanne", "type": "commune", "parent_code": null, "postcodes": ["97441"], "department_code": "974", "department_name": "La Réunion", "region_code": "04", "region_name": "La Réunion", "epci_code": "249740119", "epci_name": "CA Intercommunale du Nord de la Réunion (CINOR)", "siren": "219740206", "population": 25551, "area_ha": 5814.02, "centre_latitude": -20.9507, "centre_longitude": 55.5936, "town_hall_latitude": -20.9056, "town_hall_longitude": 55.6075, "zone": "drom"}], "source": "API Decoupage administratif (geo.api.gouv.fr), INSEE and IGN data, Etalab licence 2.0"}

fr communes_of <kind> <code> <json_params>


Description

    The communes with parameters: municipal_districts (false: true adds the districts of Paris, Lyon and Marseille), timeout_ms (20000), endpoint, block_private (false)

Parameters

    kind:   departement, region or epci - String - required
    code:   The code - String - required
    json_params:   The parameters - String - required
admin
fr communes_of "departement" "975" "{\"timeout_ms\": 30000}"
mentdb
{"kind": "departement", "code": "975", "count": 2, "communes": [{"code": "97501", "name": "Miquelon-Langlade", "type": "commune", "parent_code": null, "postcodes": ["97500"], "department_code": "975", "department_name": "Saint-Pierre-et-Miquelon", "region_code": "975", "region_name": "Saint-Pierre-et-Miquelon", "epci_code": null, "epci_name": null, "siren": null, "population": 596, "area_ha": 19277.71, "centre_latitude": 46.9711, "centre_longitude": -56.3405, "town_hall_latitude": 47.0997, "town_hall_longitude": -56.3779, "zone": "com"}, {"code": "97502", "name": "Saint-Pierre", "type": "commune", "parent_code": null, "postcodes": ["97500"], "department_code": "975", "department_name": "Saint-Pierre-et-Miquelon", "region_code": "975", "region_name": "Saint-Pierre-et-Miquelon", "epci_code": null, "epci_name": null, "siren": null, "population": 5194, "area_ha": 2681.04, "centre_latitude": 46.788, "centre_longitude": -56.1805, "town_hall_latitude": 46.7819, "town_hall_longitude": -56.1742, "zone": "com"}], "source": "API Decoupage administratif (geo.api.gouv.fr), INSEE and IGN data, Etalab licence 2.0"}