Routes API (Batch-routeberekening)

Gebruik Routes om meerdere routes in één aanvraag te berekenen. REST retourneert JSON, terwijl SOAP CalculateRoutes gebruikt voor batch-routeberekeningsworkflows en legacy-integraties.

Illustratie van de TrackRoad Routes API die meerdere routes in één aanvraag berekent en afstanden en tijden retourneert.
Routes berekent meerdere routes in één aanroep, wat het nuttig maakt voor bulk-routeplanning, routevergelijking en batch-routingworkflows.

Hebt u het volledige API-contract nodig?

Swagger behandelt de REST-modellen, terwijl de SOAP WSDL legacy TrackService-integraties ondersteunt.

Swagger UI bekijken SOAP WSDL bekijken Overzicht van de API-referentie

Inhoudsopgave

  1. Wat Routes doet
  2. Endpoints en basis-URL's
  3. Authenticatie (REST & SOAP)
  4. Aanvraagschema
  5. Antwoordschema
  6. Voorbeelden
  7. Veelvoorkomende fouten
  8. Best practices
  9. Gerelateerde endpoints
  10. FAQ

Wat Routes doet#

Routes berekent één of meerdere routes in één enkele aanvraag. Dit is handig wanneer u batch-routeberekening nodig hebt in plaats van veel afzonderlijke routeaanroepen te verzenden.

Elke route gebruikt een geordende lijst met Location-invoer en optionele RouteOptions. U kunt ook een globaal object RoutesOptions definiëren dat standaardwaarden toepast op de volledige aanvraag.

Tip: Als u slechts één route nodig hebt, gebruik dan Route API . Als u meerdere routes tegelijk wilt berekenen, gebruik dan Routes.

Endpoints en basis-URL's#

REST (JSON)

Item Waarde
Basis-URL https://trackservice.trackroad.com
Endpoint POST /rest/routes
Volledige URL https://trackservice.trackroad.com/rest/routes
Content-Type application/json

SOAP (CalculateRoutes)

Item Waarde
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 en REST delen dezelfde kernconcepten voor routing, zoals RouteSpecification, RouteOptions en Location. Het belangrijkste verschil is het transport: JSON voor REST en SOAP-envelope + SessionIDHeader voor SOAP.

Authenticatie (REST & SOAP)#

REST-authenticatie (X-API-Key)

Neem uw TrackServiceKey op in de X-API-Key-header bij elke REST-aanvraag. Zie API-authenticatie .

SOAP-authenticatie (SessionIDHeader)

SOAP-aanvragen gebruiken SessionIDHeader. Stuur uw TrackServiceKey als SessionID mee bij elke CalculateRoutes-aanroep.

Aanbevolen: gebruik REST, tenzij u moet integreren met een bestaand alleen-SOAP- of legacy-enterprisesysteem.

Aanvraagschema#

Gedeelde modellen

Location, LatLong en Address worden gedeeld over endpoints heen. Zie Dispatch API (gedeelde modellen) .

RoutesSpecification (REST)

Eigenschap Type Verplicht Beschrijving
Specifications RouteSpecification[] Ja* Eén item per route die u in de batch-aanvraag wilt berekenen.
RoutesOptions RouteOptions Nee Globale standaardwaarden die op elke route worden toegepast, tenzij overschreven door RouteOptions per route.

RouteSpecification

Eigenschap Type Verplicht Beschrijving
Locations Location[] Ja* Stops voor deze route. De volgorde kan worden geoptimaliseerd op basis van RouteOptions.
RouteOptions RouteOptions Nee Overschrijvingen per route voor routing-engine, eenheden, optimalisatiemodus, cultuur en kaartopties.

RouteOptions (samenvatting)

RouteOptions-velden zoals RoutingService, DistanceUnit, RouteOptimize, Culture en kaartgerelateerde instellingen zijn vergelijkbaar met het Route-endpoint en kunnen globaal of per route worden toegepast.

Antwoordschema#

REST-antwoord (RoutesResult)

Eigenschap Type Beschrijving
Results RouteResult[] Eén resultaat per ingevoerde RouteSpecification.
Map string Optionele kaartuitvoer afhankelijk van de opties. Deze kan leeg zijn.
Errors Error[] Optionele waarschuwingen en fouten die door de service worden geretourneerd.
Status int (enum) 0=None, 1=Success, 2=Failed, 3=SuccessWithErrors.

SOAP-antwoord (CalculateRoutesResult)

Voorbeelden#

Gebruik de onderstaande voorbeelden om te begrijpen hoe TrackRoad Routes werkt met zowel REST JSON als SOAP CalculateRoutes. De voorbeeld-codeblokken moeten in alle talen ongewijzigd blijven.

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
}

Veelvoorkomende fouten#

  • REST 403 / Forbidden: Sleutel is geldig, maar geblokkeerd, verlopen of zonder beschikbaar tegoed.
  • Validatiefouten: Ontbrekende Locations, ongeldige coördinaten of ongeldige enumwaarden.

Best practices#

  • Batch slim: Zet meerdere routeberekeningen in één Routes-aanroep om de aanvraagoverhead te verminderen.
  • Geef de voorkeur aan LatLong: Geef waar mogelijk coördinaten op om geocoderingsambiguïteit te verminderen en de prestaties te verbeteren.
  • Gebruik globale RoutesOptions: Stel gedeelde standaardwaarden één keer in en overschrijf alleen waar nodig per route.
  • Houd opties consistent: Het mixen van routing-engines, eenheden of optimalisatiemodi tussen routes kan vergelijkingen moeilijker maken.

FAQ#

Wat doet de Routes API?
De Routes API berekent één of meerdere routes in één aanvraag. Elk resultaat kan geordende locaties, afstand, tijd en optionele kaartuitvoer bevatten, afhankelijk van de opties.
Hoe authenticeer ik mij voor Routes (REST en SOAP)?
REST-aanvragen sturen de TrackServiceKey mee in de X-API-Key-header. SOAP CalculateRoutes-aanvragen sturen de TrackServiceKey mee in SessionIDHeader als SessionID.
Wanneer moet ik Routes gebruiken in plaats van Route?
Gebruik Route wanneer u één enkele route moet berekenen. Gebruik Routes wanneer u meerdere routes in één batch-aanvraag wilt berekenen.
Wat zijn de meest voorkomende fouten van de Routes API?
Veelvoorkomende fouten zijn onder meer een ontbrekende of ongeldige X-API-Key, SOAP-authenticatiefouten met SessionIDHeader, ontbrekende Locations, ongeldige coördinaten en ongeldige enumwaarden.

Volgende stap: optimaliseren over voertuigen heen

Als u stops aan meerdere voertuigen moet toewijzen en de stopvolgorde voor elk voertuig moet optimaliseren, ga dan verder met de Dispatch API.

Ga naar Dispatch Swagger UI