Limitation de débit

L'API geocodeme.net utilise un système de limitation à deux niveaux pour garantir un usage équitable :

1. Limite de débit par seconde : protection contre les rafales via une fenêtre glissante Redis. Limite le nombre de requêtes que vous pouvez effectuer par seconde.
2. Quota de crédits : contrôle du volume en crédits (chaque endpoint a un poids ; un géocodage coûte 1 crédit, une isochrone 10). Les plans payants ont une enveloppe mensuelle réinitialisée le 1er du mois ; le plan Free a une enveloppe journalière réinitialisée à minuit UTC.

Plans

Plan	Limite de débit (req/s)	Quota de crédits
Free	1	3 000 / jour
Startup	10	150 000 / mois
Growth	15	500 000 / mois
Pro	25	1 500 000 / mois

Consultez les tarifs actuels pour le détail et les prix des plans, et la page Crédits & quotas pour les poids par endpoint.

Headers de réponse

Chaque réponse de l'API inclut ces headers de limitation de débit :

Header	Description
X-RateLimit-Limit	Nombre maximal de requêtes autorisées par seconde pour votre plan
X-RateLimit-Remaining	Nombre de requêtes restantes dans la fenêtre par seconde en cours
X-RateLimit-Reset	Timestamp Unix de réinitialisation de la limite de débit par seconde
X-RateLimit-Monthly-Limit	Quota de crédits de la fenêtre en cours (mensuelle ; journalière sur Free)
X-RateLimit-Monthly-Remaining	Crédits restants dans la fenêtre en cours
X-RateLimit-Monthly-Reset	Timestamp Unix de réinitialisation de la fenêtre (1er du mois suivant 00:00 UTC ; minuit UTC suivant sur Free)
X-RateLimit-Monthly-Warning	Vaut true dès que vous avez consommé ≥ 80 % de votre fenêtre de quota
Retry-After	Uniquement sur les réponses 429 : nombre de secondes à attendre avant de réessayer

remarque

Les noms Monthly-* sont conservés pour compatibilité : sur le plan Free, ils décrivent la fenêtre du jour (limite 3 000, reset à minuit UTC).

Inspectez les headers de limite de débit avec :

curl -I -H "X-Api-Key: gm_YOUR_API_KEY" \
  "https://api.geocodeme.net/v1/geocode?q=Paris"

Gérer les erreurs 429

Quand vous dépassez une limite, l'API renvoie un HTTP 429 avec l'un de ces deux codes d'erreur :

Limite de débit dépassée (par seconde)

Le champ retry_after indique combien de secondes attendre :

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded. Try again in 1 second",
    "retry_after": 1
  }
}

Implémentez un backoff exponentiel :

import time
import requests

def geocode_with_retry(url, headers, params, max_retries=3):
    for attempt in range(max_retries):
        response = requests.get(url, headers=headers, params=params)
        if response.status_code != 429:
            response.raise_for_status()
            return response
        try:
            retry_after = response.json()["error"]["retry_after"]
        except (ValueError, KeyError):
            retry_after = 1  # backoff par défaut si la réponse n'est pas du JSON
        time.sleep(retry_after * (2 ** attempt))
    raise requests.exceptions.HTTPError(
        f"Rate limit exceeded after {max_retries} retries", response=response
    )

Quota de crédits épuisé

Le champ quota_reset est le timestamp Unix de réinitialisation de votre fenêtre (minuit UTC suivant sur Free, 1er du mois suivant 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"
  }
}

Quota épuisé : montez de plan ou attendez la réinitialisation de la fenêtre.

astuce

Cachez vos résultats de géocodage localement (Redis, mémoire) pour économiser vos crédits, et rappelez-vous que les échecs côté serveur (5xx) sont automatiquement remboursés.