Questions · Adresses

Existe-t-il une API pour normaliser les adresses ?

Ce que fait l'appel

L'endpoint de vérification de contact met l'adresse dans la forme postale de son pays, et le nom qui l'accompagne. Il lit voie, numéro, code postal et ville ensemble, pas un champ à la fois, et déclare chaque correction. Le pays va dans country_code (ISO 3166-1) ou dans country, écrit comme il vient.

Un contact à la fois dans le corps de la requête, ou une liste dans le champ items, jusqu'à cinq cents par appel. Chaque appel demande un jeton, que vous générez depuis votre espace personnel une fois inscrit, et passez dans l'en-tête Authorization: Bearer. Le jeton peut recevoir une date d'expiration, ou rester valide jusqu'à ce que vous le révoquiez.

Comment revient le résultat

La réponse a deux formes de la même adresse : une lisible avec les accents, l'autre dans la forme postale pour l'impression des étiquettes, en majuscules. Vous avez besoin des deux pour des raisons différentes : la première pour montrer l'adresse à un opérateur ou dans une interface, la seconde pour l'impression proprement dite.

Avec elles, un résultat en mots-clés — correct, modifié avec le détail de ce qui a changé champ par champ, ou à contrôler quand l'adresse ne peut pas être reconstruite avec certitude, avec le motif en clair : voie introuvable dans la commune, données insuffisantes, numéro introuvable. Rien n'est jamais corrigé en silence : si nous changeons quelque chose nous le disons, et si nous ne sommes pas sûrs nous le disons tout aussi clairement au lieu de deviner. Là où le référentiel est en service vous recevez aussi les coordonnées du numéro, le code de la commune et, dans les villes qui en ont, l'arrondissement.

Adresse unitaire ou travaux en bloc

Sous les cinq cents requêtes vous avez la réponse tout de suite, dans le même appel : le cas typique d'un formulaire d'inscription ou d'un paiement, où l'adresse doit être vérifiée au moment où l'utilisateur la saisit. Pour des listes plus grandes, jusqu'à cent mille adresses en une fois, ajoutez "async": true : la requête renvoie tout de suite un code de travail et le traitement entre dans la file, la même qui gère les travaux en bloc chargés depuis le site. Vous relisez le résultat avec un GET sur le même endpoint en passant le code, en JSON ou, s'il vous faut le fichier à télécharger, en CSV.

Autocomplétion pour vos formulaires

Si vous construisez un formulaire d'adresse, /api/v1/suggest vous donne l'autocomplétion pendant la saisie : voie, ville et numéro proposés au fur et à mesure, avec le champ déjà vérifié à la sélection au lieu de devoir le contrôler après avec un appel séparé. À utiliser depuis un serveur à vous, qui fait proxy vers l'endpoint : le jeton ne doit jamais apparaître dans le navigateur de l'utilisateur final.

Quand l'intégrer a du sens

Cela a du sens quand l'adresse entre dans le fichier encore et encore, pas une seule fois : un formulaire d'inscription, un paiement e-commerce, un CRM alimenté par plusieurs canaux. La vérifier là, au moment où elle entre, évite d'accumuler des adresses incorrectes qu'il faut ensuite nettoyer en bloc avant chaque envoi. Si au contraire vous avez déjà une liste à remettre en ordre une seule fois, il est plus simple de la charger comme fichier Excel ou CSV depuis le site : même moteur, sans écrire une ligne de code.

Erreurs, limites et documentation complète

Chaque réponse a un code HTTP cohérent avec ce qui s'est passé : 401 si le jeton manque ou n'est pas valide, 413 si le lot dépasse la limite, 429 si vous avez dépassé le nombre de requêtes par minute autorisé, 402 si le crédit ne suffit pas à couvrir l'appel. Une adresse qu'on n'arrive pas à normaliser n'est pas une erreur de l'API : la réponse arrive quand même, avec le résultat qui explique pourquoi.

Sur la page API vous trouvez tous les endpoints — adresse, dédoublonnage, e-mail, téléphone, site, enrichissement du nom — avec les paramètres, les exemples curl et les codes d'erreur au complet. Si vous travaillez avec un outil qui importe des spécifications, il y a aussi openapi.json.

Un appel minimal

La réponse complète porte aussi la forme postale, le détail de chaque champ modifié, les coordonnées du numéro et les données telles que vous les avez envoyées, pour comparaison.