Route API (Einzelroute)

Verwenden Sie Route , um eine einzelne Route mit gesamter Distanz und Fahrzeit , detaillierten Navigationsschritten und Routenpunkten zu erzeugen. Für die Multi-Fahrzeug-Optimierung verwenden Sie Dispatch .

TrackRoad Route API erstellt eine einzelne Route mit Distanz, Fahrzeit und Abbiegehinweisen
Beispiel für die Planung einer Einzelroute mit Distanz, ETA und Routengeometrie aus der Route API.

Benötigen Sie den vollständigen Vertrag?

Swagger enthält das vollständige Schema, die Modelle und Endpunktdetails für Route und verwandte APIs.

Swagger UI ansehen API-Referenz Übersicht

Inhaltsverzeichnis

  1. Was Route macht
  2. Endpunkte und Basis-URL (REST + SOAP)
  3. Authentifizierung
  4. Request-Schema
  5. Response-Schema
  6. Beispiele
  7. Häufige Fehler
  8. Best Practices
  9. Verwandte Endpunkte
  10. FAQ

Was Route macht#

Route berechnet eine einzelne Route durch eine Liste von Standorten. Die API liefert Gesamtdistanz und Fahrzeit, Routenabschnitte mit Navigationsanweisungen, Routenpunkte und optional eine Kartenausgabe – abhängig von den gewählten Optionen.

LatLong wird bevorzugt. Wenn Sie für einen Standort keine Koordinaten angeben, müssen Sie eine Adresse übergeben. Gemeinsame Modelle wie Location, LatLong und Address sind in der Dispatch API dokumentiert.

Endpunkte und Basis-URL (REST + SOAP)#

REST

Element Wert
Basis-URL https://trackservice.trackroad.com
Endpunkt POST /rest/Route
Vollständige URL https://trackservice.trackroad.com/rest/Route
Content-Type application/json
Authentifizierung X-API-Key: YOUR_TRACKSERVICEKEY

SOAP

Element Wert
WSDL https://trackservice.trackroad.com/TrackService.asmx?wsdl
SOAP-Endpunkt https://trackservice.trackroad.com/TrackService.asmx
Operation CalculateRoute
SOAPAction http://TrackService.TrackRoad.com/CalculateRoute
Namespace http://TrackService.TrackRoad.com/
Content-Type text/xml; charset=utf-8
Authentifizierungs-Header SessionIDHeader mit SessionID

Authentifizierung#

REST-Authentifizierung (X-API-Key)

Fügen Sie Ihren TrackServiceKey in den X-API-Key -Header jeder REST-Anfrage ein. Erstellen Sie ihn unter API Authentication .

SOAP-Authentifizierung (SessionIDHeader)

SOAP-Aufrufe verwenden einen SessionIDHeader. Typischer Ablauf:

  1. Rufen Sie Login (SOAP) mit Ihrem Benutzernamen und Passwort auf.
  2. Lesen Sie den zurückgegebenen SessionIDHeader mit der SessionID aus.
  3. Senden Sie diese SessionID im SOAP-Header für CalculateRoute-Anfragen mit.

REST- und SOAP-Authentifizierung sind getrennt. REST verwendet X-API-Key. SOAP verwendet SessionIDHeader.

Request-Schema#

Der REST-Request-Body ist RouteSpecification. . SOAP verwendet dieselbe logische Struktur in XML. Gemeinsame Modelle sind in der Dispatch API .

RouteSpecification

Eigenschaft Typ Erforderlich Beschreibung
Locations Location[] Ja* Liste der Routenstopps. Mindestens 2 Standorte erforderlich.
RouteOptions RouteOptions Nein Routing-Engine, Einheiten, Routenpräferenz und optionale Karteneinstellungen.

RouteOptions

