Documentation API officielle

Documentation API Reverseum

Reverseum expose une API HTTP simple pour le reverse geocoding, le géocodage d’adresse (Pro+), et des traitements CSV (Pro+). Cette page est pensée comme un wiki : vous scrollez, vous copiez, vous intégrez.

Voir les exemples de code Gérer mes clés API Guide utilisateur complet

Base URL : https://api.reverseum.fr

Pack Postman V2 : collection / environnement

Fichiers d’exemple prêts à télécharger

Même base d’exemples que le Guide complet, pour tester rapidement chaque module sans utiliser vos données sensibles.

API & test

CSV & trajet

Comparaison tournée

Geofencing

Batch async

Lot batch d’exemple (CSV)

Pilotage opérations

Exploitation

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 }"

Remarque : une clé invalide/révoquée retournera 401.

Reverse geocoding — POST /api/geo/reverse

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

La réponse expose à la fois l'adresse finale (adresseComplete) et un bloc segmenté (adresse.segments) prêt pour CRM, dispatch et BI.

Version contrat propre recommandée pour nouveaux projets: POST /api/geo/reverse/v2 (payload strictement structuré, sans champs legacy à la racine).

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",
  "adresse": {
    "formatee": "10 Rue de la Commanderie, 54000 Nancy, France",
    "ligne1": "10 Rue de la Commanderie",
    "ligne2": "54000 Nancy",
    "ligne3": "Meurthe-et-Moselle, Grand Est, France",
    "segments": {
      "numeroRue": "10",
      "voie": "Rue de la Commanderie",
      "quartier": "Rives de Meurthe",
      "codePostal": "54000",
      "ville": "Nancy",
      "departement": "Meurthe-et-Moselle",
      "region": "Grand Est",
      "codeInsee": "54395",
      "codePays": "FR",
      "pays": "France"
    }
  }
}

Exemple de réponse V2 :

{
  "coordinates": {
    "latitude": 48.6921,
    "longitude": 6.1844
  },
  "address": {
    "formatee": "10 Rue de la Commanderie, 54000 Nancy, France",
    "ligne1": "10 Rue de la Commanderie",
    "ligne2": "54000 Nancy",
    "ligne3": "Meurthe-et-Moselle, Grand Est, France",
    "segments": {
      "numeroRue": "10",
      "voie": "Rue de la Commanderie",
      "quartier": "Rives de Meurthe",
      "codePostal": "54000",
      "ville": "Nancy",
      "departement": "Meurthe-et-Moselle",
      "region": "Grand Est",
      "codeInsee": "54395",
      "codePays": "FR",
      "pays": "France"
    }
  }
}

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

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

Variante contrat propre: POST /api/geo/reverse/batch/v2.

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",
      "adresse": {
        "formatee": "10 Rue de la Commanderie, 54000 Nancy, France",
        "ligne1": "10 Rue de la Commanderie",
        "ligne2": "54000 Nancy",
        "segments": {
          "numeroRue": "10",
          "voie": "Rue de la Commanderie",
          "codePostal": "54000",
          "ville": "Nancy",
          "codePays": "FR",
          "pays": "France"
        }
      }
    },
    {
      "latitude": 48.8566,
      "longitude": 2.3522,
      "adresseComplete": "Paris, France"
    }
  ],
  "erreurs": []
}

Comparaison tournée — POST /api/geo/route-compare (Pro+)

Compare une trace planifiée (attendue) et une trace réalisée pour produire un score de conformité, les distances, les points hors parcours et les segments en écart.

Les statuts de segments sont en français: Conforme et HorsParcours.

Endpoint réservé à l’offre Reverseum Pro+. Limite : 10 000 points par trace.

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

Body:
{
  "plannedPoints": [
    { "latitude": 48.8566, "longitude": 2.3522 },
    { "latitude": 48.8572, "longitude": 2.3598 }
  ],
  "actualPoints": [
    { "latitude": 48.8567, "longitude": 2.3523 },
    { "latitude": 48.8580, "longitude": 2.3650 }
  ],
  "toleranceMeters": 150,
  "strongDeviationThresholdMeters": 320
}

Exemple de réponse :

{
  "complianceScore": 86,
  "plannedDistanceKm": 5.12,
  "actualDistanceKm": 5.64,
  "distanceGapKm": 0.52,
  "missedPlannedPoints": 14,
  "offRoutePoints": 9,
  "segments": [
    { "fromIndex": 0, "toIndex": 1, "status": "Conforme", "gapMeters": 31.2 },
    { "fromIndex": 1, "toIndex": 2, "status": "HorsParcours", "gapMeters": 284.9 }
  ]
}

