API Route (itinéraire unique)

Utilisez Route pour générer un itinéraire unique avec la distance totale et le temps de trajet , des étapes d’itinéraire détaillées et des points de route . Pour l’optimisation multi-véhicules, utilisez Dispatch .

L’API Route de TrackRoad génère un itinéraire unique avec distance, temps de trajet et indications pas à pas
Exemple de planification d’un itinéraire unique montrant la distance, l’ETA et la géométrie de la route renvoyées par l’API Route.

Besoin du contrat complet ?

Swagger inclut le schéma complet, les modèles et les détails des endpoints pour Route et les API associées.

Voir Swagger UI Vue d’ensemble de la référence API

Table des matières

  1. Ce que fait Route
  2. Endpoints et URL de base (REST + SOAP)
  3. Authentification
  4. Schéma de requête
  5. Schéma de réponse
  6. Exemples
  7. Erreurs courantes
  8. Bonnes pratiques
  9. Endpoints associés
  10. FAQ

Ce que fait Route#

Route calcule un itinéraire unique à travers une liste d’emplacements. Il renvoie la distance totale et le temps de trajet, des tronçons d’itinéraire avec instructions, des points de route et une sortie cartographique optionnelle selon les options sélectionnées.

LatLong est préférable. Si vous omettez les coordonnées pour un emplacement, vous devez fournir une Address . Les modèles partagés tels que Location, LatLong et Address sont documentés dans l’ API Dispatch .

Endpoints et URL de base (REST + SOAP)#

REST

Élément Valeur
URL de base https://trackservice.trackroad.com
Endpoint POST /rest/Route
URL complète https://trackservice.trackroad.com/rest/Route
Content-Type application/json
Authentification X-API-Key: YOUR_TRACKSERVICEKEY

SOAP

Élément Valeur
WSDL https://trackservice.trackroad.com/TrackService.asmx?wsdl
Endpoint SOAP https://trackservice.trackroad.com/TrackService.asmx
Opération CalculateRoute
SOAPAction http://TrackService.TrackRoad.com/CalculateRoute
Espace de noms http://TrackService.TrackRoad.com/
Content-Type text/xml; charset=utf-8
En-tête d’authentification SessionIDHeader avec SessionID

Authentification#

Authentification REST (X-API-Key)

Incluez votre TrackServiceKey dans l’en-tête X-API-Key de chaque requête REST. Générez-la dans API Authentication .

Authentification SOAP (SessionIDHeader)

Les appels SOAP utilisent un SessionIDHeader. Flux habituel :

  1. Appelez Login (SOAP) avec votre nom d’utilisateur et votre mot de passe.
  2. Lisez le SessionIDHeader renvoyé contenant le SessionID.
  3. Envoyez ce SessionID dans l’en-tête SOAP pour les requêtes CalculateRoute.

L’authentification REST et SOAP est distincte. REST utilise X-API-Key. SOAP utilise SessionIDHeader.

Schéma de requête#

Le corps de la requête REST est RouteSpecification. . SOAP utilise la même structure logique en XML. Les modèles partagés sont documentés dans l’ API Dispatch .

RouteSpecification

Propriété Type Obligatoire Description
Locations Location[] Oui* Liste des arrêts de l’itinéraire. Fournissez au moins 2 emplacements.
RouteOptions RouteOptions Non Moteur de routage, unités, préférence d’itinéraire et paramètres cartographiques facultatifs.

RouteOptions

Propriété Type Obligatoire Description
RoutingService int (enum) Non 0=NetRoad, 1=TrackRoad, 2=Bing.
DistanceUnit int (enum) Non 0=Mile, 1=Kilometer.
RouteOptimize int (enum) Non 0=MinimizeTime, 1=MinimizeDistance.
Culture string Non Par exemple, en-US.
MapSize MapSize Non Taille de sortie facultative avec Width et Height.
RouteColor RouteColor Non Couleur facultative de l’itinéraire sur la carte.
MapCenter LatLong Non Coordonnées facultatives du centre de la carte.
HideStops bool Non Si true, les marqueurs d’arrêt sont masqués dans la sortie cartographique lorsqu’elle est disponible.
ZoomLevel int Non 0=auto ; sinon un niveau de zoom fixe.

Types partagés

Pour éviter les duplications, les modèles partagés tels que Location, LatLong et Address sont décrits dans l’ API Dispatch .

Schéma de réponse#

Une réponse réussie renvoie RouteResult avec Route contenant la distance, le temps de trajet, les tronçons d’itinéraire, les étapes d’itinéraire, les points de route et une sortie cartographique optionnelle.

RouteResult

Propriété Type Description
Route Route Sortie d’itinéraire incluant distance, temps de trajet, tronçons, points et carte optionnelle.
Errors Error[] Erreurs ou avertissements facultatifs.
Status int (enum) 0=None, 1=Success, 2=Failed, 3=SuccessWithErrors.

Route

Propriété Type Description
Distance double Distance totale. L’unité dépend de DistanceUnit.
Time int Temps de trajet total en secondes.
RouteLegs RouteLeg[] Tronçons d’itinéraire contenant les étapes d’itinéraire.
Points LatLong[] Points de polyligne. Cette collection peut être volumineuse.
Map string Charge cartographique facultative selon le comportement du serveur et les options.

Exemples#

Les corps de requête d’exemple, réponses d’exemple, en-têtes et exemples de code par langage doivent être insérés ci-dessous.

REST request body (JSON)#

