API Route (pojedyncza trasa)

Użyj Route , aby wygenerować pojedynczą trasę z łącznym dystansem i czasem przejazdu , szczegółowymi krokami trasy oraz punktami trasy . Do optymalizacji wielu pojazdów użyj Dispatch .

API Route TrackRoad generuje pojedynczą trasę z dystansem, czasem przejazdu i wskazówkami krok po kroku
Przykład planowania pojedynczej trasy pokazujący dystans, ETA i geometrię trasy zwrócone przez API Route.

Potrzebujesz pełnej specyfikacji?

Swagger zawiera pełny schemat, modele i szczegóły endpointów dla Route oraz powiązanych API.

Otwórz Swagger UI Przegląd dokumentacji API

Spis treści

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

Co robi Route#

Route oblicza pojedynczą trasę przez listę lokalizacji. Zwraca łączny dystans i czas przejazdu, odcinki trasy z instrukcjami przejazdu, punkty trasy oraz opcjonalny wynik mapy w zależności od wybranych opcji.

LatLong jest preferowane. Jeśli pominiesz współrzędne dla lokalizacji, musisz podać Address . Wspólne modele, takie jak Location, LatLong i Address, są udokumentowane w API Dispatch .

Endpointy i bazowy URL (REST + SOAP)#

REST

Element Wartość
Bazowy URL https://trackservice.trackroad.com
Endpoint POST /rest/Route
Pełny URL https://trackservice.trackroad.com/rest/Route
Content-Type application/json
Uwierzytelnianie X-API-Key: YOUR_TRACKSERVICEKEY

SOAP

Element Wartość
WSDL https://trackservice.trackroad.com/TrackService.asmx?wsdl
Endpoint SOAP https://trackservice.trackroad.com/TrackService.asmx
Operacja CalculateRoute
SOAPAction http://TrackService.TrackRoad.com/CalculateRoute
Namespace http://TrackService.TrackRoad.com/
Content-Type text/xml; charset=utf-8
Nagłówek uwierzytelniania SessionIDHeader z SessionID

Uwierzytelnianie#

Uwierzytelnianie REST (X-API-Key)

Dodaj swój TrackServiceKey do nagłówka X-API-Key w każdym żądaniu REST. Wygeneruj go w API Authentication .

Uwierzytelnianie SOAP (SessionIDHeader)

Wywołania SOAP używają SessionIDHeader. Typowy przebieg:

  1. Wywołaj Login (SOAP) za pomocą nazwy użytkownika i hasła.
  2. Odczytaj zwrócony SessionIDHeader zawierający SessionID.
  3. Przekaż ten SessionID w nagłówku SOAP dla żądań CalculateRoute.

Uwierzytelnianie REST i SOAP jest rozdzielone. REST używa X-API-Key. SOAP używa SessionIDHeader.

Schemat żądania#

Body żądania REST to RouteSpecification. . SOAP używa tej samej logicznej struktury w XML. Wspólne modele są udokumentowane w API Dispatch .

RouteSpecification

Właściwość Typ Wymagane Opis
Locations Location[] Tak* Lista przystanków na trasie. Podaj co najmniej 2 lokalizacje.
RouteOptions RouteOptions Nie Silnik routingu, jednostki, preferencja trasy i opcjonalne ustawienia mapy.

RouteOptions

Właściwość Typ Wymagane Opis
RoutingService int (enum) Nie 0=NetRoad, 1=TrackRoad, 2=Bing.
DistanceUnit int (enum) Nie 0=Mile, 1=Kilometer.
RouteOptimize int (enum) Nie 0=MinimizeTime, 1=MinimizeDistance.
Culture string Nie Na przykład en-US.
MapSize MapSize Nie Opcjonalny rozmiar wyniku z Width i Height.
RouteColor RouteColor Nie Opcjonalny kolor trasy na mapie.
MapCenter LatLong Nie Opcjonalne współrzędne środka mapy.
HideStops bool Nie Jeśli true, znaczniki przystanków są ukrywane w wyniku mapy, gdy jest dostępny.
ZoomLevel int Nie 0=auto; w przeciwnym razie stały poziom powiększenia.

Typy współdzielone

Aby uniknąć powielania, współdzielone modele, takie jak Location, LatLong i Address, są opisane w API Dispatch .

Schemat odpowiedzi#

Prawidłowa odpowiedź zwraca RouteResult z Route zawierającym dystans, czas przejazdu, odcinki trasy, kroki trasy, punkty trasy i opcjonalny wynik mapy.

RouteResult

Właściwość Typ Opis
Route Route Wynik trasy obejmujący dystans, czas przejazdu, odcinki, punkty i opcjonalną mapę.
Errors Error[] Opcjonalne błędy lub ostrzeżenia.
Status int (enum) 0=None, 1=Success, 2=Failed, 3=SuccessWithErrors.

Route

Właściwość Typ Opis
Distance double Łączny dystans. Jednostka zależy od DistanceUnit.
Time int Łączny czas przejazdu w sekundach.
RouteLegs RouteLeg[] Odcinki trasy zawierające kroki trasy.
Points LatLong[] Punkty polilinii. Ta kolekcja może być duża.
Map string Opcjonalny ładunek mapy zależny od działania serwera i opcji.

Przykłady#

Poniżej należy wstawić przykładowe body żądań, przykładowe odpowiedzi, nagłówki i przykłady kodu dla poszczególnych języków.

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#

  • 401 / Unauthorized (REST): Brakujący lub nieprawidłowy X-API-Key.
  • Błąd uwierzytelniania SOAP: Brakujący lub nieprawidłowy SessionIDHeader albo wygasły identyfikator sesji.
  • Błędy walidacji: Lokalizacja może nie mieć ani LatLong, ani Address, współrzędne mogą być nieprawidłowe lub podano zbyt mało lokalizacji.
  • Lokalizacje nienawigowalne: Niektóre punkty mogą nie być routowalne w zależności od dostawcy routingu lub jakości danych.

Dobre praktyki#

  • Preferuj LatLong dla wszystkich lokalizacji, aby ograniczyć koszt geokodowania i niejednoznaczność.
  • Dobierz tryb optymalizacji świadomie: MinimizeTime dla najszybszej trasy, MinimizeDistance dla najkrótszej trasy.
  • Punkty polilinii mogą być liczne, więc pobieraj i zapisuj je tylko wtedy, gdy potrzebujesz geometrii.
  • Użyj Dispatch do optymalizacji tras wielopojazdowych lub wieloprzystankowych.

FAQ#

Co zwraca API Route?
Route zwraca łączny dystans i czas przejazdu, odcinki trasy z krokami trasy, punkty trasy oraz opcjonalny wynik mapy w zależności od wybranych opcji.
Jak się uwierzytelnić?
REST używa X-API-Key. SOAP używa SessionIDHeader z SessionID uzyskanym z wywołania SOAP Login.
Czy potrzebuję LatLong czy Address dla lokalizacji?
LatLong jest preferowane. Jeśli LatLong zostanie pominięte dla lokalizacji, wymagane jest Address, aby usługa mogła zgeokodować przystanek.
Kiedy używać Route zamiast Dispatch?
Użyj Route, gdy potrzebujesz pojedynczej trasy ze wskazówkami i szczegółami przejazdu. Użyj Dispatch, gdy potrzebujesz optymalizacji wielopojazdowej lub dla wielu przystanków.

Twórz trasy w kilka minut

Wygeneruj swój klucz API dla REST albo użyj SOAP Login, aby uzyskać SessionID, a następnie rozpocznij routing w TrackRoad.

Uzyskaj API Key Otwórz Swagger UI