Authentification

Les 2 500 premières requêtes par jour depuis une adresse ne nécessitent aucune clé. Une clé sert pour tout ce qui va au-delà : elle détermine sur quel crédit ou quel forfait une requête est prélevée et quelles machines peuvent l'utiliser, et elle vous fournit un historique d'utilisation. Les clés sont gratuites et s'obtiennent en une minute.

Sans clé

Envoyez la requête sans aucun identifiant et elle obtient une réponse. Chaque adresse dispose ainsi de 2 500 requêtes par jour, comptées à partir de 00:00 UTC sur tous les endpoints et tous les hôtes compatibles, avec les mêmes données et les mêmes réponses qu'un compte payant. Au-delà, l'API répond 429 quota_exceeded avec un en-tête Retry-After jusqu'à la remise à zéro ; rien n'est facturé et rien n'est mis en file d'attente.

Deux choses à savoir. Les adresses qui appartiennent au même réseau partagent un même quota, si bien qu'un bureau très actif, un campus ou une région cloud peut l'épuiser plus vite qu'une seule machine. Et un réseau et les clés utilisées depuis ce réseau puisent dans le même quota : les requêtes faites sans clé réduisent ce qu'une clé utilisée depuis ce réseau obtient aujourd'hui, et les requêtes gratuites faites avec cette clé réduisent ce que le réseau obtient sans clé. S'inscrire apporte donc du crédit, des forfaits et un historique, pas un second lot de 2 500 requêtes gratuites depuis le même endroit.

Obtenir une clé

Inscrivez-vous sur www.mygeocode.com/signup avec votre nom, une adresse e-mail et un mot de passe. Votre première clé est affichée une seule fois, sur-le-champ ; copiez-la, car seul un hachage est conservé. Créez autant de clés supplémentaires que vous le souhaitez dans Clés d'API, donnez à chacune un libellé (une par serveur ou par application est une bonne habitude) et révoquez-en n'importe laquelle à tout moment.

Chaque clé dispose de 2 500 requêtes gratuites par jour, comptées à partir de 00:00 UTC sur tous les endpoints et tous les hôtes compatibles. Au-delà, les requêtes sont prélevées sur le crédit prépayé du compte à 0,0001 € l'unité, sauf si la clé est liée à un forfait Unlimited.

Envoyer la clé

Chacune de ces méthodes fonctionne sur tous les hôtes. Préférez l'en-tête : les chaînes de requête finissent dans les journaux des serveurs, l'historique des navigateurs et les proxys.

$ curl -H "X-API-Key: mg_7f3c2a19e04b...d1" "https://api.mygeocode.com/v1/reverse?lat=51.5&lon=-0.12"

$ curl -H "Authorization: Bearer mg_7f3c2a19e04b...d1" "https://api.mygeocode.com/v1/reverse?lat=51.5&lon=-0.12"

$ curl "https://api.mygeocode.com/v1/reverse?lat=51.5&lon=-0.12&key=mg_7f3c2a19e04b...d1"

$ curl -u "mg_7f3c2a19e04b...d1:" "https://api.mygeocode.com/v1/reverse?lat=51.5&lon=-0.12"

Sur les hôtes compatibles, la clé va aussi là où allait la clé du fournisseur d'origine : key pour Google, Bing, Geocode.Farm, OpenCage, LocationIQ, TomTom et MapQuest ; apiKey pour HERE et Geoapify ; access_token pour Mapbox ; api_key pour Geocodio ; access_key pour PositionStack et ipstack ; token pour ipinfo. Les clients Nominatim et Open-Elevation ajoutent key= ou un en-tête, puisque ces deux services n'ont pas de clé propre.

En plus du paramètre de requête, quatre façons d'envoyer les identifiants sont acceptées sur tous les hôtes, si bien qu'une bibliothèque cliente qui s'authentifie à la manière du fournisseur n'a besoin d'aucune modification : l'en-tête X-API-Key, Authorization: Bearer, l'authentification HTTP Basic avec la clé comme nom d'utilisateur (ce qu'envoie curl -u KEY:, et ce qu'utilisent les exemples ipinfo), et l'en-tête X-Goog-Api-Key qu'envoient les clients de Google. Une clé dans le corps d'un formulaire est également lue, pour les endpoints qui reçoivent des POST. Changer le nom d'hôte et la clé constitue toute la migration.

Deux types de clé

Emplacements IP

Une clé peut être utilisée depuis un nombre limité d'adresses IP à la fois : deux pour une clé en paiement à l'usage, trois pour une clé Unlimited. La règle est glissante, par adresse :

• La première fois qu'une adresse utilise la clé, elle occupe un emplacement et le conserve pendant 24 heures à partir de cette première requête.
• Une fois ces 24 heures écoulées, l'emplacement se libère de lui-même, quoi que fassent les autres adresses. Si la même adresse revient plus tard, elle occupe simplement un emplacement à nouveau.
• Une requête depuis une nouvelle adresse alors que tous les emplacements sont occupés est refusée avec 403 et le code key_ip_limit. Le message indique quand le prochain emplacement se libère. Les requêtes refusées ne sont pas comptées.

Ainsi, si deux serveurs ont utilisé une clé pour la première fois à 02:00 et un troisième à 04:00, deux emplacements se libèrent à 02:00 le lendemain et le troisième à 04:00. Le tableau de bord indique quelles adresses occupent les emplacements d'une clé et quand chacun se libère. Besoin de plus de machines ? Créez d'autres clés en paiement à l'usage ou ajoutez d'autres forfaits Unlimited ; chaque forfait apporte sa propre clé.

Cette limite existe parce que les clés fuient. Grâce à elle, une clé qui se retrouve dans un dépôt public ne vaut pas grand-chose pour qui la trouve, et comme le crédit est prépayé, personne ne peut dépenser plus que le solde que vous avez chargé.

Clés et navigateurs

Ne placez pas de clé dans du JavaScript ni dans une application mobile. N'importe qui peut la lire dans la page, et chaque visiteur est une nouvelle adresse IP : les emplacements de la clé sont donc épuisés dès le deuxième ou le troisième visiteur. Appelez l'API depuis votre propre serveur et gardez-y la clé. Les hôtes compatibles pour cartes JavaScript chargent les tuiles et les bibliothèques sans clé ; seuls leurs appels de géocodage doivent passer par votre serveur.

Révocation et rotation

Révoquez une clé dans le tableau de bord et elle cesse de fonctionner en moins d'une minute. Créez d'abord la nouvelle clé, déployez-la, puis révoquez l'ancienne ; les deux fonctionnent entre-temps. Les clés n'expirent jamais d'elles-mêmes.

Refus

Aucun de ces refus n'est décompté du quota ni ne coûte de crédit. Sur les hôtes compatibles, ils sont renvoyés dans le format du fournisseur d'origine ; voir compatibilité.