Passer d'api-adresse.data.gouv.fr au géocodage de la Géoplateforme

Ce qui a changé, et où en est l'ancienne adresse

Le 27 septembre 2026 à 19 h, nous avons envoyé la même requête, « 8 bd du port amiens », aux deux adresses. Les deux ont répondu 200 en un peu plus de 200 millisecondes, avec le même corps de 582 octets et le même etag. Même libellé, « 8 Boulevard du Port 80000 Amiens », même score, même identifiant BAN. Le géocodage inverse sur la place Victor-Hugo de Grenoble et le géocodage d'un fichier CSV ont donné le même résultat, ligne pour ligne.

La différence est dans les en-têtes de l'ancienne adresse. Elle en porte une série que la nouvelle n'a pas : deprecation et sunset datés du 31 janvier 2026, x-api-deprecated: true, x-api-migration: permanent, x-api-new-host qui donne la nouvelle URL, un location qui pointe vers le même chemin sur data.geopf.fr, et un x-api-notice en toutes lettres : « L'URL api-adresse.data.gouv.fr va être décommissionnée. » Un dernier, x-infra: gpf, dit que la réponse sort déjà de l'infrastructure de la Géoplateforme.

La règle : l'ancienne adresse n'est plus qu'un relais vers la nouvelle, et la date de fin écrite dans la documentation est dépassée depuis huit mois. Tant qu'elle répond, rien ne casse. Le jour où elle s'arrête, aucun préavis supplémentaire n'est promis. Migrez maintenant.

Ce qui change dans vos appels : l'URL, et presque rien d'autre

Un code qui appelle /search/?q=... n'a qu'une chose à changer : la racine. Le moteur est le même (la BAN reste la source des adresses, actualisée chaque semaine selon la documentation), les paramètres sont les mêmes, et la réponse garde sa forme GeoJSON avec label, score, id, banId, citycode, context et les coordonnées Lambert 93 en x et y.

Le getCapabilities est la vraie nouveauté pour un développeur : il décrit en JSON chaque opération, chaque paramètre, ses valeurs par défaut et ses exemples. C'est lui qu'il faut lire avant d'écrire un client, pas un billet de blog de 2022.

Les limites de débit : 50 par seconde, puis un 429

Le 27 septembre 2026, nous avons lancé 80 requêtes simultanées sur data.geopf.fr/geocodage/search depuis une même adresse IP. Résultat : 50 réponses 200 et 30 réponses 429. La requête suivante portait retry-after: 3. La documentation de cartes.gouv.fr décrit exactement ce comportement : 50 appels par IP et par seconde, un blocage de 5 secondes au-delà, et un retry-after qui décroît dès que la sur-sollicitation cesse.

Les deux adresses annoncent la même limite dans leurs en-têtes (ratelimit-limit: 50). La bascule ne vous fait donc rien gagner en débit. Deux cas posent problème. Un script qui géocode un fichier ligne à ligne sans pause, d'abord : il passe les 50 premières lignes et prend un mur de 429 sur les suivantes. Un serveur qui relaie la saisie de tous vos visiteurs ensuite, parce que la limite s'applique à son IP, pas à celle du visiteur.

Pour le premier cas, le fichier CSV est la bonne réponse : un appel, jusqu'à 200 000 lignes. Au-delà, la Géoplateforme propose un géocodage asynchrone par projet, pour des fichiers jusqu'à 1 Go. Pour le second, appelez l'API depuis le navigateur du visiteur quand c'est possible : l'en-tête access-control-allow-origin: * le permet, et chaque visiteur compte alors pour lui-même. Un acteur public qui bute régulièrement sur la limite peut demander à l'IGN d'étudier sa levée, par le formulaire de contact de geoservices.

Ce que la Géoplateforme ajoute à l'ancienne API

La même URL cherche désormais dans trois index, choisis par le paramètre index. address est le défaut et reste la BAN. poi interroge les lieux nommés de la BD TOPO : « col du coq » rend le col de Saint-Pierre-de-Chartreuse, classé « col », avec son code commune et son département. parcel retrouve une parcelle cadastrale par son identifiant, depuis le Parcellaire Express. Les deux derniers sont actualisés chaque trimestre, pas chaque semaine.

Le changement du 22 avril 2026 a ajouté le filtre depcode et les valeurs multiples : postcode et citycode acceptent jusqu'à 50 valeurs séparées par des virgules, depcode jusqu'à 10. Une recherche « place victor hugo » limitée à depcode=38,73 nous a rendu Grenoble, Vienne et Aix-les-Bains, et rien d'autre.

Un point d'attention : l'autocomplétion proposée à part, sur /completion, ne parle pas le format de /search. Elle rend un objet status et une liste results avec x, y, fulltext et kind, pas un GeoJSON. Si vous branchez un champ de saisie dessus, écrivez un adaptateur, ne réutilisez pas le code de lecture de /search.

Une recherche de lieu nommé prend tout son sens sur une carte de randonnée, où l'on cherche un col, un refuge ou un parking plus souvent qu'un numéro de rue.

La carte du Parc naturel régional de Chartreuse, telle qu'elle s'intègre sur un site : on y cherche une adresse, un col ou un départ de sentier, et les itinéraires et les lieux autour s'affichent.

Migrer en cinq étapes

Une bascule sans surprise tient en une demi-journée pour un site ordinaire. L'ordre compte plus que la durée.

1. 1

   Trouver tous les appels

   Cherchez api-adresse.data.gouv.fr dans le code, la configuration, les variables d'environnement, les scripts d'import et les outils no-code (Zapier, Make, tableurs). Les appels oubliés sont presque toujours dans un script lancé une fois par mois.

2. 2

   Remplacer la racine, et elle seule

   Mettez https://data.geopf.fr/geocodage dans une variable de configuration. Gardez les chemins /search, /reverse et /search/csv, et les paramètres tels quels.

3. 3

   Comparer sur un échantillon

   Passez cent adresses réelles aux deux URL et comparez label, score et id. Le 27 septembre 2026, les réponses étaient identiques : un écart est le signe d'une URL mal réécrite, pas d'une différence de moteur.

4. 4

   Respecter le 429

   Lisez retry-after, attendez, relancez. Pour un volume, passez par le CSV plutôt que par une boucle d'appels unitaires.

5. 5

   Surveiller la fin de l'ancienne adresse

   Une fois la bascule faite, un test automatique qui échoue si api-adresse.data.gouv.fr réapparaît dans le code évite le retour en arrière par copier-coller.

Un appel à la Géoplateforme qui respecte le 429

const GEOCODAGE = 'https://data.geopf.fr/geocodage';

async function geocode(q, { limit = 5, tries = 3 } = {}) {
  const url = `${GEOCODAGE}/search?q=${encodeURIComponent(q)}&limit=${limit}`;
  for (let i = 0; i < tries; i++) {
    const res = await fetch(url);
    if (res.status === 429) {
      const wait = Number(res.headers.get('retry-after')) || 5;
      await new Promise(r => setTimeout(r, wait * 1000));
      continue;
    }
    if (!res.ok) throw new Error(`Géocodage : ${res.status}`);
    return (await res.json()).features;
  }
  throw new Error('Géocodage : limite de débit dépassée');
}