POST /v1/batch/geocode

Vue d'ensemble

Géocodez jusqu'à 10 000 adresses en un job asynchrone : soumettez la liste, suivez l'avancement du job, téléchargez les résultats en CSV. Idéal pour nettoyer un fichier client ou préparer un jeu de données sans écrire vous-même une boucle qui respecte les limites de débit.

Coût : 1 crédit par adresse, débité à la soumission ; les lignes en échec sont automatiquement remboursées à la fin du job. Disponibilité : à partir du plan Growth.

Le flux :

1. POST /v1/batch/geocode → 202 Accepted avec un job_id (les crédits sont débités ici)
2. GET /v1/batch/{job_id} → statut et avancement (gratuit, interrogez aussi souvent que nécessaire)
3. GET /v1/batch/{job_id}/result → résultats en CSV, une fois le status à completed

Les résultats sont conservés 7 jours après la soumission (expires_at dans la réponse de statut), puis supprimés.

Soumettre un job

POST https://api.geocodeme.net/v1/batch/geocode

Header requis : X-Api-Key: gm_YOUR_API_KEY

Corps de la requête

Deux formats acceptés :

• JSON (Content-Type: application/json) : {"addresses": ["18 rue de la Paix, Paris", "..."]}
• CSV / texte brut (Content-Type: text/csv ou text/plain) : une adresse par ligne, en UTF-8

Limites : 10 000 adresses max par job, 512 caractères max par adresse. Les lignes vides sont ignorées. La soumission est refusée avec un 429 QUOTA_EXCEEDED si votre fenêtre de crédits restante ne peut pas couvrir le job entier ; rien n'est débité dans ce cas.

Exemples de code

cURL (JSON)

curl -X POST \
  -H "X-Api-Key: gm_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "addresses": [
      "18 rue de la Paix, Paris",
      "10 Rue de Rivoli, Paris",
      "1 Parvis de Notre-Dame, Paris"
    ]
  }' \
  "https://api.geocodeme.net/v1/batch/geocode"

cURL (CSV)

curl -X POST \
  -H "X-Api-Key: gm_YOUR_API_KEY" \
  -H "Content-Type: text/csv" \
  --data-binary @adresses.csv \
  "https://api.geocodeme.net/v1/batch/geocode"

Où adresses.csv contient une adresse par ligne :

18 rue de la Paix, Paris
10 Rue de Rivoli, Paris
1 Parvis de Notre-Dame, Paris

Python (flux complet)

import os
import time

import requests

api_key = os.environ["GEOCODEME_API_KEY"]
headers = {"X-Api-Key": api_key}
base = "https://api.geocodeme.net/v1/batch"

# 1. Soumission
response = requests.post(
    f"{base}/geocode",
    json={"addresses": ["18 rue de la Paix, Paris", "10 Rue de Rivoli, Paris"]},
    headers=headers,
)
response.raise_for_status()
job_id = response.json()["job_id"]

# 2. Interrogation jusqu'à la fin du job
while True:
    status = requests.get(f"{base}/{job_id}", headers=headers).json()
    if status["status"] in ("completed", "failed"):
        break
    print(f"{status['processed_lines']}/{status['total_lines']} traitées...")
    time.sleep(2)

# 3. Téléchargement du CSV
result = requests.get(f"{base}/{job_id}/result", headers=headers)
result.raise_for_status()
with open("geocode.csv", "wb") as f:
    f.write(result.content)

Réponse : 202 Accepted

{
  "job_id": "0198c9a2-7f43-7b21-a5d0-3f6e2c9b8d11",
  "status": "queued",
  "total_lines": 3,
  "credits_debited": 3
}

Champ	Type	Description
job_id	string (UUID)	Identifiant du job, à utiliser pour les endpoints de statut et de résultat
status	string	Toujours queued à la soumission
total_lines	integer	Nombre d'adresses acceptées
credits_debited	integer	Crédits débités immédiatement (1 par adresse)

