OpenCage s'est constitué une communauté de développeurs qui apprécient une API de géocodage simple et bien documentée, sans grand-chose d'autre autour. Nous avons construit notre hôte compatible dans le même esprit : reproduire à l'identique le format de requête et de réponse, pour que rien dans le changement ne donne l'impression de repartir de zéro.
L'hôte reproduit précisément les paramètres de requête et le corps de réponse d'OpenCage, les seules différences étant les textes de copyright, de conditions et de confidentialité, qui sont ceux de My Geocode. Le code qui construit actuellement une requête au format OpenCage et analyse une réponse au format OpenCage peut être dirigé vers notre hôte en laissant ces deux parties entièrement intactes.
Ce qui change, c'est le nom d'hôte dans votre configuration et la clé avec laquelle vous vous authentifiez. Cette clé peut être envoyée en en-tête X-API-Key, en en-tête Authorization: Bearer, en authentification HTTP Basic avec la clé comme nom d'utilisateur, ou en paramètre de requête, selon l'approche qu'adopte déjà votre bibliothèque cliente existante. Les quatre fonctionnent de la même façon sur tous nos hôtes.
Les tarifs suivent notre structure standard, quel que soit l'hôte qui traite une requête. Toute adresse bénéficie de 2 500 requêtes gratuites par jour sans aucune clé, comptées par réseau. Une clé ajoute ses propres 2 500 requêtes gratuites par jour en plus. Au-delà de ces deux quotas, le crédit prépayé coûte 0,0001 € la requête, ou un forfait Unlimited couvre l'utilisation pour 50 € par mois, et rien de tout cela ne change selon qu'un appel passe par cet hôte compatible ou directement par /v1/forward.
Les en-têtes de quota accompagnent chaque réponse, ajoutant une couche de visibilité sur l'utilisation qu'une intégration OpenCage classique n'aurait pas autrement : X-Quota-Limit, X-Quota-Used, X-Quota-Free-Remaining, X-Quota-Network-Used, X-Credits-Remaining, X-Key-IPs-Used, X-Key-IPs-Limit et X-Quota-Reset sont tous inclus, à chaque fois.
Pour les équipes qui veulent plus que ce que renvoie par défaut la réponse compatible, ajouter mg_extras=1 à la requête, ou un en-tête X-MG-Extras, ajoute des champs facultatifs par-dessus, comme l'altitude du sol, sans perturber la structure de base sauf si vous le demandez.
La documentation de l'hôte se trouve sur /compatibility/opencage/, et une présentation plus large du fonctionnement des hôtes compatibles sur la plateforme sur /docs/compatibility/. Si OpenCage est déjà intégré à votre stack, faire l'essai revient à modifier une URL de base et à utiliser une nouvelle clé.