Le problème Pelias apparaît quand une équipe veut maîtriser sa recherche d'adresse, son autocomplete ou son reverse geocoding, mais découvre trop tard qu'un géocodeur ouvert demande aussi un vrai modèle d'index, de sources, de layers et de preuves.
Pelias n'est pas une simple route HTTP à brancher dans un formulaire. C'est une stack de géocodage open source qui transforme adresses, noms de lieux et coordonnées en GeoJSON, avec Elasticsearch, données ouvertes, parsing, hiérarchies administratives et services spécialisés.
Vous allez comprendre comment décider, corriger et industrialiser `/v1/search`, `/v1/autocomplete`, `/v1/reverse`, `/v1/search/structured`, `/v1/place`, `text`, `focus.point`, `boundary.country`, `boundary.circle`, `sources`, `layers`, `gid`, `confidence`, `label`, `bbox` et les choix d'hébergement.
Le risque n'est pas seulement d'avoir un résultat imprécis. Le risque est de confondre source, layer, identifiant temporaire, scoring et vérité métier, puis de laisser le support arbitrer des adresses que le système ne sait plus expliquer.
Pour cadrer cette architecture, notre accompagnement en intégration API aide à relier Pelias, index géographique, CRM, OMS, TMS, portail client, datawarehouse, observabilité et runbook. Le sujet se rattache aussi à la landing API cartographie et géolocalisation et à la page intégrateur Pelias.
Pour qui Pelias mérite une intégration dédiée
Identifier les usages vraiment adaptés
Pelias mérite une intégration dédiée quand l'entreprise veut contrôler l'index de recherche, choisir ses sources, héberger un géocodeur, prioriser les résultats locaux ou réduire une dépendance directe à un fournisseur propriétaire.
Le cas typique concerne un portail qui doit rechercher des adresses, des établissements, des communes ou des points d'intérêt avec une logique métier propre, plutôt qu'afficher seulement le premier résultat d'une API commerciale.
Le signal de priorité est simple: si un résultat Pelias modifie une promesse de livraison, une zone de service, une affectation terrain ou une fiche client, alors le flux mérite un contrat de run complet.
Contrairement à ce que laisse penser un premier test rapide, la difficulté ne vient pas de faire répondre Pelias, mais de garantir que le même cas sera expliqué après plusieurs mois, un rebuild et plusieurs corrections métier.
Séparer géocodage, cartographie et routing
Pelias sert au géocodage, à l'autocomplete, au reverse geocoding et à la recherche de lieux. Il ne remplace pas une API de routing, un moteur d'itinéraires ou un service de calcul de matrice.
Cette séparation évite les promesses trop larges. Une application peut très bien utiliser Pelias pour trouver une adresse, puis Valhalla, OpenRouteService, HERE, TomTom ou un autre moteur pour calculer un trajet.
Le cadrage doit donc dire quelle brique répond à quelle question: Pelias identifie le lieu, la carte l'affiche, le routing calcule le chemin, et le SI métier décide quoi faire.
Le coût caché apparaît quand cette frontière n'est pas écrite. Une erreur de géocodage devient alors une erreur de tournée, puis une charge support, alors que le problème initial venait seulement d'une responsabilité floue.
1. Comprendre les endpoints Pelias
Utiliser `/v1/search` pour la recherche complète
L'endpoint `/v1/search` transforme une requête textuelle en résultats géographiques. Le paramètre `text` porte la requête, tandis que `size`, `focus.point`, `boundary.country`, `boundary.rect`, `boundary.circle`, `sources` et `layers` cadrent le résultat.
Cette recherche convient quand l'utilisateur valide une adresse complète, un nom de lieu ou une requête assez explicite. Elle est plus stable pour une décision finale qu'une suggestion partielle affichée pendant la saisie.
Le connecteur doit conserver la requête, les paramètres de filtrage et le résultat choisi. Sans cette trace, il devient impossible d'expliquer pourquoi une adresse a été retenue au lieu d'une homonyme.
Le contrat REST interne peut être documenté dans OpenAPI et rejoué dans Postman ou Insomnia avec les vrais payloads. Cette preuve évite de confondre succès HTTP, décision métier et qualité de géocodage.
Utiliser `/v1/autocomplete` pour le type-ahead
L'endpoint `/v1/autocomplete` sert aux suggestions pendant la saisie. Il accepte aussi `text`, `size`, `focus.point`, `sources` et `layers`, mais il doit être piloté avec une logique UX plus stricte.
La documentation Pelias recommande de tenir compte des frappeurs rapides, des réponses asynchrones et du throttling. Un champ qui envoie trop d'appels peut dépasser les limites du service et afficher des résultats obsolètes.
Le produit doit envoyer moins de requêtes, annuler les réponses dépassées et confirmer le choix avec `/v1/search` quand la décision devient métier. L'autocomplete aide l'utilisateur, mais il ne doit pas signer seul une adresse critique.
Si un SDK front existe dans le projet, il doit encapsuler debounce, annulation, token interne, timeout et versioning du schéma. Le composant d'interface ne doit pas réinventer ces règles écran par écran.
Utiliser `/v1/reverse` pour relire une coordonnée
L'endpoint `/v1/reverse` part de `point.lat` et `point.lon` pour retrouver des adresses, POI, quartiers, villes, régions ou pays proches. Il répond en GeoJSON comme les autres endpoints Pelias.
Les paramètres `boundary.circle.radius`, `size`, `layers`, `sources`, `boundary.country` et `boundary.gid` permettent de limiter le résultat. La documentation précise que le rayon reverse est limité pour protéger les accès disque.
Le reverse doit rester associé au contexte terrain. Une coordonnée GPS bruitée, une position prise en intérieur ou un point proche d'une frontière ne doivent pas produire une décision irréversible sans contrôle.
Le signal faible se voit quand le support corrige souvent les mêmes points terrain sans incident serveur. À ce moment, la dette vient plutôt du rayon, du layer accepté ou du seuil de distance.
2. Cadrer search, autocomplete et focus
Choisir entre recherche mondiale et recherche bornée
Pelias peut chercher dans le monde entier ou limiter les résultats par pays, rectangle, cercle ou parent administratif avec `boundary.gid`. Ce choix change la qualité métier, pas seulement la performance.
Une application locale peut borner fortement les résultats, tandis qu'un support national doit garder plus d'ouverture pour corriger un pays, une commune ou une adresse mal renseignée par l'utilisateur.
Si 4 % des adresses valides disparaissent après ajout d'une frontière stricte sur 7 jours, alors le filtre doit être revu avant généralisation. Le coût caché se voit vite dans tickets support et abandons.
Une revue hebdomadaire des refus par `boundary.country` ou `boundary.gid` suffit souvent au départ. Si 20 cas légitimes sont rejetés dans une semaine, la règle est trop stricte pour le parcours.
Prioriser avec `focus.point` sans enfermer l'utilisateur
Le paramètre `focus.point` remonte les résultats proches d'une coordonnée sans empêcher des lieux plus éloignés d'apparaître. Il est différent d'une restriction comme `boundary.circle`.
Ce comportement est utile pour une recherche autour d'une carte, d'un magasin ou d'une position courante. Il devient dangereux si le produit fait croire que les résultats éloignés sont impossibles.
Le front doit afficher un indice clair quand le focus influence l'ordre. Le support doit aussi retrouver la coordonnée de focus pour comprendre pourquoi un résultat local est passé devant une ville plus connue.
Le bon arbitrage consiste à garder `focus.point` comme biais tant que l'utilisateur explore, puis à demander une confirmation explicite dès que la sélection modifie une commande, un rendez-vous ou un compte client.
Throttler l'autocomplete comme un parcours produit
La documentation Pelias indique que les tests d'autocomplete trouvent souvent un bon équilibre entre 5 et 10 requêtes par seconde, mais chaque service peut imposer ses propres limites.
Le connecteur doit donc traiter le throttling côté client et côté proxy. Il doit ignorer les réponses arrivées dans le mauvais ordre, car une requête courte peut revenir après une requête plus précise.
Une règle simple protège l'expérience: une suggestion aide à choisir, mais la validation finale doit enregistrer le résultat complet, le `gid`, le `label`, la source, le layer et les paramètres utilisés.
Si le p95 de l'autocomplete dépasse 800 ms pendant 30 minutes, alors le proxy doit réduire la taille, renforcer le cache ou désactiver les sources secondaires avant que la conversion ne baisse.
3. Cadrer reverse, structured et place
Qualifier le reverse par couche et distance
Un reverse Pelias peut retourner une adresse, un POI, une rue, un quartier, une ville ou un pays. Le paramètre `layers` devient donc indispensable quand le métier attend précisément une ville ou une adresse.
La réponse reverse contient une distance en kilomètres et un score de confiance lié à l'éloignement du point. Cette information doit apparaître dans le modèle interne, surtout pour les positions imprécises.
Si une application terrain accepte un résultat au-delà de 250 mètres sans revue, alors elle risque de rattacher une intervention au mauvais lieu. Un seuil métier doit encadrer cette décision.
Employer `/v1/search/structured` avec prudence
L'endpoint `/v1/search/structured` permet de séparer `address`, `neighbourhood`, `borough`, `locality`, `county`, `region`, `postalcode` et `country` quand les données sont déjà découpées par le SI.
La documentation officielle indique que cet endpoint est en beta et moins éprouvé que `/v1/search`. Il faut donc le qualifier sur les vrais formats d'adresses avant de le généraliser.
La recherche structurée devient pertinente pour un fichier d'adresses ou un back-office qui possède déjà ville, code postal et pays. Elle réduit certaines ambiguïtés, mais elle ne corrige pas une donnée source incohérente.
Le batch structuré doit rester rejouable. Chaque ligne doit porter une clé d'idempotence, un statut de sortie et une cause de rejet, sinon la réconciliation avec ERP, CRM, PIM, OMS ou WMS devient manuelle.
Utiliser `/v1/place` sans inventer les `gid`
L'endpoint `/v1/place` relit un lieu à partir d'un identifiant `gid` renvoyé par Pelias. Cet identifiant ne doit pas être construit manuellement ni analysé comme une clé métier universelle.
La documentation prévient que certains `gid` peuvent changer quand des données ouvertes sont réimportées. OpenStreetMap et OpenAddresses sont particulièrement sensibles à cette instabilité dans le temps.
Le SI doit donc stocker son propre identifiant métier et conserver le `gid` comme preuve de recherche. Si un `gid` expire après un rebuild, la fiche client ne doit pas devenir orpheline.
Une stratégie robuste conserve aussi l'ancien `gid`, le nouveau résultat et la date de comparaison. Cette trace permet de décider si la différence relève d'un meilleur index ou d'une rupture de contrat.
4. Modéliser GeoJSON, gid et confidence
Traiter la réponse comme un contrat GeoJSON
Pelias répond normalement avec une `FeatureCollection` GeoJSON qui contient `geocoding`, `features` et parfois `bbox`. Chaque feature porte une géométrie de type point et des propriétés lisibles.
Les coordonnées GeoJSON sont dans l'ordre longitude puis latitude. Cette règle doit être testée explicitement, car l'inversion lat/lon crée des erreurs spectaculaires et pourtant difficiles à repérer dans un mapping.
Le modèle interne doit garder `name`, `label`, `source`, `layer`, `source_id`, `country`, `region`, `locality`, `confidence`, `bbox` et les champs utiles au support. Le front n'a pas besoin de tout exposer.
Le payload normalisé doit préciser ses entrées, ses sorties, son schema versionné, ses responsabilités, son owner et sa politique de compatibilité. Cette discipline rend le middleware plus facile à tester.
Interpréter `confidence` sans en faire une vérité absolue
Le score `confidence` aide à lire la qualité d'un résultat, mais il dépend du contexte. En recherche, il reflète notamment la correspondance entre texte parsé, résultat et biais géographique.
En reverse, la confiance dépend surtout de la distance entre la coordonnée demandée et le résultat retourné. Un score élevé n'a donc pas exactement le même sens selon l'endpoint utilisé.
Le bon modèle combine endpoint, distance, source, layer, score et décision métier. Si une adresse modifie une livraison, un seuil unique de confidence ne suffit pas à prouver la qualité.
Une règle plus saine sépare score technique et acceptation métier. Par exemple, une confidence élevée peut rester insuffisante si le layer est `locality` alors que le tunnel exige `address`.
Préserver `gid`, `source` et `layer` séparément
Le `gid` Pelias combine une source, un layer et un identifiant quand l'information existe. Les propriétés `source`, `layer` et `source_id` restent pourtant plus lisibles pour les règles métier.
Le connecteur doit conserver ces champs séparément. Une règle qui accepte `layer=address` ne doit pas produire le même statut qu'une règle qui accepte `layer=venue` ou `layer=locality`.
Si une même saisie retourne d'abord un POI puis une adresse après rebuild, le support doit voir la différence. Sinon, la correction ressemble à une anomalie aléatoire alors qu'elle vient du modèle d'index.
Le reporting doit compter ces bascules par source et par layer. Si 2 % des sélections changent de layer après rebuild, l'élargissement du périmètre doit attendre une recette complémentaire.
5. Choisir sources, layers et obligations data
Comprendre les sources officielles supportées
Pelias s'appuie sur plusieurs sources ouvertes, notamment OpenStreetMap, OpenAddresses, WOF et GeoNames. Les paramètres `sources` acceptent aussi des alias comme `osm`, `oa`, `wof` et `gn`.
Chaque source a ses forces. OpenAddresses est très utile pour les adresses issues d'autorités publiques, OpenStreetMap apporte routes, bâtiments et POI, WOF structure l'administratif, GeoNames complète certains lieux.
Le choix des sources doit être explicite par parcours. Un champ de livraison, une recherche de commune et une recherche de POI n'ont pas besoin du même compromis entre couverture, précision et stabilité.
Le signal faible se voit quand les corrections support citent toujours la même source, mais que le dashboard ne ventile pas les erreurs par `openstreetmap`, `openaddresses`, `wof` ou `geonames`.
Filtrer par layer pour éviter les faux amis
Pelias classe les résultats par layers comme `venue`, `address`, `street`, `neighbourhood`, `locality`, `region`, `country`, `coarse` ou `postalcode`. Ces layers doivent être traduits en statuts métier.
Une recherche "Paris" peut renvoyer une ville, une rue, un établissement ou un autre objet selon le contexte et les données. Le produit doit savoir quel type de résultat il accepte.
Si un tunnel de commande attend une adresse complète, il doit refuser une localité seule ou demander un complément. Ce refus doit être un statut normal, pas une erreur obscure.
Le back-office doit afficher le layer accepté et le layer refusé dans le même vocabulaire. Cette lecture évite qu'une commune validée devienne une adresse complète par simple confort d'interface.
Respecter licences et attribution des données
Les sources ouvertes imposent des obligations. OpenStreetMap utilise l'ODbL avec attribution et share-alike, tandis que les sources OpenAddresses peuvent avoir des licences différentes selon les contributeurs.
La documentation Pelias précise que les informations de licence ne sont pas toujours retournées directement dans chaque réponse. L'équipe doit donc gouverner l'attribution et les obligations au niveau de la source.
Le runbook doit indiquer quelles sources sont activées, quelles mentions sont affichées et quelles réutilisations sont autorisées. Un bon géocodeur respecte aussi la chaîne de données qui le rend possible.
La conformité doit être revue avant export massif ou synchronisation partenaire. Si un flux EDI réutilise des coordonnées enrichies, la licence de la source doit être vérifiée avant diffusion.
6. Architecturer une instance Pelias
Comprendre le rôle de l'API et d'Elasticsearch
Le serveur API Pelias est le point d'entrée HTTP. Il interroge Elasticsearch et les services disponibles pour renvoyer des résultats GeoJSON sur search, autocomplete, reverse, structured et place.
Elasticsearch devient donc un composant critique du run. Index, mapping, taille, mémoire, snapshots, monitoring et rebuild doivent être traités comme des sujets de production, pas comme un détail d'installation.
Si l'index change sans version ni campagne de non-régression, les résultats peuvent évoluer sans incident technique visible. C'est souvent là que les écarts support deviennent les plus difficiles à expliquer.
Un rebuild doit donc produire un changelog exploitable: volume importé, sources incluses, durée, erreurs, snapshot Elasticsearch, jeu de comparaison et seuils de rollback. Sans cela, le monitoring reste trop pauvre.
Décider les services nécessaires au périmètre
Placeholder aide à traiter les relations administratives et les langues, Libpostal parse les adresses complètes, PIP sert au point-in-polygon et Interpolation estime des adresses absentes des sources directes.
Tous les services ne sont pas utiles au même niveau. La documentation Pelias indique que l'API est requise partout, Placeholder et Libpostal comptent pour search, PIP est très important en reverse, Interpolation reste optionnel.
Le cadrage doit donc partir des parcours. Une instance pour autocomplete simple, une instance pour reverse territorial et une instance mondiale avec adresses interpolées n'ont pas le même coût de build ni de run.
Le choix doit aussi intégrer throughput attendu, latence cible, mémoire disponible et niveau de SLA. Une instance interne sans astreinte claire peut devenir plus risquée qu'un service hébergé correctement contractualisé.
Évaluer Docker, zone pilote et full planet
Le projet Docker Pelias propose des exemples de build, notamment une zone Portland pour se familiariser avec la stack. Cette approche permet de tester les commandes avant un périmètre plus large.
Les builds géographiques peuvent télécharger des dizaines de Go et demander une mémoire importante. La documentation Docker indique au moins 8 Go de RAM, avec des durées très différentes selon zone, machine et services.
Une entreprise doit donc commencer par une zone pilote et des tests métier. Construire trop vite un full planet sans besoin prouvé ajoute stockage, temps de rebuild et complexité de monitoring.
Le risque est de croire que plus de données donne mécaniquement plus de qualité. En réalité, une zone réduite mais bien qualifiée peut mieux servir le métier qu'un index mondial impossible à gouverner.
7. Industrialiser proxy, cache et limites
Placer un proxy métier devant Pelias
Un proxy métier protège Pelias des appels directs, ajoute l'authentification, impose les paramètres autorisés, journalise les décisions et traduit les réponses dans un contrat interne stable.
Le front ne doit pas décider seul quelles sources, quels layers ou quels rayons sont autorisés. Ces choix ont un impact de qualité, de performance, de coût et de conformité data.
Si 80 % des appels viennent d'un seul écran pendant 10 minutes, le proxy doit pouvoir ralentir ce parcours sans bloquer toute la géolocalisation. La priorité doit rester pilotable.
Le proxy peut aussi porter OAuth2, JWT, IAM interne, rate limit, circuit breaker et journalisation. Pelias reste concentré sur le géocodage, tandis que le middleware porte les règles de sécurité et d'exploitation.
Mettre en cache sans masquer la fraîcheur
Le cache réduit la charge et stabilise l'expérience, mais il doit rester visible. Une réponse issue d'un cache ancien n'a pas la même valeur qu'une réponse calculée après un rebuild récent.
Le connecteur doit tracer clé de cache, date de calcul, version d'index, sources activées et paramètres. Cette preuve permet de comprendre pourquoi deux utilisateurs ne voient pas exactement le même résultat.
Une règle raisonnable consiste à différencier cache de suggestion, cache de décision et cache de diagnostic. Les durées ne doivent pas être identiques quand l'impact métier change.
La queue de retry doit rester idempotente et utiliser un backoff borné. Si le cache est vide et que Pelias ralentit, le runbook doit dire quoi rejouer, quoi attendre et quoi bloquer.
Gérer taille, timeouts et erreurs exploitables
Le paramètre `size` contrôle le nombre de résultats. L'API Pelias expose aussi des limites comme `minSize`, `maxSize` et `defaultSize` dans sa configuration, avec un défaut de 10 résultats courant.
Les timeouts doivent être pensés par endpoint. Un autocomplete doit répondre vite ou être annulé, tandis qu'une reprise back-office peut tolérer plus de délai si elle produit une preuve complète.
Les erreurs doivent être traduites en statuts: requête invalide, source refusée, layer interdit, index indisponible, réponse vide, résultat ambigu ou délai dépassé. Le support ne doit pas lire seulement un code HTTP.
La sandbox doit inclure pagination, taille maximale, timeout, payload invalide et réponse vide. Ces cas paraissent basiques, mais ils évitent de découvrir en production que le contrat-first est incomplet.
8. Plan d'action Pelias
Prioriser le premier parcours utile
Le premier parcours doit être celui qui prouve la valeur sans ouvrir toute la complexité. Un champ d'adresse critique, une recherche de point de service ou un reverse terrain suffit souvent à cadrer Pelias.
L'équipe doit écrire la décision attendue avant le paramétrage: proposer, confirmer, refuser, mettre en attente ou demander un complément. Cette décision pilote ensuite endpoint, sources, layers, cache et support.
Un seuil de sortie simple aide le lancement: 100 recherches réelles rejouées, moins de 2 % de résultats inconnus, zéro inversion lat/lon et une fiche support capable d'expliquer les 10 cas les plus fréquents.
Prototyper sur une zone et un jeu de données contrôlés
Le prototype doit utiliser une zone limitée, un fichier d'adresses représentatif et des cas volontairement difficiles. Homonymes, accents absents, communes voisines, POI ambigus et frontières révèlent vite les défauts.
Cette étape sert à comparer `/v1/search`, `/v1/autocomplete`, `/v1/reverse` et `/v1/search/structured` sur les mêmes cas. Le résultat attendu n'est pas seulement un score, mais une décision explicable.
Si la zone pilote échoue sur 15 % des adresses métier, élargir l'index ne résoudra pas le problème. Il faut d'abord corriger sources, layers, normalisation ou messages utilisateur.
En priorité, le prototype doit être rejoué par une personne métier. Si elle ne sait pas expliquer pourquoi une suggestion est acceptée ou refusée, l'équipe technique n'a pas encore livré une preuve exploitable.
Construire le modèle interne avant le front
Le modèle interne doit être défini avant l'interface. Il doit préciser `label`, coordonnées, source, layer, `gid`, confidence, distance, statut métier, version d'index, cache et date de décision.
Cette couche évite de laisser chaque écran interpréter Pelias à sa manière. Elle permet aussi de changer d'instance, de fournisseur ou de stratégie de sources sans casser tous les consommateurs.
Le front peut alors rester simple: afficher une suggestion, demander une confirmation, signaler une ambiguïté et conserver la preuve. La complexité reste dans le middleware, où elle est testable.
La normalisation doit prévoir les événements internes. Pelias ne fournit pas un webhook métier de décision; si ERP ou CRM doivent être notifiés, le middleware doit émettre son propre event après validation.
Développer observabilité et runbook ensemble
Les logs doivent raconter une histoire complète: endpoint, paramètres, utilisateur ou système appelant, durée, cache hit, index, résultat choisi, résultat rejeté, statut métier et action support.
Le runbook doit répondre aux mêmes questions que les logs. Que faire si l'index est indisponible, si un `gid` expire, si un résultat change après rebuild ou si le reverse retourne un POI inattendu?
Une alerte utile inclut un seuil et une décision. Par exemple, plus de 5 % de résultats ambigus pendant 24 heures doit bloquer l'élargissement et déclencher une revue de sources ou de layers.
Le plan d'instrumentation doit relier métriques techniques et actions. Latence, timeout, cache hit, taux de réponse vide et correction support doivent finir dans le même tableau, avec un owner nommé.
Préparer le passage en instance dédiée
Une instance dédiée devient pertinente quand les volumes, la souveraineté, la personnalisation des sources ou les contraintes de latence dépassent ce qu'un service mutualisé peut garantir proprement.
Le passage doit être réversible. L'application doit pouvoir changer d'endpoint, garder son modèle interne, comparer deux index et afficher une consigne claire quand les résultats diffèrent.
La décision ne doit pas être prise seulement sur le coût serveur. Elle doit intégrer temps de rebuild, monitoring Elasticsearch, stockage, sauvegarde, données sous licence, support et compétence d'exploitation.
Par exemple, si l'instance dédiée réduit 40 tickets support mensuels mais demande 2 jours de run par mois, alors le seuil de décision doit être assumé par produit et opération.
9. Erreurs fréquentes avec Pelias
Les pièges qui cassent la qualité
- Traiter Pelias comme un moteur de routing, puis lui demander des distances ou itinéraires qui relèvent d'une autre brique.
- Stocker seulement le `label` et les coordonnées, sans conserver source, layer, `gid`, confidence, distance et version d'index.
- Lancer l'autocomplete sans throttling, sans annulation des réponses anciennes et sans recherche finale de confirmation.
- Confondre `focus.point` avec une frontière stricte, puis masquer des résultats légitimes à un support national.
- Utiliser un `gid` comme identifiant métier permanent, alors que certains jeux de données changent après réimport.
Ces erreurs restent discrètes au prototype, car Pelias répond vite et proprement. Elles deviennent visibles quand le trafic monte, que l'index change ou que le support doit justifier une adresse contestée.
Le bon arbitrage consiste à refuser une nouvelle famille d'appels tant que endpoint, sources, layers, cache, owner, fallback et preuve ne sont pas écrits dans le contrat interne.
Cette rigueur protège aussi la réputation du géocodeur. Une mauvaise intégration peut faire croire que Pelias est imprécis, alors que le problème vient souvent du choix de sources ou du mapping aval.
Au début, ces pièges ressemblent à de simples détails de configuration, mais ils deviennent visibles quand un incident oblige à rejouer 500 recherches sans savoir quel index avait répondu.
Reconnaître les limites de données ouvertes
Les données ouvertes évoluent. Une adresse peut apparaître, disparaître, changer de classification ou recevoir un meilleur parent administratif après mise à jour. Le connecteur doit assumer cette réalité.
La qualité ne se pilote donc pas seulement avec une moyenne de succès. Il faut suivre les cas changés après rebuild, les résultats vides, les homonymes, les POI promus et les corrections support.
Si plus de 3 % des décisions métier changent après une réindexation, alors la mise à jour doit passer par une recette dédiée avant exposition à tous les utilisateurs.
Le rapprochement doit comparer l'ancien résultat, le nouveau résultat et l'impact. Cette réconciliation évite de transformer une amélioration de donnée ouverte en rupture silencieuse pour le back-office.
10. Recette, rollback et support Pelias
Tester les familles d'appels avant ouverture
La recette doit couvrir recherche libre, autocomplete, reverse, structured, place, réponse vide, résultat ambigu, source filtrée, layer interdit, focus différent, cache expiré et index indisponible.
Chaque cas doit produire une preuve: endpoint, paramètres, statut HTTP, durée, cache, source, layer, `gid`, confidence, distance éventuelle, résultat retenu, résultat refusé et décision métier.
Un seuil de sortie protège le lancement: 100 % des appels critiques traçables, zéro inversion de coordonnées, moins de 2 % d'ambiguïtés non classées et fallback documenté pour chaque parcours.
La recette doit être exécutable hors poste développeur avec collection Postman, exemples OpenAPI, données sandbox et consignes de rollback. Cette autonomie révèle vite les zones encore trop abstraites.
Préparer un rollback sans casser l'adresse
Le rollback ne doit pas supprimer toute la recherche. Il peut réduire l'autocomplete, désactiver une source, revenir à un index précédent, basculer fournisseur ou placer les résultats ambigus en revue.
Si 3 incidents critiques touchent la même famille d'adresses en 24 heures, si le cache est contourné ou si plus de 5 % des résultats changent après rebuild, le mode contrôlé doit s'activer.
Cette approche garde les usages fiables ouverts. Elle évite le faux choix entre couper toute la géolocalisation et laisser un index instable décider silencieusement pour le métier.
Le rollback doit être testé avec un vrai changement d'endpoint. Si la bascule prend plus de 20 minutes en recette, elle prendra trop longtemps pendant un incident client.
Donner au support une lecture actionnable
La fiche support doit traduire Pelias en statuts lisibles: adresse confirmée, lieu ambigu, résultat trop éloigné, source refusée, layer insuffisant, index indisponible, cache utilisé ou recherche à compléter.
Le support doit pouvoir répondre à quatre questions: quelle requête a été envoyée, quelle instance a répondu, pourquoi le résultat a été accepté, et quelle action est autorisée quand l'utilisateur conteste.
Si une personne qui n'a pas participé au projet ne peut pas expliquer un cas simple en moins de 15 minutes, alors l'intégration fonctionne techniquement mais n'est pas encore prête pour un run autonome.
La fiche support doit contenir des exemples acceptés et refusés. Une adresse complète, une commune seule, un POI proche et un résultat vide doivent produire quatre réponses différentes.
Mesurer la stabilité après mise en production
Les 30 premiers jours doivent suivre par parcours: appels, latence, erreurs, cache hit, requêtes bloquées par policy interne, ambiguïtés, corrections manuelles, tickets support et changements après rebuild.
Cette mesure décide les extensions. Un parcours stable peut être élargi, tandis qu'un parcours ambigu doit être limité, corrigé ou déplacé vers fournisseur ou instance dédiée avant de toucher plus d'utilisateurs.
Le bon résultat n'est pas seulement une coordonnée trouvée. Le bon résultat est une décision géographique traçable, conforme aux sources utilisées, compréhensible par le support et soutenable dans le temps.
Si, après 30 jours, les questions support répétées baissent de 30 % et que les seuils restent stables, alors le seuil d'élargissement peut être validé par produit, support et opération.
Questions fréquentes Pelias
À quoi sert l'API Pelias ? Pelias sert à rechercher des lieux avec `/v1/search`, à proposer des suggestions avec `/v1/autocomplete`, à faire du reverse geocoding avec `/v1/reverse`, à rechercher des champs séparés avec `/v1/search/structured` et à relire un lieu avec `/v1/place`.
Pelias remplace-t-il Google Maps ou un moteur de routing ? Pelias peut remplacer ou compléter une brique de géocodage, mais il ne remplace pas une carte, une matrice de distances ou un calcul d'itinéraire. Ces fonctions doivent être branchées séparément.
Dawap peut-il accompagner une intégration Pelias ? Oui. Dawap accompagne le cadrage, le développement et l'industrialisation de flux Pelias pour search, autocomplete, reverse, structured, place, cache, proxy, observabilité et instance dédiée.
Guides complémentaires après Pelias
La ressource API Nominatim complète Pelias avec un angle utile sur l'usage responsable d'un géocodeur OpenStreetMap public, ses limites et ses règles de cache.
La ressource API GeoNames prolonge Pelias avec une lecture centrée sur les lieux, hiérarchies, toponymes, identifiants géographiques et usages de référentiel dans un SI métier.
La ressource rate limiting API aide à cadrer les limites, throttles, files d'attente et arbitrages de priorité quand l'autocomplete ou le reverse montent en charge.
La landing API cartographie et géolocalisation permet de relier ce sujet à l'offre métier correspondante, tandis que la page intégrateur Pelias précise l'accompagnement possible pour un géocodeur ouvert maîtrisé.
Conclusion opérationnelle Pelias
Une intégration Pelias réussie ne se mesure pas au premier résultat affiché. Elle se mesure à la capacité de l'équipe à expliquer source, layer, `gid`, confidence, cache, index et décision métier.
Le bon ordre reste stable: cadrer le parcours, choisir les sources, définir les layers, versionner le modèle GeoJSON, protéger Pelias par un proxy, tester les rebuilds et donner au support une preuve lisible.
Si vous devez brancher Pelias dans une architecture métier robuste, notre accompagnement en intégration API peut cadrer endpoints, index, cache, observabilité et instance dédiée sans déplacer la dette vers le support.
