Crédits et quotas
Votre quota est exprimé en crédits, pas en requêtes. Chaque endpoint a un poids qui reflète son coût de calcul : un géocodage débite 1 crédit, un itinéraire point à point 2, une isochrone 10. Vous dépensez votre enveloppe de crédits sur le mix d'endpoints qui vous convient.
Poids en crédits
| Endpoint | Coût en crédits |
|---|---|
GET /v1/geocode | 1 par appel (limit n'a aucun effet) |
GET /v1/reverse | 1 par appel |
GET /v1/autocomplete | 1 par appel (limit n'a aucun effet) |
GET /v1/nearest | 1 |
GET /v1/route | 2 |
GET /v1/elevation | 2 |
GET /v1/isochrone | 10 |
POST /v1/match | 1, plus 1 par bloc de 25 points entamé au-delà des 25 premiers |
POST /v1/matrix | 1 par bloc de 25 éléments entamé (sources × targets) |
POST /v1/batch/geocode | 1 par adresse, débité à la soumission ; lignes en échec remboursées |
Par appel, pas par résultat
Pour les endpoints de recherche (/v1/geocode, /v1/reverse, /v1/autocomplete), le poids est débité une fois par appel, quel que soit le limit demandé. Une autocomplétion à limit=20 coûte exactement 1 crédit, comme à limit=1 : X-RateLimit-Monthly-Remaining diminue de 1 dans les deux cas. L'autocomplétion interroge plusieurs moteurs régionaux en parallèle ; cette diffusion n'est pas non plus facturée par région.
Conséquence de dimensionnement : le sur-échantillonnage est gratuit. Si vous filtrez, dédoublonnez ou reclassez les résultats de votre côté, demandez le limit le plus grand qui vous soit utile et gardez ce que vous voulez ; le coût en crédits ne bouge pas. Seul le corps de la réponse grossit. Ce qui pilote la consommation, c'est le nombre d'appels : sur un champ de recherche à la saisie, temporisez la frappe et ignorez les requêtes de moins de trois caractères plutôt que de baisser limit.
Seuls les endpoints ci-dessous ont un coût qui croît avec la requête elle-même.
Coûts dépendant de la taille, en pratique :
- Match : une trace GPS de 25 points ou moins coûte 1 crédit ; 26 à 50 points coûtent 2 ; 51 à 75 coûtent 3... Une trace de 100 points coûte 4 crédits.
- Matrix : éléments = sources × targets. Une matrice 2×3 (6 éléments) coûte 1 crédit ; une 10×10 (100 éléments) en coûte 4 ; une 25×25 (625 éléments) en coûte 25.
- Batch : 1 000 adresses coûtent 1 000 crédits à la soumission ; si 40 lignes échouent, 40 crédits reviennent à la fin du job.
Les tuiles vectorielles (tiles.geocodeme.net) ont leurs propres compteurs par plan (tuiles par mois) et ne consomment pas de crédits : une vue de carte charge des dizaines de tuiles d'un coup et épuiserait n'importe quelle enveloppe de crédits.
Fenêtres de quota
Les plans payants disposent d'une enveloppe de crédits mensuelle. Le plan Free est compté sur une fenêtre journalière :
| Plan | Enveloppe de crédits | Remise à zéro |
|---|---|---|
| Free | 3 000 crédits / jour | Chaque minuit UTC |
| Startup | 150 000 crédits / mois | Le 1er du mois, 00:00 UTC |
| Growth | 500 000 crédits / mois | Le 1er du mois, 00:00 UTC |
| Pro | 1 500 000 crédits / mois | Le 1er du mois, 00:00 UTC |
Les quotas sont comptés par compte : toutes les clés API d'un même compte puisent dans la même enveloppe. Consultez les tarifs actuels pour les prix des plans, et Limitation de débit pour les limites de requêtes par seconde (appliquées indépendamment des crédits).
Capacités par plan
Au-delà du volume, les plans conditionnent les fonctionnalités disponibles :
| Capacité | Free | Startup | Growth | Pro |
|---|---|---|---|---|
| Profils de routage | car | car, bike, foot | tous (+ truck, moto) | tous (+ truck, moto) |
| Isochrone : minutes max | non | 30 | 60 | 120 |
| Matrix : taille max | non | 25×25 | 50×50 | 100×100 |
| Élévation | non | ✓ | ✓ | ✓ |
| Géocodage par lots | non | non | ✓ | ✓ |
| Tuiles vectorielles | non | ✓ | ✓ | ✓ |
Les profils s'appliquent à /v1/route, /v1/match, /v1/nearest, /v1/matrix et /v1/isochrone.
Quand les crédits sont (ou ne sont pas) débités
- Débités : chaque requête servie avec succès, au poids de son endpoint.
- Jamais débités : les requêtes que l'API refuse d'emblée : restrictions de plan (
403), validation de la requête (400sur paramètres mal formés), limitation de débit et refus de quota (429). Une requête que nous rejetons nous-mêmes ne coûte rien. - Débités : les erreurs
400levées par le moteur de routage après validation (par exemple une coordonnée impossible à accrocher au réseau routier) ; le calcul a bien eu lieu. - Remboursés automatiquement : toute défaillance côté serveur (
5xx) ; le débit est annulé avant que la réponse ne quitte l'API. Les jobs batch remboursent en plus chaque ligne en échec à leur clôture.
Suivre votre consommation
Chaque réponse porte les headers de quota décrits dans Limitation de débit :
X-RateLimit-Monthly-Limit: 150000
X-RateLimit-Monthly-Remaining: 148236
X-RateLimit-Monthly-Reset: 1754006400
Les noms Monthly-* décrivent la fenêtre active, quelle que soit sa durée : sur le plan Free, ils reflètent la fenêtre journalière du jour (limite 3 000, remise à zéro au prochain minuit UTC).
X-RateLimit-Monthly-Warning: true est ajouté dès que 80 % de la fenêtre est consommée (le header est absent sous le seuil), un bon déclencheur d'alerte de votre côté (vous recevez aussi un email).
Erreurs de quota et de plan
403 PLAN_UPGRADE_REQUIRED
Renvoyée quand la requête demande une capacité hors de votre plan (profil, fonctionnalité, ou valeur au-dessus de votre plafond). Rien n'est débité.
{
"error": {
"code": "PLAN_UPGRADE_REQUIRED",
"message": "Your plan allows up to 30 minutes. Upgrade to raise the limit.",
"field": "minutes",
"upgrade_url": "https://geocodeme.net/dashboard/billing"
}
}
429 QUOTA_EXCEEDED
Renvoyée quand la fenêtre ne peut pas couvrir le coût de la requête. quota_reset est le timestamp Unix de la prochaine remise à zéro (prochain minuit UTC en Free, 1er du mois sur les plans payants).
{
"error": {
"code": "QUOTA_EXCEEDED",
"message": "Quota exceeded. Upgrade your plan to continue.",
"quota_reset": 1753056000,
"upgrade_url": "https://geocodeme.net/dashboard/billing"
}
}
Les requêtes à coût variable (match, matrix, batch) sont refusées en bloc si la fenêtre restante ne peut pas les couvrir : un batch de 1 000 adresses exige 1 000 crédits disponibles d'avance. Soumettez vos gros jobs en début de fenêtre, ou découpez-les.
Pour la référence complète des erreurs, consultez Codes d'erreur.