Surveillez l'utilisation de votre clé avant d'atteindre une limite
Surveiller vos en-têtes de quota au fil de l'eau vous indique quand une limite approche, bien avant qu'une requête ne soit effectivement refusée.
Prévoir une solution de repli quand une recherche ne renvoie aucun résultat
Une requête qui aboutit sans contenir de résultat utile est facile à mal gérer, car elle ne ressemble pas à un échec au niveau HTTP : elle ne contient simplement pas la réponse que vous espériez.
À quoi ressemble un résultat vide
Une recherche de géocodage direct portant sur quelque chose de trop vague ou d'entièrement fictif renvoie un statut 200 avec un tableau de résultats vide, et non un code d'erreur.
GET /v1/forward?q=xyzzy nonexistent place&limit=1{
"status": "ok",
"query": "xyzzy nonexistent place",
"results": []
}Une recherche d'IP portant sur une adresse d'une plage non attribuée ou privée renvoie found: false plutôt qu'une erreur, accompagné des champs qu'elle peut malgré tout renseigner.
{
"status": "ok",
"ip": "10.0.0.5",
"version": 4,
"found": false
}Construire un chemin de repli explicite
Traitez un tableau de résultats vide, ou found: false, comme une branche à part dans votre code, distincte à la fois du chemin de réussite et de la gestion des erreurs pour les réponses 4xx et 5xx. Décidez délibérément de la suite : demander à l'utilisateur d'affiner sa saisie, se rabattre sur une recherche plus large avec une limite plus élevée, ou afficher un message clair « lieu introuvable » plutôt qu'un espace vide ou une valeur par défaut trompeuse.
Les causes courantes à vérifier en premier
Un lieu réellement inexistant est une cause possible, mais une chaîne de saisie mal formatée, une faute de frappe ou une requête mêlant de façon inattendue plusieurs langues ou écritures peuvent aussi produire un résultat vide pour une adresse qui existe bel et bien. Avant de conclure que le lieu lui-même n'existe pas, voyez si normaliser la saisie ou essayer une version avec le paramètre countries renseigné résoudrait le problème.
Journaliser les résultats vides séparément
Suivez la fréquence à laquelle votre intégration emprunte le chemin du résultat vide, séparément de votre taux d'erreur. Une hausse du taux de résultats vides signale souvent un problème de qualité des données en amont, dans la façon dont les adresses sont collectées ou formatées, plutôt qu'un défaut de la recherche elle-même.
Le coût d'une recherche sans résultat
Un résultat vide coûte tout de même une requête, comme une correspondance réussie, puisque la recherche a été effectuée dans les deux cas. Il n'existe pas de tarif réduit pour une recherche qui revient vide.
Traiter un résultat vide comme une issue à part entière, décidée délibérément, plutôt que comme un ajout de dernière minute à la gestion des erreurs, rend une intégration nettement plus solide. La page des erreurs couvre les véritables réponses d'erreur, tandis que les résultats vides sont documentés avec la forme de réponse normale de chaque endpoint, comme dans la documentation du géocodage direct.