Quotas, crédit et limites

Chaque clé bénéficie d'un quota gratuit quotidien. Au-delà, les requêtes sont prélevées sur le crédit prépayé ou couvertes par un forfait Unlimited. Chaque réponse vous indique où vous en êtes dans ses en-têtes.

Le quota journalier

Le quota avec clé est calculé par clé, pas par compte : trois clés donnent trois fois 2 500 requêtes gratuites. Le quota sans clé est calculé par adresse, et les adresses d'un même réseau le partagent. Un réseau et les clés utilisées depuis ce réseau puisent dans un seul quota : les requêtes sans clé réduisent ce qu'obtient ce jour-là une clé utilisée depuis le même réseau, et inversement, de sorte que les 2 500 requêtes gratuites ne peuvent pas être obtenues deux fois depuis le même endroit. Le crédit est calculé par compte et il est utilisé par n'importe quelle clé qui dépasse son quota. La journée est le jour calendaire UTC ; X-Quota-Reset indique l'heure Unix exacte de la prochaine remise à zéro.

Ce qui compte comme une requête

• Chaque appel réussi (200) à n'importe quel endpoint compte pour une requête, qu'il ait trouvé quelque chose ou non.
• Chaque élément d'un appel groupé compte comme une requête : chaque adresse d'un lot IP, chaque point d'un appel d'altitude ou de fuseau horaire à plusieurs points, chaque entrée sur les endpoints par lot des hôtes compatibles. C'est aussi ainsi que les fournisseurs d'origine les comptent. Un lot plus grand que ce qui reste du quota est refusé en entier, avant tout traitement, avec l'erreur de limite propre au fournisseur, plutôt que de recevoir une réponse partielle. Chaque hôte accepte autant d'éléments par appel que son fournisseur d'origine (100 pour ip-api et MapQuest, 50 pour ipstack, 512 pour Google Elevation, 1 000 pour ipinfo, Mapbox et Geoapify, 1 024 pour Bing et Open-Elevation, 10 000 pour Geocodio et le traitement par lot asynchrone de TomTom ; 100 sur les endpoints natifs). La récupération d'un résultat asynchrone stocké n'est pas comptée.
• Les appels refusés avec 400, 401, 402, 403 ou 404 ne sont pas comptés et ne coûtent rien.
• Les appels qui échouent avec 500 ou 503 ne sont pas comptés et ne coûtent rien.
• Les tuiles de carte, le JSON de style et les chargements de bibliothèque des remplacements JavaScript ne sont pas comptés.

Emplacements IP

Une clé fonctionne depuis deux adresses IP à la fois (trois pour une clé Unlimited). Chaque adresse conserve son emplacement pendant 24 heures à partir de sa première requête, puis le libère. Une requête depuis une adresse supplémentaire alors que tous les emplacements sont occupés reçoit 403 key_ip_limit avec l'heure à laquelle le prochain emplacement se libère. Les détails et des exemples figurent sur la page d'authentification.

Pics de trafic

Il n'existe aujourd'hui aucune limite fixe de requêtes par seconde, avec ou sans clé. Un trafic qui ressemble à une boucle incontrôlée ou à une attaque peut être ralenti, et nous vous préviendrons si cela arrive à l'une de vos clés. Pour un gros traitement, utilisez les formes par lot (ips, locations) plutôt que des milliers d'appels unitaires.

Lire les en-têtes

x-quota-limit: 2500          # free per day for this key; -1 on an Unlimited key
x-quota-used: 2431           # counted today on this key, including this request
x-quota-free-remaining: 69   # free requests left today on this key
x-credits-remaining: 148200  # requests the account's credit still covers
x-key-ips-used: 1            # IP slots currently held on this key
x-key-ips-limit: 2           # slots on this key
x-quota-reset: 1789948800    # Unix time of the next 00:00 UTC
x-request-id: 2726386e38428697

Gérer les erreurs 402 et 403

{ "status": "error", "error": { "code": "no_credits", "message": "The free allowance of 2500 requests for today is used and the account balance (€0.0000, 0 requests) does not cover this request. Add credit at https://www.mygeocode.com/dashboard or wait for the reset at 00:00 UTC." } }

Ne réessayez pas en boucle ; la réponse restera la même tant que du crédit n'aura pas été ajouté ou que la journée n'aura pas été remise à zéro. Lisez X-Quota-Reset puis attendez, faites échouer l'opération en prévenant l'utilisateur, ou rechargez votre crédit. Le tableau de bord vous envoie un e-mail lorsque votre crédit devient faible.

{ "status": "error", "error": { "code": "key_ip_limit", "message": "This key is already in use from 2 IP addresses in the last 24 hours (limit 2). The next slot frees at 2026-09-21 23:06 UTC. Use another key or an additional Unlimited package for more addresses." } }

Cela signifie qu'une machine qui n'occupe actuellement aucun des emplacements de la clé a tenté de l'utiliser. Il s'agit généralement d'un nouveau serveur ou d'un redéploiement avec une nouvelle adresse ; donnez à cette machine sa propre clé.

Réduire le nombre de requêtes

Vous pouvez mettre les résultats en cache indéfiniment, alors faites-le. Les adresses ne bougent pas ; le même géocodage direct demain donnera la même réponse. Les blocs IP changent lentement ; une journée est une durée de cache sûre. Les règles de fuseau horaire d'un point changent rarement, et le nom IANA pratiquement jamais. Pour la saisie semi-automatique, appliquez un anti-rebond d'environ 150 ms sur la saisie et arrêtez d'envoyer des requêtes dès que l'utilisateur a choisi une suggestion.