Ce guide propose d'explorer des cas pratiques d'utilisation des API géographiques mises à votre disposition pour vous accompagner dans leur utilisation, que vous soyez en train de construire une carte ou que vous souhaitiez récupérer des données géographiques.

Ce guide s'adresse donc à plusieurs types de profils :

• Néophytes dans l'utilisation des APIs ;

• Intégrateurs web ;

• Spécialistes du secteur géospatial.

Il s'agit d'un outil évolutif et ouvert. Vous pouvez contribuer à l'améliorer en proposant une modification sur GitHub ou en contactant directement l'équipe Géo d'Etalab.

Dans ce guide, vous apprendrez comment :

Dans cette section, vous apprendrez comment :

Comment utiliser l'API dans un site web ?

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.

Quels sont les exemples officiels d'utilisation de l'API ?

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.

Quelles sont les sources alternatives pour les communes ?

ogrinfo -so WFS:https://wxs.ign.fr/administratif/geoportail/wfs

ogrinfo --DEBUG ON -so WFS:https://wxs.ign.fr/administratif/geoportail/wfs

ogrinfo -so -noextent WFS:https://wxs.ign.fr/administratif/geoportail/wfs "ADMINEXPRESS-COG.LATEST:commune"

# Filtrer les communes pour plusieurs départements en retournant un GeoJSON
ogr2ogr -f GeoJSON communes-44-35.geojson \
        --config OGR_WFS_PAGING_ALLOWED ON \
        --config OGR_WFS_PAGE_SIZE 250 \
        WFS:https://wxs.ign.fr/administratif/geoportail/wfs \
        -sql "SELECT * FROM \"ADMINEXPRESS-COG.LATEST:commune\" WHERE insee_dep IN ('44', '35')" \
        -lco RFC7946=YES

# Obtenir la commune par code commune INSEE sous forme CSV
ogr2ogr -f CSV commune-44109.csv WFS:https://wxs.ign.fr/administratif/geoportail/wfs -sql "SELECT * FROM \"ADMINEXPRESS-COG.LATEST:commune\" WHERE insee_com = '44109'"

# Obtenir les communes de l'EPCI grâce au code Siren de l'EPCI
ogr2ogr -f GeoJSON communes-epci-with-44109.geojson WFS:https://wxs.ign.fr/administratif/geoportail/wfs -sql "SELECT * FROM \"ADMINEXPRESS-COG.LATEST:commune\" WHERE siren_epci = '244400404'"

ogr2ogr -f CSV commune-44109-from-geom.csv WFS:https://wxs.ign.fr/administratif/geoportail/wfs -sql "SELECT * FROM \"ADMINEXPRESS-COG.LATEST:commune\" WHERE ST_Contains(ST_GeomFromText('POINT(-1.54241 47.21791)', 'EPSG:4326'), the_geom)" -lco RFC7946=YES

ogr2ogr -f GeoJSON epci-with-44109-from-siren.geojson WFS:https://wxs.ign.fr/administratif/geoportail/wfs -sql "SELECT * FROM \"ADMINEXPRESS-COG.LATEST:epci\" WHERE code_siren = '244400404'"

ogr2ogr -f GeoJSON epci-with-44109-from-geom.geojson WFS:https://wxs.ign.fr/administratif/geoportail/wfs -sql "SELECT * FROM \"ADMINEXPRESS-COG.LATEST:epci\" WHERE ST_Contains(ST_GeomFromText('POINT(-1.54241 47.21791)', 'EPSG:4326'), the_geom)"

Foire aux questions (FAQ)

Quels sont les usages de l’API Adresse ?

L'API Adresse est utilisée principalement pour :

• trouver par un formulaire une adresse pour la corriger et/ou récupérer des coordonnées en ayant une liste de choix pour trouver le résultat : c’est l’autocomplétion ;

• fournir un fichier tabulaire pour obtenir en retour une version enrichie des coordonnées et d’autres informations.

