Compatibilité drop-in

Vous n'avez pas besoin d'apprendre cette API pour l'utiliser. Pour dix-sept autres API de géocodage et de recherche d'IP, nous exploitons un hôte qui accepte le format de requête de ce fournisseur et répond dans son format de réponse, avec nos données derrière. Il en va de même pour les bibliothèques de cartes JavaScript que ces fournisseurs proposent. La migration se résume à un changement de nom d'hôte.

Comment ça marche

Chaque hôte compatible est une implémentation complète de l'interface HTTP publique d'un fournisseur : les mêmes chemins, les mêmes paramètres de requête, les mêmes noms de champs JSON, la même imbrication et les mêmes types, le même vocabulaire de statuts et les mêmes formats d'erreur. Les valeurs sont les nôtres. Votre code client, votre code d'analyse et votre gestion des erreurs ne changent pas.

1. Changez d'hôte. maps.googleapis.com devient gapi.mygeocode.com, dev.virtualearth.net devient bing.mygeocode.com, et ainsi de suite. Le tableau ci-dessous contient toutes les paires.
2. Remplacez la clé, ou supprimez-la. Placez votre clé My Geocode dans le paramètre qu'utilisait l'ancienne clé (key, apiKey, access_token, token...). Toute adresse dispose de 2 500 requêtes gratuites par jour sans clé, et chaque clé est fournie avec ses propres 2 500 requêtes, donc migrer et tester ne coûte rien.
3. Comparez. Envoyez un échantillon de requêtes réelles aux deux hôtes. Les coordonnées différeront légèrement parce que les données sont différentes ; les noms de champs, non.

$ curl "https://maps.googleapis.com/maps/api/geocode/json?address=10+Downing+St+London&key=GOOGLE_KEY"

$ curl "https://gapi.mygeocode.com/maps/api/geocode/json?address=10+Downing+St+London&key=MYGEOCODE_KEY"

Tous les hôtes compatibles

Chaque hôte fonctionne sur la même infrastructure, avec les mêmes données, le même quota gratuit et les mêmes prix que api.mygeocode.com. Cliquez sur un fournisseur pour voir la liste de ses endpoints, un exemple de réponse et les différences connues.

Bibliothèques de cartes JavaScript

Les changements de fournisseur font le plus mal dans le navigateur, où la carte, le widget de géocodage et la facturation sont imbriqués. Pour les bibliothèques ci-dessous, la bibliothèque elle-même est chargée depuis notre hôte (ou, pour MapLibre, Mapbox GL et Leaflet, pointée vers notre hôte par configuration) et conserve son API publique : google.maps.Map, Microsoft.Maps.Map, H.Map et le reste. Les tuiles, le géocodage, la saisie semi-automatique et l'altitude viennent de chez nous. Les chargements de carte et les tuiles sont gratuits ; les appels de géocodage sont comptés comme d'habitude.

La page des remplacements JavaScript présente les extraits de code avant et après, la liste de ce qui est inclus ou non pour chaque bibliothèque, ainsi que les URL des tuiles et des styles.

Où placer la clé

Chaque hôte accepte la clé à l'endroit où le fournisseur d'origine l'attend, ainsi que dans l'en-tête X-API-Key. Une clé est facultative : 2 500 requêtes par jour et par adresse n'en nécessitent aucune. Une clé gratuite s'obtient en une minute et apporte du crédit, des forfaits et un historique d'utilisation. Une clé en paiement à l'usage peut être utilisée depuis deux adresses IP par période glissante de 24 heures, et une clé Unlimited depuis trois ; utilisez davantage de clés ou de forfaits pour davantage d'adresses (voir authentification).

Quotas et erreurs sur les hôtes compatibles

Le quota journalier est le même que partout ailleurs et il est compté par clé, ou par adresse lorsqu'aucune clé n'est envoyée, sur api.mygeocode.com et tous les hôtes compatibles : 2 500 requêtes gratuites par jour, puis du crédit ou une clé Unlimited. Les en-têtes X-Quota-* et X-Key-IPs-* sont envoyés sur tous les hôtes, vous pouvez donc lire l'état réel dans les en-têtes quel que soit le format du corps. Dans le corps, les limites sont signalées de la manière dont le fournisseur les signale :

Ce qui correspond et ce qui ne correspond pas

Liste de contrôle pour la migration

1. Recherchez le nom d'hôte du fournisseur dans votre code et votre configuration. Il se trouve souvent à plusieurs endroits : code serveur, applications mobiles, règle de CDN, configuration en cache.
2. Remplacez-le par l'hôte compatible indiqué dans le tableau ci-dessus. Conservez le chemin.
3. Remplacez la clé par une clé My Geocode. Utilisez une clé par serveur, ou pour deux serveurs au maximum ; une clé en paiement à l'usage accepte deux adresses IP par période glissante de 24 heures, une clé Unlimited trois.
4. Lancez votre suite de tests existante. Elle doit passer sans modification. Si un champ dont vous dépendez est absent, consultez la page de l'hôte pour les lacunes connues et prévenez-nous.
5. Rejouez quelques centaines de requêtes réelles sur les deux hôtes et comparez les coordonnées et les champs que vous affichez. Regardez precision là où l'hôte compatible l'expose (sous la forme location_type, accuracy, resultType, etc.).
6. Surveillez X-Quota-Used pendant une journée pour dimensionner votre offre : du crédit en dessous d'environ 19 000 requêtes par jour, une clé Unlimited au-dessus.
7. Résiliez l'ancienne facturation.

SDK des fournisseurs

La plupart des bibliothèques clientes officielles acceptent une URL de base personnalisée, elles fonctionnent donc aussi avec les hôtes compatibles : les clients Google Maps Services (googlemaps pour Python, @googlemaps/google-maps-services-js), les SDK Mapbox (option origin), les clients REST de HERE, les bibliothèques d'ipinfo et les wrappers Nominatim comme geopy (domain=). Pointez-les vers l'hôte du tableau et passez votre clé My Geocode là où allait la clé du fournisseur.

Un fournisseur qui n'est pas dans la liste

Ajouter un hôte représente quelques jours de travail lorsque le format du fournisseur est documenté. Si vous utilisez un service qui ne figure pas ici, dites-nous lequel et combien de requêtes par jour vous envoyez environ. Les derniers ajouts étaient tous des demandes d'utilisateurs.