Bonnes pratiques

Réessayer, sans insister

Les réponses 429, 503 et 504 signalent un problème passager : réessayez, avec un délai qui double à chaque tentative et une part de hasard, pour ne pas renvoyer toutes les requêtes au même instant. Ne réessayez jamais une erreur 4xx autre que 429 : la même requête échouera de la même façon.

const RETRYABLE = new Set([429, 503, 504]);
const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

async function fetchWithRetry(url, options, attempts = 4) {
  for (let i = 0; ; i++) {
    const res = await fetch(url, options);
    if (!RETRYABLE.has(res.status) || i === attempts - 1) return res;
    // 0,5 s, 1 s, 2 s… plus une part aléatoire
    await sleep(500 * 2 ** i + Math.random() * 250);
  }
}

import random
import time

import httpx

RETRYABLE = {429, 503, 504}


def request_with_retry(client: httpx.Client, method: str, url: str, attempts: int = 4, **kwargs):
    for i in range(attempts):
        r = client.request(method, url, **kwargs)
        if r.status_code not in RETRYABLE or i == attempts - 1:
            return r
        # 0,5 s, 1 s, 2 s… plus une part aléatoire
        time.sleep(0.5 * 2**i + random.random() * 0.25)

Fixez aussi un délai d'attente côté client adapté à chaque usage : court pour une saisie semi-automatique, plus long pour une grande matrice ou un fichier CSV.

Économiser les requêtes

Le débit de chaque client est limité (voir erreur 429). Moins de requêtes, c'est aussi des réponses plus rapides :

Mettre en cache le géocodage

Une adresse géocodée change rarement. Conservez le résultat (coordonnées, label, identifiant BAN ou OSM) plutôt que de géocoder la même adresse à chaque affichage. Pour rester à jour, regéocodez de temps en temps : les données des moteurs sont rafraîchies régulièrement.

Les itinéraires et les matrices dépendent davantage du contexte (profil, options) : mettez-les en cache seulement si vous rejouez souvent les mêmes requêtes.

Protéger votre clé d'API

• Passez la clé dans l'en-tête X-API-Key, pas dans l'URL.
• Gardez-la côté serveur : jamais dans le code d'une page web, d'une application mobile ou d'un dépôt de code.
• Stockez-la dans une variable d'environnement ou un coffre-fort de secrets.
• Clé exposée ? Prévenez Galigeo pour la remplacer.

Accepter la compression

Les réponses sont compressées (gzip ou brotli) quand le client l'accepte, ce qui réduit fortement la taille des itinéraires détaillés et des isochrones. Les navigateurs et la plupart des bibliothèques HTTP le font seuls ; avec curl, ajoutez --compressed.

Citer les sources des données

Contacter le support

Pour un diagnostic rapide, joignez à votre demande :

• la date et l'heure de l'appel, avec le fuseau horaire ;
• la requête complète (méthode, URL, corps), sans votre clé d'API ;
• le code HTTP et le corps de la réponse ;
• la valeur de l'en-tête X-GGO-Upstream, s'il est présent ;
• le résultat de /v2/health au même moment.