Comment accéder aux données d’adresses ?

Pour accéder aux données d'adresses, il est possible de :

• Récupérer directement les données. Cette méthode s’adresse à des utilisateurs avancés.

• Utiliser l’API de recherche. Cette API peut rechercher des adresses soit via un appel unique par adresse soit en mode "batch" : on passe un fichier avec une liste d’adresse, une par ligne et on retourne la première adresse retournée pour chacune des lignes.

Qu'est-ce que les tuiles vectorielles ?

Pourquoi utiliser les tuiles vectorielles ?

Le service proposé par Etalab permet de :

• mettre à disposition des tuiles avec un style pour avoir un fond de plan de tuiles vecteur. Ce style est publié en s’appuyant sur une version d’OpenMapTiles déployée par Etalab sur la France.

• servir les tuiles des limites administratives ainsi que celles du cadastre.

Ce service s'appuie sur les données du .

OpenStreetMap (ou "OSM") est une carte du monde entier librement modifiable, faite par des gens comme vous. OpenStreetMap vous permet de voir, modifier et utiliser des données géographiques de n'importe quel endroit dans le monde.

Si vous identifiez des données manquantes sur la carte, vous pouvez contribuer sur et vous verrez les changements au plus tard une semaine après. En effet, les tuiles vecteur des fonds de plan sont mises à jour une fois par semaine.

Il faut aussi noter que vous devez obligatoirement quand vous utilisez les fonds de plan.

Qui utilise ce service ?

Ce service est utilisé par plusieurs produits d’Etalab ainsi que par d’autres acteurs institutionnels en raison de la légèreté des tuiles vectorielles et des styles associés en comparaison à ceux mis à disposition actuellement par l’IGN.

Quelles sont les limites de ce service ?

Bien que ce service réponde à de nombreux besoins, il présente certaines limites.

❌ Les cas où vous ne devriez pas utiliser OpenMapTiles :

• Si vous avez un besoin qui vous parait correspondre à celui des tuiles vectorielles et styles associés de l’IGN (voir des exemples en fin de guide). Ces tuiles sont un peu plus lourdes mais elles sont par nature plus homogènes en terme de contenu car elles utilisent les données de l’IGN. Celles du projet OpenMapTiles étant basées sur OpenStreetMap, la complétude dépend des contributions à OpenStreetMap.

Rappels sur les tuiles vecteur

Les tuiles raster

Historiquement, pour faire du webmapping, on renvoyait des tuiles images qui étaient des images de cartes découpées en 256px ou 512px (si écran haute définition).

Ce qu'on peut encore voir par exemple :

Le découpage des tuiles est normalisé en s'appuyant sur "une grille" qui change avec les échelles et dont les conventions sont reprises par tous.

Les « tuiles vectorielles »

Même si ces solutions raster sont toujours fonctionnelles, il existe des cas qui nécessitent d’avoir plus de souplesse pour pouvoir styler des fonds de plan en particulier ou bien pour afficher une couche « par-dessus » les autres. Ils peuvent être adressés avec les tuiles vectorielles.

On parle abusivement de tuiles vectorielles pour désigner généralement deux choses :

• les tuiles vectorielles à proprement parler

• les styles « Mapbox Vector Style »

Les tuiles vectorielles en elles-même

On peut les assimiler à des objects vectoriels, des points, des lignes, des polygones qui sont associés à des attributs par exemple un nom. On groupe ces objets par couche, généralement un objet métier, par exemple, les limites communales, les commerces, etc. On découpe ensuite ces vecteurs selon une emprise fixe qui reprend celle historiquement utilisées par les tuiles raster. On peut ainsi voir quelles couches contiennent une tuile.

Il existe plusieurs standards pour ces tuiles mais celui le plus adopté est celui de la société Mapbox : on parle de "Mapbox Vector Tiles" ou MVT.

