API Routes (Obliczanie tras wsadowo)

Użyj Routes, aby obliczyć wiele tras w jednym żądaniu. REST zwraca JSON, a SOAP używa CalculateRoutes do wsadowego obliczania tras i integracji ze starszymi systemami.

Ilustracja API Routes TrackRoad obliczającego wiele tras w jednym żądaniu i zwracającego odległości oraz czasy.
Routes oblicza wiele tras w jednym wywołaniu, co sprawia, że dobrze nadaje się do masowego planowania tras, porównywania tras i wsadowych przepływów routingu.

Potrzebujesz pełnego kontraktu API?

Swagger opisuje modele REST, a WSDL SOAP wspiera starsze integracje TrackService.

Otwórz Swagger UI Otwórz SOAP WSDL Przegląd dokumentacji API

Spis treści

  1. Co robi Routes
  2. Endpointy i bazowe adresy URL
  3. Uwierzytelnianie (REST i SOAP)
  4. Schemat żądania
  5. Schemat odpowiedzi
  6. Przykłady
  7. Typowe błędy
  8. Dobre praktyki
  9. Powiązane endpointy
  10. FAQ

Co robi Routes#

Routes oblicza jedną lub wiele tras w jednym żądaniu. Dzięki temu jest przydatne, gdy potrzebujesz wsadowego obliczania tras zamiast wysyłania wielu pojedynczych wywołań trasy.

Każda trasa używa uporządkowanej listy wejść Location oraz opcjonalnych RouteOptions. Możesz również zdefiniować globalny obiekt RoutesOptions, który zastosuje wartości domyślne do całego żądania.

Wskazówka: Jeśli potrzebujesz tylko jednej trasy, użyj API Route . Jeśli chcesz obliczyć wiele tras jednocześnie, użyj Routes.

Endpointy i bazowe adresy URL#

REST (JSON)

Element Wartość
Bazowy URL https://trackservice.trackroad.com
Endpoint POST /rest/routes
Pełny URL https://trackservice.trackroad.com/rest/routes
Content-Type application/json

SOAP (CalculateRoutes)

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

SOAP i REST współdzielą te same podstawowe pojęcia routingu, takie jak RouteSpecification, RouteOptions i Location. Główna różnica dotyczy transportu: JSON dla REST oraz koperta SOAP + SessionIDHeader dla SOAP.

Uwierzytelnianie (REST i SOAP)#

Uwierzytelnianie REST (X-API-Key)

Dołącz swój TrackServiceKey w nagłówku X-API-Key w każdym żądaniu REST. Zobacz Uwierzytelnianie API .

Uwierzytelnianie SOAP (SessionIDHeader)

Żądania SOAP używają SessionIDHeader. Wysyłaj swój TrackServiceKey jako SessionID przy każdym wywołaniu CalculateRoutes.

Zalecane: używaj REST, chyba że musisz integrować się z istniejącym systemem korporacyjnym typu legacy lub tylko SOAP.

Schemat żądania#

Treść żądania REST to pojedynczy obiekt wsadowy: RoutesSpecification, który zawiera listę elementów RouteSpecification. SOAP używa tej samej logicznej struktury wewnątrz operacji CalculateRoutes.

Współdzielone modele

Location, LatLong i Address są współdzielone między wieloma endpointami. Zobacz API Dispatch (współdzielone modele) .

RoutesSpecification (REST)

Właściwość Typ Wymagane Opis
Specifications RouteSpecification[] Tak* Jeden element dla każdej trasy, którą chcesz obliczyć w żądaniu wsadowym.
RoutesOptions RouteOptions Nie Globalne wartości domyślne stosowane do każdej trasy, chyba że zostaną nadpisane przez RouteOptions dla danej trasy.

RouteSpecification

