Documentation

Tout est une requête GET vers https://api.mygeocode.com/v1/ avec des paramètres de requête, et la réponse est en JSON. Cette page couvre ce que tous les endpoints ont en commun. Les pages de chaque endpoint décrivent ses paramètres et ses champs.

Votre première requête

Aucune clé n'est nécessaire pour les 2 500 premières requêtes par jour depuis une adresse. Depuis n'importe quelle machine :

$ curl "https://api.mygeocode.com/v1/forward?q=Brandenburg+Gate,+Berlin&limit=1"

{
  "status": "ok",
  "query": "Brandenburg Gate, Berlin",
  "results": [
    {
      "formatted": "Brandenburger Tor, Pariser Platz, 10117 Berlin, Germany",
      "lat": 52.516275,
      "lon": 13.377704,
      "type": "poi",
      "precision": "house",
      "confidence": 0.99,
      "components": {
        "name": "Brandenburger Tor",
        "road": "Pariser Platz",
        "suburb": "Mitte",
        "city": "Berlin",
        "state": "Berlin",
        "postcode": "10117",
        "country": "Germany",
        "country_code": "de"
      },
      "bounds": { "north": 52.516441, "south": 52.516107, "east": 13.377862, "west": 13.377538 }
    }
  ]
}

Cette requête a compté comme la 1 sur les 2 500 requêtes gratuites dont dispose votre adresse aujourd'hui. Avec une clé, elle aurait été décomptée de la clé, et les en-têtes indiqueraient en plus votre crédit et vos emplacements IP. Les en-têtes de réponse vous indiquent où vous en êtes :

HTTP/2 200
content-type: application/json; charset=utf-8
x-quota-limit: 2500
x-quota-used: 1
x-quota-free-remaining: 2499
x-quota-reset: 1756339200
x-request-id: 2726386e38428697

Vous venez d'un autre fournisseur ?

Vous n'avez peut-être pas besoin du reste de cette page. Si votre code communique déjà avec Google Maps, Bing Maps, HERE, Mapbox, Geocode.Farm, Nominatim, OpenCage, LocationIQ, Geoapify, TomTom, MapQuest, Geocodio, PositionStack, ip-api, ipinfo, ipstack ou Open-Elevation, nous exploitons un hôte qui parle le format de requête et de réponse de ce fournisseur, avec nos données derrière. Changez le nom d'hôte, mettez votre clé là où se trouvait l'ancienne et conservez votre code d'analyse. Il en va de même pour la Google Maps JavaScript API, Bing Maps V8, HERE Maps for JavaScript, MapQuest.js et les plugins de géocodage pour MapLibre, Mapbox GL et Leaflet.

• Google Maps
• Bing Maps
• HERE
• Mapbox
• Geocode.Farm
• Nominatim
• OpenCage
• LocationIQ
• Geoapify
• TomTom
• MapQuest
• Geocodio
• PositionStack
• ip-api
• ipinfo
• ipstack
• Open-Elevation
• Bibliothèques de cartes JavaScript

Fonctionnement des hôtes compatibles : la matrice complète des hôtes, la correspondance des clés, la correspondance des erreurs et une liste de contrôle pour la migration.

URL de base et endpoints

Seul HTTPS est servi. Les requêtes en HTTP simple sont refusées avec 400 au lieu d'être redirigées, afin qu'une clé ne soit jamais envoyée en clair par accident. HTTP/2 et HTTP/3 sont pris en charge. Les réponses sont compressées lorsque le client accepte gzip ou br.

L'enveloppe de réponse

Chaque réponse est un objet JSON dont le status vaut ok ou error.

• En cas de ok, le contenu suit : results (un tableau) pour les endpoints qui peuvent renvoyer plusieurs correspondances, result (un objet ou null) pour le géocodage inverse, et des champs à plat pour les recherches d'IP et de fuseau horaire.
• En cas de error, un objet error contient une chaîne code, une phrase message et, le cas échéant, le paramètre param qui a causé l'erreur. Le statut HTTP correspond. Voir les erreurs.

Une requête valide qui ne trouve rien renvoie ok avec un tableau results vide ou un result à null. Ce n'est pas une erreur, et cela compte comme une requête.

Paramètres acceptés par tous les endpoints

Les noms de paramètres sont sensibles à la casse et en minuscules. Les paramètres inconnus sont ignorés et les paramètres vides sont traités comme absents, de sorte qu'un formulaire HTML peut envoyer des champs facultatifs vides. Les coordonnées sont en degrés décimaux ; lat de -90 à 90 et lon de -180 à 180. Le texte est en UTF-8 et doit être encodé pour l'URL.

L'authentification en un paragraphe

Une clé est facultative : chaque adresse dispose de 2 500 requêtes gratuites par jour sans clé. Une clé s'envoie dans l'en-tête X-API-Key, sous forme de jeton Authorization: Bearer ou dans le paramètre key ; les clés sont gratuites, et un compte ne demande que votre nom, une adresse e-mail et un mot de passe. Chaque clé dispose de ses propres 2 500 requêtes gratuites par jour ; au-delà, les requêtes sont prélevées sur le crédit prépayé du compte à 0,0001 € l'unité, ou sont gratuites sur une clé liée à un forfait Unlimited (50 € par mois). Les requêtes sans clé et les requêtes avec une clé provenant du même réseau partagent un même quota journalier. Une clé en paiement à l'usage fonctionne depuis deux adresses IP par période glissante de 24 heures, une clé Unlimited depuis trois. Toutes les règles figurent sur la page d'authentification.

En-têtes de quota

Appels depuis un navigateur

CORS est activé sur tous les endpoints et les en-têtes de quota sont exposés, mais une clé placée dans le code source d'une page est publique et épuiserait ses emplacements IP après quelques visiteurs. Faites les appels depuis votre serveur ; voir clés et navigateurs.

Gestion des versions

Le préfixe de chemin /v1/ est la version. Au sein d'une version, nous ajoutons des champs et des paramètres, mais nous n'en supprimons ni n'en renommons jamais, et nous ne changeons jamais le sens d'un champ existant. Si nous devons un jour casser quelque chose, cela ira dans /v2/, et /v1/ continuera de fonctionner pendant au moins six mois après l'annonce. Les ajouts sont annoncés dans la rubrique Actualités du blog.

Votre analyseur JSON doit ignorer les champs qu'il ne connaît pas. C'est la seule exigence de compatibilité ascendante.