Export JSON des écarts — POST /api/geo/route-compare/export

Retourne un fichier JSON téléchargeable contenant la requête, le résultat, et les segments d’écart fort (seuil configurable) avec l'adresse complète.

curl -L -o route_compare_export.json -X POST "https://api.reverseum.fr/api/geo/route-compare/export" ^
  -H "X-Api-Key: VOTRE_CLE_API" ^
  -H "Content-Type: application/json" ^
  -d "{ \"plannedPoints\": [{\"latitude\":48.8566,\"longitude\":2.3522}], \"actualPoints\": [{\"latitude\":48.8567,\"longitude\":2.3523}], \"toleranceMeters\":150 }"

Qualité d'adresses — POST /api/geo/address-quality/batch (Pro+)

Analyse en lot la qualité des adresses saisies, retourne un score de fiabilité, un statut (VALIDE, A_VERIFIER, INVALIDE), des drapeaux qualité et une version normalisée.

Endpoint réservé à l’offre Reverseum Pro+.

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

Body:
{
  "items": [
    { "id": "A1", "adresseComplete": "10 rue de la Paix, 75002 Paris" }
  ],
  "options": {
    "normaliser": true,
    "detectDuplicates": true
  }
}

Monitoring tournée — POST /api/route/monitor/analyze (Pro+)

Détecte les écarts forts entre trace planifiée et trace réelle, enrichit les alertes avec adresse, et peut déclencher des webhooks ecart_fort.

Endpoint réservé à l’offre Reverseum Pro+.

POST https://api.reverseum.fr/api/route/monitor/analyze
Headers:
  X-Api-Key: VOTRE_CLE_API
  Content-Type: application/json

Body:
{
  "tourneeId": "T-2026-001",
  "plannedPoints": [ { "latitude": 48.6921, "longitude": 6.1844 } ],
  "actualPoints": [ { "latitude": 48.7001, "longitude": 6.2600 } ],
  "toleranceMeters": 150,
  "strongDeviationThresholdMeters": 300,
  "triggerWebhooks": true
}

ETA & créneaux — POST /api/route/eta/calculate (Pro+)

Calcule l'ETA de chaque stop, qualifie le statut (ALHeure, RetardProbable, EnAvance) et peut déclencher des webhooks retard_probable.

Endpoint réservé à l’offre Reverseum Pro+.

POST https://api.reverseum.fr/api/route/eta/calculate
Headers:
  X-Api-Key: VOTRE_CLE_API
  Content-Type: application/json

Body:
{
  "vehicleId": "V-42",
  "positionActuelle": { "latitude": 48.69, "longitude": 6.18 },
  "averageSpeedKmh": 35,
  "stops": [
    {
      "stopId": "S1",
      "latitude": 48.70,
      "longitude": 6.20,
      "creneauDebutUtc": "2026-02-23T09:00:00Z",
      "creneauFinUtc": "2026-02-23T09:30:00Z"
    }
  ]
}

Webhooks — /api/webhooks/subscriptions (Pro+)

Gestion des abonnements webhook utilisateur. Events supportés: ecart_fort, retard_probable et *.

Endpoints réservés à l’offre Reverseum Pro+.

GET    https://api.reverseum.fr/api/webhooks/subscriptions
POST   https://api.reverseum.fr/api/webhooks/subscriptions
PATCH  https://api.reverseum.fr/api/webhooks/subscriptions/{subscriptionId}/status
DELETE https://api.reverseum.fr/api/webhooks/subscriptions/{subscriptionId}

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+.

Variante contrat propre recommandée: POST /api/geo/search/v2.

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+.

Format attendu

latitude,longitude
48.8686,2.3303
43.6047,1.4442

Limite : jusqu’à 10 000 points (Reverseum Pro+ uniquement).

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 :

Code	Signification
400	Requête invalide (champ manquant / format incorrect / CSV invalide / trop de points batch).
401	Clé API manquante, invalide ou révoquée.
402	Aucune licence active.
403	Accès interdit (ex. endpoint réservé Pro+).
413	Fichier trop volumineux (selon limites serveur).
429	Usage au-delà des limites (rate limiting / protection).
500	Erreur interne temporaire (à retenter plus tard).

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).
Comparaison tournée V2 : map-matching, analyse d’ordre de passage et alertes avancées.

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