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.
Envoyer votre clé d'API de trois façons différentes (et pourquoi c'est important)
Tous les outils qui communiquent avec une API ne gèrent pas l'authentification de la même manière, c'est pourquoi l'API accepte une clé par plusieurs mécanismes au lieu d'imposer un seul nom d'en-tête.
L'en-tête X-API-Key
C'est l'option la plus directe : un en-tête dédié qui ne transporte que la clé.
GET /v1/forward?q=Baker+Street
X-API-Key: mg_live_examplekey123Authorization: Bearer
Certains clients HTTP et passerelles d'API sont déjà configurés pour joindre un jeton bearer à chaque requête sortante, et utiliser ce mécanisme vous évite d'ajouter à côté un second en-tête propre à l'API.
GET /v1/forward?q=Baker+Street
Authorization: Bearer mg_live_examplekey123Authentification HTTP Basic
Les outils plus anciens, et certaines intégrations de serveur à serveur conçues pour d'autres fournisseurs, attendent des identifiants en authentification HTTP Basic. La clé est placée dans le nom d'utilisateur, et le mot de passe reste vide.
GET /v1/forward?q=Baker+Street
Authorization: Basic bWdfbGl2ZV9leGFtcGxla2V5MTIzOg==Un paramètre de requête, pour tout le reste
Quand un outil ne vous laisse aucun contrôle sur les en-têtes, par exemple un test rapide dans la barre d'adresse d'un navigateur ou un client qui ne prend en charge qu'une configuration par URL, la clé peut aussi être transmise directement dans la requête sous forme de paramètre de requête.
GET /v1/forward?q=Baker+Street&key=mg_live_examplekey123Pourquoi ce choix compte en pratique
Une clé envoyée comme paramètre de requête se retrouve plus facilement dans les journaux de serveur, l'historique du navigateur et les en-têtes Referer qu'une clé envoyée dans un en-tête de requête : privilégiez donc une méthode par en-tête dès que le code appelant vous en laisse la maîtrise. Les quatre méthodes fonctionnent de façon identique sur tous les endpoints et tous les hôtes de compatibilité, si bien que passer de l'une à l'autre plus tard, par exemple en migrant un script d'un test dans le navigateur vers une véritable intégration backend, ne change rien à la façon dont le quota ou le crédit est décompté sur la clé.
Utiliser ces méthodes avec les hôtes de compatibilité
Chacun des 17 hôtes de compatibilité accepte les identifiants dans le même format que le fournisseur d'origine, de sorte qu'un script écrit selon la convention d'authentification d'un autre fournisseur continue en général de fonctionner une fois pointé vers l'hôte de compatibilité My Geocode correspondant, sans réécrire la façon dont la clé est envoyée. Consultez la page de compatibilité pour la liste des hôtes et le format d'identifiants attendu par chacun.
Une erreur à éviter
Tester un script avec la clé en paramètre de requête et la laisser ainsi en production est une habitude facile à prendre, car le paramètre de requête est souvent le moyen le plus rapide d'obtenir une première requête qui fonctionne. Passez à une méthode par en-tête, X-API-Key ou Authorization, avant que le script n'approche du trafic de production ou ne soit ajouté à un dépôt partagé, car une clé visible dans une URL a bien plus de chances de finir là où vous ne l'aviez pas prévu, comme dans le journal d'un proxy ou dans l'historique du navigateur d'une machine partagée.
Aucune différence de coût
Aucune de ces méthodes ne modifie la facturation d'une requête. Chaque requête effectuée avec la clé compte toujours de la même façon dans ses 2 500 requêtes gratuites par jour et, au-delà, sur le crédit prépayé ou un forfait Unlimited.
Choisir la bonne méthode d'authentification consiste surtout à s'adapter à ce que l'outil appelant prend déjà en charge, et non à une question de performance ou de coût. Tous les détails se trouvent dans la documentation sur l'authentification.