Suivre le statut : GET /v1/batch/{job_id}

L'interrogation est gratuite (aucun débit de crédits, seule la limite de débit s'applique).

curl -H "X-Api-Key: gm_YOUR_API_KEY" \
  "https://api.geocodeme.net/v1/batch/0198c9a2-7f43-7b21-a5d0-3f6e2c9b8d11"

{
  "job_id": "0198c9a2-7f43-7b21-a5d0-3f6e2c9b8d11",
  "status": "completed",
  "total_lines": 3,
  "processed_lines": 3,
  "failed_lines": 1,
  "credits_debited": 3,
  "created_at": "2026-07-20T09:14:03.201000+00:00",
  "finished_at": "2026-07-20T09:14:41.877000+00:00",
  "expires_at": "2026-07-27T09:14:03.201000+00:00",
  "error": null
}

Champ	Type	Description
status	string	queued, running, completed ou failed
total_lines	integer	Nombre total d'adresses du job
processed_lines	integer	Adresses traitées jusqu'ici
failed_lines	integer	Adresses qui n'ont pas pu être géocodées (remboursées)
credits_debited	integer	Crédits débités à la soumission
created_at	string	Date de soumission (ISO 8601, UTC)
finished_at	string | null	Date de fin, null tant que le job tourne
expires_at	string	Date de suppression des résultats (7 jours après la soumission)
error	string | null	Cause de l'échec quand status vaut failed

Remboursements

À la fin du job, chaque ligne en échec est remboursée (1 crédit chacune). Si le job échoue entièrement, chaque ligne qui n'a pas été géocodée avec succès est remboursée.

Télécharger les résultats : GET /v1/batch/{job_id}/result

Disponible une fois le status à completed. Renvoie un fichier CSV en streaming (gratuit également) :

curl -H "X-Api-Key: gm_YOUR_API_KEY" -o geocode.csv \
  "https://api.geocodeme.net/v1/batch/0198c9a2-7f43-7b21-a5d0-3f6e2c9b8d11/result"

input,status,lat,lon,display_name
"18 rue de la Paix, Paris",ok,48.8687,2.3315,"18, Rue de la Paix, 2e Arrondissement, Paris, Île-de-France, 75002, France"
"10 Rue de Rivoli, Paris",ok,48.8556,2.3603,"10, Rue de Rivoli, 4e Arrondissement, Paris, Île-de-France, 75004, France"
"zzzz nulle part",failed,,,

Colonne	Description
input	L'adresse telle que vous l'avez soumise
status	ok ou failed
lat / lon	Coordonnées du meilleur résultat (vide si failed)
display_name	Adresse complète formatée du meilleur résultat (vide si failed)

Réponses d'erreur

Résultats demandés avant la fin du job

{
  "error": {
    "code": "JOB_NOT_READY",
    "message": "Job is 'running': results are only available once completed"
  }
}

Renvoyé avec le statut HTTP 409. Continuez d'interroger l'endpoint de statut jusqu'à ce que status vaille completed.

Job inconnu (ou appartenant à un autre compte)

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Batch job not found"
  }
}

Les jobs ne sont visibles que par le compte qui les a créés ; un job_id étranger renvoie un 404, jamais un 403.

Plan sans accès au batch

{
  "error": {
    "code": "PLAN_UPGRADE_REQUIRED",
    "message": "The 'batch' feature is not included in your plan. Upgrade to unlock it.",
    "upgrade_url": "https://geocodeme.net/dashboard/billing"
  }
}

Job trop volumineux

{
  "error": {
    "code": "INVALID_PARAMETER",
    "message": "Too many addresses (12000 > 10000)",
    "field": "addresses"
  }
}

astuce

Tous les endpoints sont également soumis aux erreurs INVALID_API_KEY (401) et RATE_LIMIT_EXCEEDED / QUOTA_EXCEEDED (429). Consultez Codes d'erreur pour la référence complète.