Leur contenu est encapsulé dans un format binaire appelé Protocol Buffer, non spécifique à la cartographie, c'est pour cela que l'extension des tuiles est souvent .pbf même si cela était historiquement .mvt.

Quelques exemples pour inspecter :

Les styles

Ils permettent d'indiquer pour quelles couches, pour quelles caractéristiques comme la population et quels zooms il faut appliquer un style.

Ces styles peuvent être : l'épaisseur du trait, sa couleur pour le contour communal, etc.

C'est avant tout la combinaison des tuiles vectorielles et des styles qui a permis à ce standard de s'imposer.

Généralement, on consomme ces tuiles vectorielles via une bibliothèque cartographique JavaScript. Il faut également noter que selon les bibliothèques, il est possible de profiter de la combinaison des deux mais que certains ne permettent pas de gérer les styles mais simplement de consommer les tuiles vectorielles, les pbf mais en devant styler selon la syntaxe propre à la bibliothèque. Cela joue fortement sur les choix techniques à adopter selon votre besoin. Seuls Maplibre et OpenLayers via une bibliothèque intermédiaire sont à même de correctement utiliser les deux.

Comment utiliser les tuiles vectorielles d’Etalab ?

Les versions des tuiles pour les fonds de plan ont été mises à jour en mars 2022 et sont mises à jour une fois par semaine.

Consommer les styles

Nous abordons principalement l'usage avec MapLibre qui est capable de nativement gérer les tuiles et les styles associés.

Nous n'aborderons pas Mapbox GL JS, la bibliothèque JavaScript de Mapbox, car elle n'est maintenant plus OpenSource depuis la version 2.x et c'est MapLibre, une version forkée de la dernière version de Mapbox GL JS avant son passage en version non libre, qui a pris sa succession.

Voici quelques scénarios :

Consommer les tuiles vectorielles seules

Héberger les tuiles du cadastre ou faire une extrait sur votre zone

L'alternative des tuiles vecteur de l'IGN

Selon vos besoins, vous pouvez choisir d'utiliser l'API de tuiles vectorielles de l'IGN plutôt que celles que nous mettons à disposition.

Voici deux exemples :

Qu'est-ce que le géocodage ?

Les indispensables pour réaliser un géocodage

Pour réaliser un géocodage, il est nécessaire de disposer :

• des données de référence contenant numéro, nom de rue, , code postal, nom de commune ;

• des coordonnées géographiques x et y qui sont généralement la longitude(x) et la latitude(y) ;

• une entrée correspondant à l’adresse recherchée.

Le fonctionnement d'un géocodeur

Un géocodeur transforme une donnée textuelle des données de référence en utilisant des algorithmes qui séparent l’adresse en syllabes, mots et groupes de mots.

Les différents éléments sont indexés, puis en s’appuyant sur des algorithmes relatifs à du traitement textuel, le géocodeur compare la similarité entre les mots constituant l’adresse à rechercher et ceux qui sont indexés depuis les données de référence.

Un algorithme permet généralement d’ordonner les résultats. Il s’agit par exemple de faire apparaitre en premier les résultats ayant les coordonnées fixes les plus proches ou encore ceux dont la population est la plus forte.

Il est également possible de filtrer selon des critères comme le pays (si le géocodeur a une vocation internationale, comme ) ou encore par type de résultat.

En pratique, un certain nombre de géocodeurs visent à réaliser des recherches de communes et de POIs (Points Of Interest ou points d’intérêts) et pas seulement des adresses.

Le géocodage peut aussi se faire de façon inverse, c’est-à-dire retourner une adresse en envoyant une coordonnée. Dans ce cas de figure, il s’agit de trouver la donnée de référence la plus proche des coordonnées envoyées.

Les limites du géocodage

La qualité des données de référence

Les données textuelles de l’adresse de référence ne sont pas toujours uniformes.

Exemple : "rue" peut être représenté par les lettres "r" ou "R" ou "rue" ou "Rue".

