Routes API (Batch-Routenberechnung)

Verwenden Sie Routes, um mehrere Routen in einer einzigen Anfrage zu berechnen. REST liefert JSON, während SOAP für Batch-Routenberechnungen und Legacy-Integrationen CalculateRoutes verwendet.

Illustration der TrackRoad Routes API, die mehrere Routen in einer Anfrage berechnet und Distanzen sowie Zeiten zurückgibt.
Routes berechnet mehrere Routen in einem Aufruf und eignet sich daher für Bulk-Routenplanung, Routenvergleiche und Batch-Routing-Workflows.

Benötigen Sie den vollständigen API-Vertrag?

Swagger beschreibt die REST-Modelle, während das SOAP-WSDL Legacy-Integrationen mit TrackService unterstützt.

Swagger UI anzeigen SOAP WSDL anzeigen API-Referenzübersicht

Inhaltsverzeichnis

  1. Was Routes macht
  2. Endpunkte und Basis-URLs
  3. Authentifizierung (REST & SOAP)
  4. Anfrageschema
  5. Antwortschema
  6. Beispiele
  7. Häufige Fehler
  8. Best Practices
  9. Verwandte Endpunkte
  10. FAQ

Was Routes macht#

Routes berechnet eine oder mehrere Routen in einer einzelnen Anfrage. Das ist besonders nützlich, wenn Sie Batch-Routenberechnung benötigen, statt viele einzelne Route-Aufrufe zu senden.

Jede Route verwendet eine geordnete Liste von Location-Eingaben und optionalen RouteOptions. Zusätzlich können Sie ein globales RoutesOptions-Objekt definieren, das Standardwerte für die gesamte Anfrage festlegt.

Tipp: Wenn Sie nur eine einzelne Route benötigen, verwenden Sie die Route API . Wenn Sie mehrere Routen gleichzeitig berechnen möchten, verwenden Sie Routes.

Endpunkte und Basis-URLs#

REST (JSON)

Element Wert
Basis-URL https://trackservice.trackroad.com
Endpunkt POST /rest/routes
Vollständige URL https://trackservice.trackroad.com/rest/routes
Content-Type application/json

SOAP (CalculateRoutes)

Element Wert
SOAP-URL https://trackservice.trackroad.com/TrackService.asmx
WSDL https://trackservice.trackroad.com/TrackService.asmx?WSDL
Methode CalculateRoutes
SOAPAction http://TrackService.TrackRoad.com/CalculateRoutes
Content-Type text/xml; charset=utf-8

SOAP und REST verwenden dieselben zentralen Routing-Konzepte wie RouteSpecification, RouteOptions und Location. Der Hauptunterschied liegt im Transport: JSON bei REST und SOAP-Envelope + SessionIDHeader bei SOAP.

Authentifizierung (REST & SOAP)#

REST-Authentifizierung (X-API-Key)

Übergeben Sie Ihren TrackServiceKey bei jeder REST-Anfrage im Header X-API-Key. Siehe API-Authentifizierung .

SOAP-Authentifizierung (SessionIDHeader)

SOAP-Anfragen verwenden SessionIDHeader. Senden Sie Ihren TrackServiceKey bei jedem CalculateRoutes-Aufruf als SessionID.

Empfehlung: Verwenden Sie REST, außer Sie müssen mit einem bestehenden SOAP-only- oder Legacy-Unternehmenssystem integrieren.

Anfrageschema#

Der REST-Anfragekörper ist ein einzelnes Batch-Objekt: RoutesSpecification, das eine Liste von RouteSpecification-Elementen enthält. SOAP verwendet dieselbe logische Struktur innerhalb der CalculateRoutes-Operation.

Gemeinsame Modelle

Location, LatLong und Address werden über mehrere Endpunkte hinweg gemeinsam genutzt. Siehe Dispatch API (gemeinsame Modelle) .

RoutesSpecification (REST)

Eigenschaft Typ Erforderlich Beschreibung
Specifications RouteSpecification[] Ja* Ein Eintrag pro Route, die Sie in der Batch-Anfrage berechnen möchten.
RoutesOptions RouteOptions Nein Globale Standardwerte, die auf jede Route angewendet werden, sofern sie nicht durch RouteOptions pro Route überschrieben werden.

