API Route (Ruta única)

Use Route para generar una ruta única con distancia total y tiempo de viaje , pasos detallados del itinerario y puntos de ruta . Para la optimización con varios vehículos, use Dispatch .

La API Route de TrackRoad genera una ruta única con distancia, tiempo de viaje e indicaciones giro a giro
Ejemplo de planificación de una ruta única que muestra la distancia, la ETA y la geometría de la ruta devuelta por la API Route.

¿Necesita el contrato completo?

Swagger incluye el esquema completo, los modelos y los detalles de los endpoints de Route y APIs relacionadas.

Ver Swagger UI Resumen de la referencia de API

Tabla de contenidos

  1. Qué hace Route
  2. Endpoints y URL base (REST + SOAP)
  3. Autenticación
  4. Esquema de solicitud
  5. Esquema de respuesta
  6. Ejemplos
  7. Errores comunes
  8. Buenas prácticas
  9. Endpoints relacionados
  10. Preguntas frecuentes

Qué hace Route#

Route calcula una sola ruta a través de una lista de ubicaciones. Devuelve la distancia total y el tiempo de viaje, tramos de ruta con instrucciones del itinerario, puntos de ruta y salida de mapa opcional según las opciones seleccionadas.

Se prefiere LatLong. Si omite las coordenadas de una ubicación, debe proporcionar una Address . Los modelos compartidos como Location, LatLong y Address están documentados en la API Dispatch .

Endpoints y URL base (REST + SOAP)#

REST

Elemento Valor
URL base https://trackservice.trackroad.com
Endpoint POST /rest/Route
URL completa https://trackservice.trackroad.com/rest/Route
Content-Type application/json
Autenticación X-API-Key: YOUR_TRACKSERVICEKEY

SOAP

Elemento Valor
WSDL https://trackservice.trackroad.com/TrackService.asmx?wsdl
Endpoint SOAP https://trackservice.trackroad.com/TrackService.asmx
Operación CalculateRoute
SOAPAction http://TrackService.TrackRoad.com/CalculateRoute
Namespace http://TrackService.TrackRoad.com/
Content-Type text/xml; charset=utf-8
Encabezado de autenticación SessionIDHeader con SessionID

Autenticación#

Autenticación REST (X-API-Key)

Incluya su TrackServiceKey en el encabezado X-API-Key en cada solicitud REST. Genérelo en API Authentication .

Autenticación SOAP (SessionIDHeader)

Las llamadas SOAP usan un SessionIDHeader. Flujo típico:

  1. Llame a Login (SOAP) con su nombre de usuario y contraseña.
  2. Lea el SessionIDHeader devuelto que contiene el SessionID.
  3. Envíe ese SessionID en el encabezado SOAP para las solicitudes CalculateRoute.

La autenticación REST y SOAP es independiente. REST usa X-API-Key. SOAP usa SessionIDHeader.

Esquema de solicitud#

El cuerpo de la solicitud REST es RouteSpecification. . SOAP usa la misma estructura lógica en XML. Los modelos compartidos están documentados en la API Dispatch .

RouteSpecification

Propiedad Tipo Obligatorio Descripción
Locations Location[] Sí* Lista de paradas de la ruta. Proporcione al menos 2 ubicaciones.
RouteOptions RouteOptions No Motor de enrutamiento, unidades, preferencia de ruta y opciones de mapa opcionales.

RouteOptions

Propiedad Tipo Obligatorio Descripción
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 Por ejemplo, en-US.
MapSize MapSize No Tamaño de salida opcional con Width y Height.
RouteColor RouteColor No Color opcional de la ruta en el mapa.
MapCenter LatLong No Coordenadas opcionales del centro del mapa.
HideStops bool No Si es true, los marcadores de parada se ocultan en la salida del mapa cuando esté disponible.
ZoomLevel int No 0=auto; en caso contrario, un nivel de zoom fijo.

Tipos compartidos

Para evitar duplicaciones, los modelos compartidos como Location, LatLong y Address se describen en la API Dispatch .

Esquema de respuesta#

Una respuesta correcta devuelve RouteResult con Route que contiene distancia, tiempo de viaje, tramos de ruta, pasos del itinerario, puntos de ruta y salida de mapa opcional.

RouteResult

Propiedad Tipo Descripción
Route Route Salida de ruta que incluye distancia, tiempo de viaje, tramos, puntos y mapa opcional.
Errors Error[] Errores o advertencias opcionales.
Status int (enum) 0=None, 1=Success, 2=Failed, 3=SuccessWithErrors.

Route

Propiedad Tipo Descripción
Distance double Distancia total. La unidad depende de DistanceUnit.
Time int Tiempo total de viaje en segundos.
RouteLegs RouteLeg[] Tramos de la ruta que contienen pasos del itinerario.
Points LatLong[] Puntos de la polilínea. Esta colección puede ser grande.
Map string Carga útil de mapa opcional según el comportamiento del servidor y las opciones.

Ejemplos#

Los cuerpos de solicitud de ejemplo, respuestas de ejemplo, encabezados y muestras de código específicas por lenguaje deben insertarse a continuación.

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
}

Errores comunes#

  • 401 / Unauthorized (REST): X-API-Key ausente o no válido.
  • Error de autenticación SOAP: SessionIDHeader ausente o no válido, o una ID de sesión caducada.
  • Errores de validación: Una ubicación puede no tener ni LatLong ni Address, las coordenadas pueden ser no válidas o puede que se hayan proporcionado muy pocas ubicaciones.
  • Ubicaciones no enrutables: Algunos puntos pueden no ser enrutables según el proveedor de enrutamiento o la calidad de los datos.

Buenas prácticas#

  • Prefiera LatLong para todas las ubicaciones para reducir el coste de geocodificación y la ambigüedad.
  • Elija cuidadosamente el modo de optimización: MinimizeTime para la ruta más rápida, MinimizeDistance para la ruta más corta.
  • Los puntos de la polilínea pueden ser muchos, así que solicítelos y guárdelos solo cuando necesite la geometría.
  • Use Dispatch para la optimización de rutas con varios vehículos o muchas paradas.

Preguntas frecuentes#

¿Qué devuelve la API Route?
Route devuelve la distancia total y el tiempo de viaje, tramos de ruta con pasos del itinerario, puntos de ruta y salida de mapa opcional según sus opciones.
¿Cómo me autentico?
REST usa X-API-Key. SOAP usa SessionIDHeader con un SessionID obtenido de la llamada SOAP Login.
¿Necesito LatLong o Address para las ubicaciones?
Se prefiere LatLong. Si se omite LatLong para una ubicación, se requiere Address para que el servicio pueda geocodificar la parada.
¿Cuándo debo usar Route en lugar de Dispatch?
Use Route cuando necesite una sola ruta con indicaciones y detalles del trayecto. Use Dispatch cuando necesite optimización de rutas con varios vehículos o muchas paradas.

Cree rutas en minutos

Genere su API key para REST o use SOAP Login para obtener un SessionID y comenzar a enrutar con TrackRoad.

Obtener API Key Ver Swagger UI