Il s’agit donc en premier lieu d’uniformiser les différentes manières de décrire le type de voie.

Il s’agit également d’omettre les articles lors d’une comparaison.

Exemple : chercher "rue métanies" au lieu de "rue des métanies".

D’un autre côté, les coordonnées géographiques peuvent manquer de précision. Dans certains cas, il arrive de disposer uniquement du centroïde de la commune, de la voie ou du lieu dit (point d’une zone géographique choisi au voisinage de son centre de gravité et dont les coordonnées servent de localisant pour cette zone).

Dans d’autres cas, les coordonnées peuvent avoir été interpolées : les adresses ont été positionnées en fonction du nombre de numéros dans une voie et la longueur de celle-ci.

Les principales problématiques liées aux adresses

Cas pratiques

Comment faire si une recherche d’adresse ne fonctionne pas ?

• • Tapez votre adresse. Par exemple, "20 avenue de Ségur". Si le numéro est bien proposé et que la commune est la bonne pour le premier résultat, c’est la manière dont vous avez récupéré l’adresse qui est en cause. Si vous êtes en mode "batch", la première adresse retournée peut être mauvaise et c’est la 2ème ou 3ème adresse que vous attendiez.

  • Imaginons que vous pensiez que le numéro existe, mais ne le trouvez pas dans votre résultat de géocodage. Essayez alors de trouver la rue. Essayons "87 avenue de Ségur". On ne voit que des rues qui sont retournées suite à la recherche. Cliquez sur la rue qui semble correspondre à votre recherche. Cela va zoomer. Vous allez pouvoir voir s’il y a des adresses et lesquelles sont inventoriées.

• La donnée de référence n’est pas présente : c’est un oubli ou personne ne l’a encore produite.

• Le résultat est une adresse BAL. Votre commune est entrée dans une démarche de recensement et valorisation de ces adresses.

  • • Zoomez sur la carte pour trouver votre commune ou l'organisme qui porte votre BAL, par exemple un intercommunalité.

    • Nous pouvons ensuite vérifier dans la liste l'existence du numéro.

• Adresse IGN vs adresse cadastre vs adresse BAL.

• La donnée est présente, mais les termes de recherche ne permettent pas de la trouver.

Comment faire de l’autocomplétion d’adresse ?

Il existe plusieurs solutions pour faire de l’autocomplétion dans un outil web.

Vous pouvez vous appuyer sur de nombreuses bibliothèques, celles-ci étant généralement liées à des bibliothèques cartographiques.

Solutions basées sur Leaflet

Exemples :

Solutions basées sur OpenLayers

Exemples :

Solutions indépendantes de bibliothèques cartographiques

Exemples :

Comment faire du géocodage par adresse unitaire ?

Avec Python, pour faire des appels unitaires, vous pouvez :

Comment réaliser un géocodage massif ?

Lorsqu'on choisit cette option, on privilégie l'appel par le endpoint CSV de l'API.

Il faut préalablement s'assurer que son CSV est bien formaté : il s'avère que le géocodage peut ponctuellement dysfonctionner si le CSV n'est pas bien formaté.

Option manuelle

Pour réaliser un géocodage massif, il faut généralement vérifier le formatage de votre CSV.

Python seul

JavaScript

Autres outils utilisant la BAN

--> Vous faites du SIG, néophyte comme expert et utilisez le logiciel SIG QGIS ?

--> Vous utilisez d’autres outils?

Si ce n’est pas le cas, vous pouvez vous autohéberger.

Quels autres géocodeurs est-il possible d'utiliser ?

Même si nous avons abordé l’usage du géocodeur Addok, utilisé par adresse.data.gouv.fr, il existe d'autres possibilités pour géocoder.

Il est ainsi possible d'installer des solutions OpenSource comme :

Une instance alternative d'Addok (http://demo.addok.xyz) est mise à disposition et contient des données venant de la BANO, des POIs d'OpenStreetMap ainsi que des intersections de rues/routes.