Documentation API Reverseum

Authentification & sécurité

L’API Reverseum utilise une authentification par clé API passée dans l’en-tête HTTP :

X-Api-Key: VOTRE_CLE_API

• Vos clés sont gérées depuis la page API & clés.
• Une clé peut être révoquée immédiatement en cas de fuite.
• Utilisez une clé par environnement (DEV, TEST, PROD) ou par client.
• Ne logguez jamais la clé elle-même (logguez statut, endpoint, temps de réponse).

Test rapide (reverse unitaire) :

curl -i -X POST "https://api.reverseum.fr/api/geo/reverse" ^
  -H "X-Api-Key: VOTRE_CLE_API" ^
  -H "Content-Type: application/json" ^
  -d "{ \"latitude\": 48.6921, \"longitude\": 6.1844 }"

Reverse geocoding — POST /api/geo/reverse

À partir d’une latitude / longitude, Reverseum retourne une adresse structurée adaptée au contexte français.

POST https://api.reverseum.fr/api/geo/reverse
Headers:
  X-Api-Key: VOTRE_CLE_API
  Content-Type: application/json

Body:
{
  "latitude": 48.6921,
  "longitude": 6.1844
}

Exemple de réponse :

{
  "latitude": 48.6921,
  "longitude": 6.1844,
  "numeroRue": "10",
  "voie": "Rue de la Commanderie",
  "ville": "Nancy",
  "codePostal": "54000",
  "departement": "Meurthe-et-Moselle",
  "region": "Grand Est",
  "pays": "France",
  "adresseComplete": "10 Rue de la Commanderie, 54000 Nancy, France"
}

Reverse batch — POST /api/geo/reverse/batch

Permet de reverser plusieurs points en un seul appel. Limite par appel selon abonnement : 10 points (Reverseum) et 50 points (Reverseum Pro+).

POST https://api.reverseum.fr/api/geo/reverse/batch
Headers:
  X-Api-Key: VOTRE_CLE_API
  Content-Type: application/json

Body:
{
  "points": [
    { "latitude": 48.6921, "longitude": 6.1844 },
    { "latitude": 48.8566, "longitude": 2.3522 }
  ]
}

Exemple de réponse :

{
  "totalDemandes": 2,
  "totalRetours": 2,
  "resultats": [
    {
      "latitude": 48.6921,
      "longitude": 6.1844,
      "adresseComplete": "10 Rue de la Commanderie, 54000 Nancy, France"
    },
    {
      "latitude": 48.8566,
      "longitude": 2.3522,
      "adresseComplete": "Paris, France"
    }
  ],
  "erreurs": []
}

Recherche d’adresse — POST /api/geo/search (Pro+)

À partir d’une adresse, Reverseum retourne des coordonnées GPS et une adresse normalisée. Cet endpoint est réservé à l’offre Reverseum Pro+.

POST https://api.reverseum.fr/api/geo/search
Headers:
  X-Api-Key: VOTRE_CLE_API
  Content-Type: application/json

Body:
{
  "adresseComplete": "10 rue de la Paix, 75002 Paris"
}

Réponse possible :

{
  "latitude": 48.8686,
  "longitude": 2.3303,
  "adresseComplete": "10 Rue de la Paix, 75002 Paris, France"
}

Import CSV — preview & téléchargement (Pro+)

Reverseum accepte un CSV contenant au minimum latitude,longitude (virgule ou point-virgule). Les colonnes additionnelles sont conservées. Les endpoints CSV sont réservés à l’offre Reverseum Pro+.

latitude,longitude
48.8686,2.3303
43.6047,1.4442

1) Aperçu JSON — POST /api/geo/csv/preview

Envoie le fichier et retourne un JSON (liste de points enrichis) pour affichage.

POST https://api.reverseum.fr/api/geo/csv/preview
Headers:
  X-Api-Key: VOTRE_CLE_API
Content-Type:
  multipart/form-data

Form-data:
  file: (votre fichier.csv)

Exemple curl (Windows) :

curl -X POST "https://api.reverseum.fr/api/geo/csv/preview" ^
  -H "X-Api-Key: VOTRE_CLE_API" ^
  -F "file=points.csv"

2) CSV enrichi à télécharger — POST /api/geo/csv

Envoie le fichier et retourne un fichier CSV (ce n’est pas du JSON). Le serveur renvoie un Content-Disposition en pièce jointe.

POST https://api.reverseum.fr/api/geo/csv
Headers:
  X-Api-Key: VOTRE_CLE_API
Content-Type:
  multipart/form-data

Form-data:
  file: (votre fichier.csv)

Response:
  200 OK (text/csv) + Content-Disposition: attachment; filename="reverseum_result_....csv"

Exemple curl (enregistre le fichier) :

curl -L -o result.csv -X POST "https://api.reverseum.fr/api/geo/csv" ^
  -H "X-Api-Key: VOTRE_CLE_API" ^
  -F "file=points.csv"

3) Upload enrichi — POST /api/geo/upload

Envoie un CSV et retourne un résultat CSV (fichier result.csv). Utile pour les intégrations “simples” côté scripts.

POST https://api.reverseum.fr/api/geo/upload
Headers:
  X-Api-Key: VOTRE_CLE_API
Content-Type:
  multipart/form-data

Form-data:
  file: (votre fichier.csv)

Exemple curl :

curl -L -o result.csv -X POST "https://api.reverseum.fr/api/geo/upload" ^
  -H "X-Api-Key: VOTRE_CLE_API" ^
  -F "file=points.csv"

Codes d’erreur & réponses

Principales réponses possibles :

Bonnes pratiques d’intégration

• Ne jamais exposer la clé dans du JavaScript public ou un dépôt Git.
• Créer une clé par environnement et par client final.
• Mettre en cache les réponses répétitives (réduit la latence et la charge).
• Journaliser endpoint, statut HTTP, durée, mais jamais la clé.
• Révoquer immédiatement en cas de suspicion de fuite.

Roadmap API

• Scopes par clé API (droits par endpoint, restrictions IP, quotas).
• Traitements CSV gros volumes (mode asynchrone avec récupération ultérieure).
• Webhooks (surconsommation, erreurs répétées, statut jobs).
• Trajets & optimisation (routing) : endpoint dédié à venir.

Pour des besoins spécifiques (volumes, SLA, fonctionnalités), contactez : contact@reverseum.fr.