RouteSpecification

Eigenschaft Typ Erforderlich Beschreibung
Locations Location[] Ja* Stopps für diese Route. Die Reihenfolge kann abhängig von RouteOptions optimiert werden.
RouteOptions RouteOptions Nein Überschreibungen pro Route für Routing-Engine, Einheiten, Optimierungsmodus, Kultur und Kartenoptionen.

RouteOptions (Zusammenfassung)

RouteOptions-Felder wie RoutingService, DistanceUnit, RouteOptimize, Culture und kartenbezogene Einstellungen sind ähnlich wie beim Route-Endpunkt und können global oder pro Route angewendet werden.

Antwortschema#

REST-Antwort (RoutesResult)

Eigenschaft Typ Beschreibung
Results RouteResult[] Ein Ergebnis pro übergebener RouteSpecification.
Map string Optionale Kartenausgabe abhängig von den Optionen. Kann leer sein.
Errors Error[] Optionale Warnungen und Fehler, die vom Dienst zurückgegeben werden.
Status int (enum) 0=None, 1=Success, 2=Failed, 3=SuccessWithErrors.

SOAP-Antwort (CalculateRoutesResult)

SOAP kapselt dieselbe logische Ergebnisstruktur innerhalb von CalculateRoutesResponse und CalculateRoutesResult.

Beispiele#

Verwenden Sie die folgenden Beispiele, um zu verstehen, wie TrackRoad Routes mit REST JSON und SOAP CalculateRoutes arbeitet. Die Beispiel-Codeblöcke sollten sprachübergreifend unverändert bleiben.

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#

  • REST 401 / Unauthorized: Fehlender oder ungültiger X-API-Key.
  • REST 403 / Forbidden: Der Schlüssel ist gültig, aber gesperrt, abgelaufen oder verfügt nicht über ausreichendes Guthaben.
  • SOAP-Authentifizierungsfehler: Fehlender oder ungültiger SessionIDHeader. SessionID muss Ihr TrackServiceKey sein.
  • Validierungsfehler: Fehlende Locations, ungültige Koordinaten oder ungültige Enum-Werte.

Best Practices#

  • Clever bündeln: Fassen Sie mehrere Routenberechnungen in einem Routes-Aufruf zusammen, um Request-Overhead zu reduzieren.
  • LatLong bevorzugen: Übergeben Sie nach Möglichkeit Koordinaten, um Geocoding-Mehrdeutigkeiten zu vermeiden und die Performance zu verbessern.
  • Globale RoutesOptions verwenden: Definieren Sie gemeinsame Standardwerte einmal und überschreiben Sie sie nur dort, wo es pro Route nötig ist.
  • Optionen konsistent halten: Unterschiedliche Routing-Engines, Einheiten oder Optimierungsmodi über mehrere Routen hinweg erschweren den Vergleich.

FAQ#

Was macht die Routes API?
Die Routes API berechnet eine oder mehrere Routen in einer einzelnen Anfrage. Jedes Ergebnis kann geordnete Standorte, Distanz, Zeit und je nach Optionen eine optionale Kartenausgabe enthalten.
Wie authentifiziere ich mich bei Routes (REST und SOAP)?
REST-Anfragen senden den TrackServiceKey im Header X-API-Key. SOAP-CalculateRoutes-Anfragen senden den TrackServiceKey im SessionIDHeader als SessionID.
Wann sollte ich Routes statt Route verwenden?
Verwenden Sie Route, wenn Sie eine einzelne Route berechnen möchten. Verwenden Sie Routes, wenn Sie mehrere Routen in einer Batch-Anfrage berechnen möchten.
Was sind die häufigsten Fehler bei der Routes API?
Häufige Fehler sind ein fehlender oder ungültiger X-API-Key, SOAP-SessionIDHeader-Authentifizierungsfehler, fehlende Locations, ungültige Koordinaten und ungültige Enum-Werte.

Nächster Schritt: über mehrere Fahrzeuge optimieren

Wenn Sie Stopps mehreren Fahrzeugen zuweisen und die Reihenfolge der Stopps pro Fahrzeug optimieren möchten, fahren Sie mit der Dispatch API fort.

Zu Dispatch Swagger UI