API Route (Percorso singolo)

Usa Route per generare un percorso singolo con distanza totale e tempo di viaggio , passaggi dettagliati dell’itinerario e punti del percorso . Per l’ottimizzazione multi-veicolo, usa Dispatch .

L’API Route di TrackRoad genera un singolo percorso con distanza, tempo di viaggio e indicazioni turn-by-turn
Esempio di pianificazione di un percorso singolo che mostra distanza, ETA e geometria del percorso restituiti dall’API Route.

Ti serve il contratto completo?

Swagger include lo schema completo, i modelli e i dettagli degli endpoint per Route e le API correlate.

Apri Swagger UI Panoramica riferimento API

Indice dei contenuti

  1. Cosa fa Route
  2. Endpoint e URL di base (REST + SOAP)
  3. Autenticazione
  4. Schema della richiesta
  5. Schema della risposta
  6. Esempi
  7. Errori comuni
  8. Best practice
  9. Endpoint correlati
  10. FAQ

Cosa fa Route#

Route calcola un singolo percorso attraverso un elenco di località. Restituisce la distanza totale e il tempo di viaggio, le tratte del percorso con istruzioni dell’itinerario, i punti del percorso e un output mappa opzionale in base alle opzioni selezionate.

LatLong è preferito. Se ometti le coordinate per una località, devi fornire un Address . I modelli condivisi come Location, LatLong e Address sono documentati nella API Dispatch .

Endpoint e URL di base (REST + SOAP)#

REST

Elemento Valore
URL di base https://trackservice.trackroad.com
Endpoint POST /rest/Route
URL completo https://trackservice.trackroad.com/rest/Route
Content-Type application/json
Autenticazione X-API-Key: YOUR_TRACKSERVICEKEY

SOAP

Elemento Valore
WSDL https://trackservice.trackroad.com/TrackService.asmx?wsdl
Endpoint SOAP https://trackservice.trackroad.com/TrackService.asmx
Operazione CalculateRoute
SOAPAction http://TrackService.TrackRoad.com/CalculateRoute
Namespace http://TrackService.TrackRoad.com/
Content-Type text/xml; charset=utf-8
Header di autenticazione SessionIDHeader con SessionID

Autenticazione#

Autenticazione REST (X-API-Key)

Includi il tuo TrackServiceKey nell’header X-API-Key in ogni richiesta REST. Generala in API Authentication .

Autenticazione SOAP (SessionIDHeader)

Le chiamate SOAP utilizzano un SessionIDHeader. Flusso tipico:

  1. Chiama Login (SOAP) con nome utente e password.
  2. Leggi il SessionIDHeader restituito contenente il SessionID.
  3. Invia quel SessionID nell’header SOAP per le richieste CalculateRoute.

L’autenticazione REST e SOAP è separata. REST usa X-API-Key. SOAP usa SessionIDHeader.

Schema della richiesta#

Il body della richiesta REST è RouteSpecification. . SOAP usa la stessa struttura logica in XML. I modelli condivisi sono documentati nella API Dispatch .

RouteSpecification

Proprietà Tipo Obbligatorio Descrizione
Locations Location[] Sì* Elenco delle fermate del percorso. Fornisci almeno 2 località.
RouteOptions RouteOptions No Motore di routing, unità, preferenza di percorso e impostazioni mappa opzionali.

RouteOptions

Proprietà Tipo Obbligatorio Descrizione
RoutingService int (enum) No 0=NetRoad, 1=TrackRoad, 2=Bing.
DistanceUnit int (enum) No 0=Mile, 1=Kilometer.
RouteOptimize int (enum) No 0=MinimizeTime, 1=MinimizeDistance.
Culture string No Ad esempio, en-US.
MapSize MapSize No Dimensione di output opzionale con Width e Height.
RouteColor RouteColor No Colore opzionale del percorso sulla mappa.
MapCenter LatLong No Coordinate opzionali del centro mappa.
HideStops bool No Se true, i marker delle fermate sono nascosti nell’output mappa quando disponibile.
ZoomLevel int No 0=auto; altrimenti un livello di zoom fisso.

Tipi condivisi

Per evitare duplicazioni, i modelli condivisi come Location, LatLong e Address sono descritti nella API Dispatch .

Schema della risposta#

Una risposta corretta restituisce RouteResult con Route contenente distanza, tempo di viaggio, tratte del percorso, passaggi dell’itinerario, punti del percorso e output mappa opzionale.

RouteResult

Proprietà Tipo Descrizione
Route Route Output del percorso che include distanza, tempo di viaggio, tratte, punti e mappa opzionale.
Errors Error[] Errori o avvisi opzionali.
Status int (enum) 0=None, 1=Success, 2=Failed, 3=SuccessWithErrors.

Route

Proprietà Tipo Descrizione
Distance double Distanza totale. L’unità dipende da DistanceUnit.
Time int Tempo totale di viaggio in secondi.
RouteLegs RouteLeg[] Tratte del percorso contenenti i passaggi dell’itinerario.
Points LatLong[] Punti della polilinea. Questa raccolta può essere grande.
Map string Payload mappa opzionale in base al comportamento del server e alle opzioni.

Esempi#

I body di richiesta di esempio, le risposte di esempio, gli header e gli esempi di codice specifici per linguaggio devono essere inseriti qui sotto.

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
}

Errori comuni#

  • 401 / Unauthorized (REST): X-API-Key mancante o non valido.
  • Errore di autenticazione SOAP: SessionIDHeader mancante o non valido, oppure ID sessione scaduto.
  • Errori di validazione: Una località potrebbe non avere né LatLong né Address, le coordinate potrebbero essere non valide oppure potrebbero essere state fornite troppo poche località.
  • Località non instradabili: Alcuni punti potrebbero non essere instradabili in base al provider di routing o alla qualità dei dati.

Best practice#

  • Preferisci LatLong per tutte le località per ridurre i costi di geocodifica e l’ambiguità.
  • Scegli con attenzione la modalità di ottimizzazione: MinimizeTime per il percorso più veloce, MinimizeDistance per il percorso più corto.
  • I punti della polilinea possono essere numerosi, quindi richiedili e salvali solo quando hai bisogno della geometria.
  • Usa Dispatch per l’ottimizzazione di percorsi multi-veicolo o con molte fermate.

FAQ#

Cosa restituisce l’API Route?
Route restituisce distanza totale e tempo di viaggio, tratte del percorso con passaggi dell’itinerario, punti del percorso e output mappa opzionale in base alle tue opzioni.
Come mi autentico?
REST usa X-API-Key. SOAP usa SessionIDHeader con un SessionID ottenuto dalla chiamata SOAP Login.
Ho bisogno di LatLong o Address per le località?
LatLong è preferito. Se LatLong viene omesso per una località, è richiesto Address affinché il servizio possa geocodificare la fermata.
Quando dovrei usare Route invece di Dispatch?
Usa Route quando hai bisogno di un singolo percorso con indicazioni e dettagli di viaggio. Usa Dispatch quando hai bisogno di ottimizzazione multi-veicolo o con molte fermate.

Crea percorsi in pochi minuti

Genera la tua API key per REST oppure usa SOAP Login per ottenere un SessionID e iniziare il routing con TrackRoad.

Ottieni API Key Apri Swagger UI