{
  "Locations": [
    { "Name": "Start", "LatLong": { "Latitude": 37.7946, "Longitude": -122.3950 }, "LocationType": 1 },
    { "Name": "Stop A", "LatLong": { "Latitude": 37.7897, "Longitude": -122.4011 }, "LocationType": 0 },
    { "Name": "Finish", "LatLong": { "Latitude": 37.7810, "Longitude": -122.4110 }, "LocationType": 2 }
  ],
  "RouteOptions": {
    "RoutingService": 2,
    "DistanceUnit": 0,
    "RouteOptimize": 0,
    "Culture": "en-US",
    "ZoomLevel": 0
  }
}

REST call examples#

curl -X POST "https://trackservice.trackroad.com/rest/Route" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_TRACKSERVICEKEY" \
  -d @route-request.json

SOAP request (CalculateRoute)#

SOAP requires SessionIDHeader. Replace YOUR_SESSION_ID with the session id returned from SOAP Login.

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Header>
    <SessionIDHeader xmlns="http://TrackService.TrackRoad.com/">
      <SessionID>YOUR_SESSION_ID</SessionID>
    </SessionIDHeader>
  </soap:Header>

  <soap:Body>
    <CalculateRoute xmlns="http://TrackService.TrackRoad.com/">
      <specification>
        <Locations>
          <Location>
            <Name>Start</Name>
            <LatLong><Latitude>37.7946</Latitude><Longitude>-122.3950</Longitude></LatLong>
            <LocationType>Start</LocationType>
          </Location>

          <Location>
            <Name>Stop A</Name>
            <LatLong><Latitude>37.7897</Latitude><Longitude>-122.4011</Longitude></LatLong>
            <LocationType>Midway</LocationType>
          </Location>

          <Location>
            <Name>Finish</Name>
            <LatLong><Latitude>37.7810</Latitude><Longitude>-122.4110</Longitude></LatLong>
            <LocationType>Finish</LocationType>
          </Location>
        </Locations>

        <RouteOptions>
          <RoutingService>Bing</RoutingService>
          <DistanceUnit>Mile</DistanceUnit>
          <RouteOptimize>MinimizeTime</RouteOptimize>
          <Culture>en-US</Culture>
          <ZoomLevel>0</ZoomLevel>
        </RouteOptions>
      </specification>
    </CalculateRoute>
  </soap:Body>
</soap:Envelope>

SOAP call examples#

curl -X POST "https://trackservice.trackroad.com/TrackService.asmx" \
  -H "Content-Type: text/xml; charset=utf-8" \
  -H "SOAPAction: http://TrackService.TrackRoad.com/CalculateRoute" \
  -d @calculate-route.xml

Response example (REST JSON)#

{
  "Route": {
    "Distance": 5.42,
    "Time": 1180,
    "RouteLegs": [
      {
        "Distance": 2.10,
        "Time": 480,
        "Itinerary": {
          "Items": [
            {
              "Distance": 0.2,
              "Time": 40,
              "Text": "Head north on ...",
              "LatLong": { "Latitude": 37.79, "Longitude": -122.39 }
            }
          ]
        }
      }
    ],
    "Points": [
      { "Latitude": 37.7946, "Longitude": -122.3950 },
      { "Latitude": 37.7897, "Longitude": -122.4011 }
    ],
    "Map": null
  },
  "Errors": [],
  "Status": 1
}

Erreurs courantes#

  • 401 / Unauthorized (REST) : X-API-Key manquant ou invalide.
  • Échec d’authentification SOAP : SessionIDHeader manquant ou invalide, ou identifiant de session expiré.
  • Erreurs de validation : Un emplacement peut ne contenir ni LatLong ni Address, les coordonnées peuvent être invalides ou trop peu d’emplacements ont été fournis.
  • Emplacements non routables : Certains points peuvent ne pas être routables selon le fournisseur de routage ou la qualité des données.

Bonnes pratiques#

  • Préférez LatLong pour tous les emplacements afin de réduire le coût de géocodage et l’ambiguïté.
  • Choisissez soigneusement le mode d’optimisation : MinimizeTime pour l’itinéraire le plus rapide, MinimizeDistance pour l’itinéraire le plus court.
  • Les points de polyligne peuvent être nombreux ; demandez-les et stockez-les uniquement lorsque la géométrie est nécessaire.
  • Utilisez Dispatch pour l’optimisation d’itinéraires multi-véhicules ou à nombreuses étapes.

FAQ#

Que renvoie l’API Route ?
Route renvoie la distance totale et le temps de trajet, les tronçons d’itinéraire avec étapes, les points de route et une sortie cartographique optionnelle selon vos options.
Comment m’authentifier ?
REST utilise X-API-Key. SOAP utilise SessionIDHeader avec un SessionID obtenu via l’appel SOAP Login.
Ai-je besoin de LatLong ou d’Address pour les emplacements ?
LatLong est préférable. Si LatLong est omis pour un emplacement, Address est requis afin que le service puisse géocoder l’arrêt.
Quand dois-je utiliser Route plutôt que Dispatch ?
Utilisez Route lorsque vous avez besoin d’un itinéraire unique avec indications et détails de trajet. Utilisez Dispatch lorsque vous avez besoin d’une optimisation multi-véhicules ou à nombreuses étapes.

Créez des itinéraires en quelques minutes

Générez votre clé API pour REST ou utilisez SOAP Login pour obtenir un SessionID, puis commencez le routage avec TrackRoad.

Obtenir une clé API Voir Swagger UI