Eigenschaft Typ Erforderlich Beschreibung
RoutingService int (enum) Nein 0=NetRoad, 1=TrackRoad, 2=Bing.
DistanceUnit int (enum) Nein 0=Mile, 1=Kilometer.
RouteOptimize int (enum) Nein 0=MinimizeTime, 1=MinimizeDistance.
Culture string Nein Zum Beispiel en-US.
MapSize MapSize Nein Optionale Ausgabegröße mit Width und Height.
RouteColor RouteColor Nein Optionale Farbe der Route auf der Karte.
MapCenter LatLong Nein Optionale Koordinaten für den Kartenzentrumspunkt.
HideStops bool Nein Wenn true, werden Stop-Markierungen in der Kartenausgabe ausgeblendet, sofern verfügbar.
ZoomLevel int Nein 0=auto, andernfalls ein fester Zoom-Level.

Gemeinsame Typen

Um Duplikate zu vermeiden, werden gemeinsame Modelle wie Location, LatLong und Address in der Dispatch API beschrieben.

Response-Schema#

Eine erfolgreiche Antwort gibt RouteResult mit Route zurück, einschließlich Distanz, Fahrzeit, Routenabschnitten, Navigationsschritten, Routenpunkten und optionaler Kartenausgabe.

RouteResult

Eigenschaft Typ Beschreibung
Route Route Routenausgabe mit Distanz, Fahrzeit, Abschnitten, Punkten und optionaler Karte.
Errors Error[] Optionale Fehler oder Warnungen.
Status int (enum) 0=None, 1=Success, 2=Failed, 3=SuccessWithErrors.

Route

Eigenschaft Typ Beschreibung
Distance double Gesamtdistanz. Die Einheit hängt von DistanceUnit ab.
Time int Gesamte Fahrzeit in Sekunden.
RouteLegs RouteLeg[] Routenabschnitte mit Navigationsschritten.
Points LatLong[] Polyline-Punkte. Diese Sammlung kann groß sein.
Map string Optionale Karten-Payload je nach Serververhalten und Optionen.

Beispiele#

Beispiel-Request-Bodies, Beispiel-Responses, Header und sprachspezifische Codebeispiele sollten unten eingefügt werden.

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
}

Häufige Fehler#

  • 401 / Unauthorized (REST): Fehlender oder ungültiger X-API-Key.
  • SOAP-Authentifizierungsfehler: Fehlender oder ungültiger SessionIDHeader oder eine abgelaufene Session-ID.
  • Validierungsfehler: Ein Standort kann sowohl LatLong als auch Address vermissen, Koordinaten können ungültig sein oder es wurden zu wenige Standorte übergeben.
  • Nicht routingfähige Standorte: Einige Punkte sind je nach Routing-Anbieter oder Datenqualität möglicherweise nicht routingfähig.

Best Practices#

  • LatLong bevorzugen für alle Standorte, um Geocoding-Kosten und Mehrdeutigkeiten zu reduzieren.
  • Wählen Sie den Optimierungsmodus bewusst: MinimizeTime für die schnellste Route, MinimizeDistance für die kürzeste Route.
  • Polyline Points können groß sein. Fordern und speichern Sie sie nur, wenn die Geometrie tatsächlich benötigt wird.
  • Verwenden Sie Dispatch für Multi-Fahrzeug- oder Many-Stop-Routenoptimierung.

FAQ#

Was gibt die Route API zurück?
Route liefert Gesamtdistanz und Fahrzeit, Routenabschnitte mit Navigationsschritten, Routenpunkte und – abhängig von Ihren Optionen – optional eine Kartenausgabe.
Wie authentifiziere ich mich?
REST verwendet X-API-Key. SOAP verwendet SessionIDHeader mit einer SessionID, die Sie aus dem SOAP-Login-Aufruf erhalten.
Benötige ich LatLong oder Address für Standorte?
LatLong wird bevorzugt. Wenn LatLong für einen Standort fehlt, ist Address erforderlich, damit der Dienst den Stopp geokodieren kann.
Wann sollte ich Route statt Dispatch verwenden?
Verwenden Sie Route, wenn Sie eine einzelne Route mit Navigationsanweisungen und Fahrdetails benötigen. Verwenden Sie Dispatch für Multi-Fahrzeug- oder Many-Stop-Routenoptimierung.

Routen in wenigen Minuten erstellen

Erzeugen Sie Ihren API-Key für REST oder verwenden Sie SOAP Login, um eine SessionID zu erhalten, und starten Sie dann mit dem Routing in TrackRoad.

API-Key erhalten Swagger UI ansehen