L’API Découpage administratif permet d’obtenir des données administratives françaises :
à des échelles différentes (communes, départements, régions) ;
à des années différentes (notion de millésime).
L'API Découpage administratif est principalement destinée à un besoin de recherche pour des formulaires en partant du nom de la commune, du code postal ou bien du code INSEE.
Les usages départements ou régions bien que pratiques semblent moins intéressants car les données ne changent quasiment jamais dans le temps et le nombre limité d'éléments fait qu'il est possible de gérer ces informations côté client.
L’API est très utile pour permettre de faire l'auto-complétion qu’il s’agisse d’un formulaire ou pour permettre de zoomer sur une commune trouvée dans un contexte web : http://bl.ocks.org/ThomasG77/0b99013795f76699c5c9a0d7daf4411e
La partie importante se base sur un simple Fetch.
Il est aussi possible de remplir les informations de coordonnées dans un tableur comme Libre Office.
Ici sont présentés les exemples les plus courants.
Pour des usages plus spécifiques, vous pouvez utiliser les exemples de la documentation officielle.
Rechercher par code postal : https://geo.api.gouv.fr/communes?codePostal=78000
Rechercher par code INSEE : https://geo.api.gouv.fr/communes?code=44109
Rechercher par nom : https://geo.api.gouv.fr/communes?nom=Nantes&boost=population&limit=5 (on ajoute un boost par population pour que la plus grande commune soit privilégiée)
Rechercher par coordonnées : https://geo.api.gouv.fr/communes?lat=47.0482944&lon=-1.1501568
Filtrer par département pour éviter les problèmes liés à l'homonymie de commune, par exemple la commune de Saint-Aubin existe dans les départements 10, 21, 36, 39, 40, 47, 59, 62, 91 et 02 : https://geo.api.gouv.fr/communes?nom=Saint-Aubin&codeDepartement=21
Obtenir toutes les communes d'un département : https://geo.api.gouv.fr/departements/44/communes
Obtenir toutes les communes d'une région : https://geo.api.gouv.fr/communes?codeRegion=84
Tous les exemples ci-dessus ne filtrent pas les champs, ne permettent pas de choisir si on veut des géométries pour les communes : soit le centre, au sens mathématique, de la commune, soit son contour, ni ne permettent pas le choix de la sérialisation : pour la cartographie, généralement, on utilise un JSON spécifique dit GeoJSON.
La meilleure manière de comprendre comment cela fonctionne est d'utiliser la démo recherche avancée de la documentation officielle. Elle permet, en cochant, de voir comment l'URL d'appel change en particulier l'option fields pour ne retourner que les colonnes/champs nécessaires.
Ce qu'il faut retenir pour les aspects géo :
Si vous souhaitez les GeoJSON avec le centre de la commune --> rajoutez aux URLs de la première partie &format=geojson&geometry=centre si votre URL contient déjà un ? sinon il faut ajouter plutôt ?format=geojson&geometry=centre
Si vous souhaitez les GeoJSON avec le contour de la commune --> rajoutez aux URLs de la première partie &format=geojson&geometry=contour si votre URL contient déjà un ? sinon il faut ajouter plutôt ?format=geojson&geometry=contour
Un exemple pour illustrer
https://geo.api.gouv.fr/communes?lat=47.0482944&lon=-1.1501568
devient :
Si l’on souhaite le centre de la commune : https://geo.api.gouv.fr/communes?lat=47.0482944&lon=-1.1501568&format=geojson&geometry=centre
Si l’on souhaite le contour de la commune : https://geo.api.gouv.fr/communes?lat=47.0482944&lon=-1.1501568&format=geojson&geometry=contour
Il faut également penser à mettre en cache quand on a des appels lourds qui ne changent pas ou qu'on retourne des contours. Ainsi :
Sans contour, la réponse fait 480Ko https://geo.api.gouv.fr/communes?codeRegion=84
Avec contour, la réponse fait 34Mo https://geo.api.gouv.fr/communes?codeRegion=84&format=geojson&geometry=contour
Vous pouvez très bien sauvegarder dans un fichier le résultat des URLs ci-dessus : le résultat ne va pas changer en permanence car ce n'est pas de l'autocomplétion.
Dans ce cas de figure, le principal intérêt est la correspondance entre un nom et un code.
Si l’on souhaite le code d'un département ou d'une région, on prend :
pour la région : https://geo.api.gouv.fr/regions?nom=Auvergne
pour le département : https://geo.api.gouv.fr/departements?nom=Loire Atl
Les cas départements et régions fonctionnent comme les communes et changent très rarement. Il est souvent envisageable d'avoir les fichiers globaux JSON plutôt que passer par des appels API. On a ainsi sous forme JSON (sans géométrie) :