Właściwość Typ Wymagane Opis
Locations Location[] Tak* Przystanki tej trasy. Kolejność może zostać zoptymalizowana w zależności od RouteOptions.
RouteOptions RouteOptions Nie Nadpisania dla pojedynczej trasy dotyczące silnika routingu, jednostek, trybu optymalizacji, kultury/języka i opcji mapy.

RouteOptions (podsumowanie)

Pola RouteOptions, takie jak RoutingService, DistanceUnit, RouteOptimize, Culture oraz ustawienia związane z mapą, są podobne do endpointu Route i mogą być stosowane globalnie lub dla pojedynczej trasy.

Schemat odpowiedzi#

Odpowiedź REST (RoutesResult)

Właściwość Typ Opis
Results RouteResult[] Jeden wynik dla każdej wejściowej RouteSpecification.
Map string Opcjonalny wynik mapy zależny od opcji. Może być pusty.
Errors Error[] Opcjonalne ostrzeżenia i błędy zwracane przez usługę.
Status int (enum) 0=None, 1=Success, 2=Failed, 3=SuccessWithErrors.

Odpowiedź SOAP (CalculateRoutesResult)

SOAP opakowuje tę samą logiczną strukturę wyniku w CalculateRoutesResponse oraz CalculateRoutesResult.

Przykłady#

Skorzystaj z poniższych przykładów, aby zrozumieć, jak działa TrackRoad Routes z REST JSON i SOAP CalculateRoutes. Bloki przykładowego kodu powinny pozostać niezmienione we wszystkich językach.

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
}

Typowe błędy#

  • REST 401 / Unauthorized: brakujący lub nieprawidłowy X-API-Key.
  • REST 403 / Forbidden: klucz jest prawidłowy, ale zablokowany, wygasł lub nie ma dostępnego kredytu.
  • Błąd uwierzytelniania SOAP: brakujący lub nieprawidłowy SessionIDHeader. SessionID musi być Twoim TrackServiceKey.
  • Błędy walidacji: brakujące Locations, nieprawidłowe współrzędne lub nieprawidłowe wartości enum.

Dobre praktyki#

  • Grupuj inteligentnie: umieszczaj wiele obliczeń tras w jednym wywołaniu Routes, aby zmniejszyć narzut żądań.
  • Preferuj LatLong: podawaj współrzędne, gdy to możliwe, aby ograniczyć niejednoznaczność geokodowania i poprawić wydajność.
  • Używaj globalnych RoutesOptions: ustaw wspólne wartości raz i nadpisuj je tylko tam, gdzie to konieczne dla pojedynczej trasy.
  • Zachowuj spójność opcji: mieszanie silników routingu, jednostek lub trybów optymalizacji między trasami może utrudnić porównania.

FAQ#

Co robi API Routes?
API Routes oblicza jedną lub wiele tras w jednym żądaniu. Każdy wynik może zawierać uporządkowane lokalizacje, odległość, czas oraz opcjonalny wynik mapy w zależności od ustawień.
Jak uwierzytelnić się w Routes (REST i SOAP)?
Żądania REST wysyłają TrackServiceKey w nagłówku X-API-Key. Żądania SOAP CalculateRoutes wysyłają TrackServiceKey w SessionIDHeader jako SessionID.
Kiedy używać Routes zamiast Route?
Użyj Route, gdy chcesz obliczyć jedną trasę. Użyj Routes, gdy chcesz obliczyć wiele tras w jednym żądaniu wsadowym.
Jakie są najczęstsze błędy API Routes?
Typowe błędy obejmują brakujący lub nieprawidłowy X-API-Key, błędy uwierzytelniania SOAP z SessionIDHeader, brakujące Locations, nieprawidłowe współrzędne i nieprawidłowe wartości enum.

Następny krok: optymalizacja między wieloma pojazdami

Jeśli chcesz przypisać przystanki do wielu pojazdów i zoptymalizować kolejność przystanków dla każdego pojazdu, przejdź do API Dispatch.

Przejdź do Dispatch Swagger UI