API de Geocodificación (Dirección → Latitud/Longitud)

Use Geocode para convertir direcciones postales en coordenadas de latitud/longitud. La geocodificación suele ser el primer paso antes de la planificación de rutas o la optimización del despacho cuando todavía no dispone de coordenadas fiables para las paradas.

La API de Geocodificación de TrackRoad convierte una dirección en coordenadas de latitud/longitud para enrutamiento y despacho.
Ejemplo de la API de Geocodificación: convierta una dirección en coordenadas de latitud/longitud para un enrutamiento y despacho precisos.

Mejor práctica: valide las paradas antes de la optimización de rutas

Las direcciones incorrectas son una de las causas más comunes de paradas faltantes, rutas incorrectas y fallos de optimización evitables. Primero use Geocode y luego llame a Dispatch o Route.

Resumen de la referencia de API Ver Swagger UI

Tabla de contenido

  1. Qué es la geocodificación y por qué importa
  2. Qué hace Geocode
  3. Comprender MatchCode
  4. Endpoint REST y URL base
  5. Endpoint SOAP
  6. Autenticación
  7. Esquema de solicitud
  8. Esquema de respuesta
  9. Ejemplos
  10. Errores comunes
  11. Mejores prácticas
  12. Endpoints relacionados
  13. Preguntas frecuentes

Qué es la geocodificación y por qué importa#

La geocodificación convierte una dirección postal como 350 5th Ave, New York, NY en coordenadas de latitud/longitud que el software puede utilizar para el enrutamiento, el cálculo de ETA y la medición de distancias.

Los motores de optimización de rutas dependen de coordenadas precisas para las paradas. Cuando las direcciones son incompletas, ambiguas o incorrectas, los resultados de las rutas se vuelven menos fiables.

  • Las coordenadas incorrectas pueden generar rutas incorrectas, distancias erróneas y ETAs deficientes.
  • La falta de coordenadas puede provocar fallos de despacho, paradas omitidas o trabajo sin asignar.
  • Las direcciones ambiguas pueden dar lugar a valores de MatchCode bajos y resultados con menor confianza.

Si optimiza rutas sin validar antes las direcciones, es más probable que vea paradas faltantes, planes inviables o una mala calidad de ruta.

Qué hace Geocode#

Geocode acepta uno o más objetos Address y devuelve uno o más resultados candidatos de Location para cada dirección. Cada Location devuelta puede incluir coordenadas LatLong y un valor de MatchCode que le ayuda a evaluar la calidad de la coincidencia.

Transacciones: cada dirección geocodificada cuenta como una transacción, incluso cuando se envían varias direcciones en la misma solicitud.

Comprender MatchCode#

MatchCode es un indicador de confianza devuelto durante la geocodificación. Muestra qué tan bien TrackRoad hizo coincidir su dirección de entrada con una ubicación del mundo real.

  • Un MatchCode alto suele significar una coincidencia más precisa y normalmente es más seguro para el despacho.
  • Un MatchCode bajo suele significar que la dirección es incompleta, ambigua o menos fiable.
  • La ausencia de una coincidencia útil puede indicar una dirección no válida o que faltan datos de ciudad, estado, código postal o país.

Si el MatchCode es bajo, corrija la dirección o envíe directamente latitud/longitud cuando las coordenadas ya se conozcan.

Endpoint REST y URL base#

Elemento Valor
URL base https://trackservice.trackroad.com
Endpoint POST /rest/geocode
URL completa https://trackservice.trackroad.com/rest/geocode
Content-Type application/json

Las solicitudes REST de geocodificación usan POST y normalmente devuelven JSON. Según los detalles de integración, XML también puede estar disponible.

Endpoint SOAP#

Elemento Valor
URL SOAP https://trackservice.trackroad.com/TrackService.asmx
WSDL https://trackservice.trackroad.com/TrackService.asmx?wsdl
SOAPAction http://TrackService.TrackRoad.com/Geocode
Content-Type text/xml; charset=utf-8

Los sobres y encabezados de las solicitudes SOAP para Geocode están definidos en el WSDL y pueden variar según la versión de SOAP.

Autenticación#

Autenticación REST (X-API-Key)

Incluya su TrackServiceKey en el encabezado X-API-Key en cada solicitud REST. Consulte Autenticación de API .

curl -X POST "https://trackservice.trackroad.com/rest/geocode" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_TRACKSERVICEKEY" \
  -d '{ "IsNeedMatchCode": true, "Addresses": [] }'

Mantenga las claves API en el lado del servidor siempre que sea posible. Evite incrustar claves API de producción directamente en código de navegador o cliente móvil.

Autenticación SOAP (SessionIDHeader)

Las solicitudes SOAP usan un SessionIDHeader. En los servicios SOAP de TrackRoad, envíe su TrackServiceKey como valor de SessionID en cada llamada. Los métodos heredados de Login/Logout aún pueden aparecer en documentación antigua, pero no son necesarios para el uso moderno.

Recomendación: prefiera REST, a menos que deba integrarse con un sistema existente solo SOAP.

Esquema de solicitud#

El cuerpo de la solicitud es un único objeto GeocodeSpecification. Proporcione una o más direcciones que desee geocodificar.

GeocodeSpecification

Propiedad Tipo Obligatorio Descripción
IsNeedMatchCode bool No Si es true, incluye indicadores de calidad de coincidencia en el resultado. Recomendado para integraciones de producción.
Addresses Address[] Sí* Una o más direcciones para geocodificar. Cada dirección cuenta como una transacción.

Address

Address es un modelo compartido entre endpoints. El esquema completo de Address también está documentado en Dispatch API (modelos compartidos) .

Propiedad Tipo Obligatorio Descripción
Street string Recomendado Línea de dirección.
City string Recomendado Ciudad o localidad.
State string No Estado, provincia o región.
PostalCode string No Código postal.
Country string Recomendado Código de país o nombre del país, por ejemplo US.

Esquema de respuesta#

Una respuesta correcta devuelve un GeocodeResult que contiene uno o más objetos GeocodeItem. Cada elemento corresponde a una dirección de entrada.

GeocodeResult

Propiedad Tipo Descripción
Items GeocodeItem[] Un elemento por cada dirección de entrada. Cada elemento puede contener cero, una o varias ubicaciones candidatas.
Errors Error[] Errores o advertencias devueltos por el servicio.
Status int (enum) Código de estado como 0=None, 1=Success, 2=Failed o 3=SuccessWithErrors.

GeocodeItem

Propiedad Tipo Descripción
Address Address La dirección original de entrada.
Locations Location[] Resultados candidatos de geocodificación para la dirección.

Location, LatLong, MatchCode

Estos modelos se comparten entre distintos endpoints. Consulte las tablas completas del esquema en Dispatch API (modelos compartidos) .

Error

Propiedad Tipo Descripción
Message string Mensaje de error o advertencia legible para humanos.

Ejemplos#

Utilice las siguientes secciones para ejemplos de solicitudes y respuestas REST y SOAP. El código de ejemplo puede mantenerse neutro y no necesita localización.

REST JSON request example#

Send one or more addresses in a single request.

{
  "IsNeedMatchCode": true,
  "Addresses": [
    {
      "Street": "6718 Whittier Avenue",
      "City": "McLean",
      "State": "VA",
      "PostalCode": "22101",
      "Country": "US"
    },
    {
      "Street": "1450 Old Chain Bridge Road",
      "City": "McLean",
      "State": "VA",
      "PostalCode": "22101",
      "Country": "US"
    }
  ]
}

REST request examples (multiple languages)#

curl -X POST "https://trackservice.trackroad.com/rest/geocode" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_TRACKSERVICEKEY" \
  -d '{
    "IsNeedMatchCode": true,
    "Addresses": [
      { "Street": "6718 Whittier Avenue", "City": "McLean", "State": "VA", "PostalCode": "22101", "Country": "US" }
    ]
  }'

REST JSON response example (shape)#

{
  "Items": [
    {
      "Address": {
        "Street": "6718 Whittier Avenue",
        "City": "McLean",
        "State": "VA",
        "PostalCode": "22101",
        "Country": "US"
      },
      "Locations": [
        {
          "MatchCode": 4,
          "LatLong": { "Latitude": 38.931594, "Longitude": -77.17602 },
          "Address": {
            "Street": "6718 Whittier Avenue",
            "City": "McLean",
            "State": "VA",
            "PostalCode": "22101",
            "Country": "US"
          }
        }
      ]
    }
  ],
  "Errors": [],
  "Status": 1
}

SOAP 1.1 request example#

SOAP Geocode uses SessionIDHeader with SessionID = TrackServiceKey and SOAPAction http://TrackService.TrackRoad.com/Geocode.

<!-- POST https://trackservice.trackroad.com/TrackService.asmx -->
<!-- Content-Type: text/xml; charset=utf-8 -->
<!-- SOAPAction: "http://TrackService.TrackRoad.com/Geocode" -->

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
               xmlns:xsd="http://www.w3.org/2001/XMLSchema"
               xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">

  <soap:Header>
    <SessionIDHeader xmlns="http://TrackService.TrackRoad.com/">
      <SessionID>YOUR_TRACKSERVICEKEY</SessionID>
    </SessionIDHeader>
  </soap:Header>

  <soap:Body>
    <Geocode xmlns="http://TrackService.TrackRoad.com/">
      <specification>
        <IsNeedMatchCode>true</IsNeedMatchCode>
        <Addresses>
          <Address>
            <Street>6718 Whittier Avenue</Street>
            <City>McLean</City>
            <State>VA</State>
            <PostalCode>22101</PostalCode>
            <Country>US</Country>
          </Address>
        </Addresses>
      </specification>
    </Geocode>
  </soap:Body>
</soap:Envelope>

SOAP request examples (multiple languages)#

SOAP Geocode uses SessionIDHeader with SessionID = TrackServiceKey and SOAPAction http://TrackService.TrackRoad.com/Geocode.

curl -X POST "https://trackservice.trackroad.com/TrackService.asmx" \
  -H "Content-Type: text/xml; charset=utf-8" \
  -H "SOAPAction: "http://TrackService.TrackRoad.com/Geocode"" \
  -d '<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
               xmlns:xsd="http://www.w3.org/2001/XMLSchema"
               xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Header>
    <SessionIDHeader xmlns="http://TrackService.TrackRoad.com/">
      <SessionID>YOUR_TRACKSERVICEKEY</SessionID>
    </SessionIDHeader>
  </soap:Header>
  <soap:Body>
    <Geocode xmlns="http://TrackService.TrackRoad.com/">
      <specification>
        <IsNeedMatchCode>true</IsNeedMatchCode>
        <Addresses>
          <Address>
            <Street>6718 Whittier Avenue</Street>
            <City>McLean</City>
            <State>VA</State>
            <PostalCode>22101</PostalCode>
            <Country>US</Country>
          </Address>
        </Addresses>
      </specification>
    </Geocode>
  </soap:Body>
</soap:Envelope>'

SOAP response example (shape)#

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>

    <GeocodeResponse xmlns="http://TrackService.TrackRoad.com/">
      <GeocodeResult>

        <Status>1</Status>
        <Errors />

        <Items>
          <GeocodeItem>

            <Address>
              <Street>6718 Whittier Avenue</Street>
              <City>McLean</City>
              <State>VA</State>
              <PostalCode>22101</PostalCode>
              <Country>US</Country>
            </Address>

            <Locations>
              <Location>
                <MatchCode>4</MatchCode>
                <LatLong>
                  <Latitude>38.931594</Latitude>
                  <Longitude>-77.17602</Longitude>
                </LatLong>
                <Address>
                  <Street>6718 Whittier Avenue</Street>
                  <City>McLean</City>
                  <State>VA</State>
                  <PostalCode>22101</PostalCode>
                  <Country>US</Country>
                </Address>
              </Location>
            </Locations>

          </GeocodeItem>
        </Items>

      </GeocodeResult>
    </GeocodeResponse>

  </soap:Body>
</soap:Envelope>

Errores comunes#

  • 401 / Unauthorized: falta o es inválido el X-API-Key en solicitudes REST.
  • 403 / Forbidden: la clave puede ser válida, pero estar bloqueada, expirada o no poder procesar la solicitud.
  • Dirección no válida o incompleta: el servicio puede devolver cero candidatos, coincidencias débiles o valores bajos de MatchCode.
  • Fallo de autenticación SOAP: falta o es inválido el SessionIDHeader, donde SessionID debe contener su TrackServiceKey.

Mejores prácticas#

  • Almacene en caché los resultados de geocodificación en su sistema para no geocodificar la misma dirección repetidamente salvo que cambie.
  • Use entradas de dirección estables como calle, ciudad, estado, código postal y país para reducir la ambigüedad.
  • Use MatchCode para filtrar o aprobar resultados cuando la calidad de los datos sea importante.
  • Envíe LatLong a Dispatch o Route después de geocodificar para mejorar el rendimiento y evitar búsquedas repetidas.
  • Si Geocode devuelve múltiples candidatos, elija el mejor según la calidad de coincidencia y la dirección formateada que mejor se adapte a sus reglas de negocio.

Preguntas frecuentes#

¿Qué hace la API de Geocodificación?
La API de Geocodificación convierte direcciones postales en una o varias ubicaciones candidatas con coordenadas de latitud/longitud, ayudándole a preparar datos de paradas precisos para enrutamiento y despacho.
¿Cómo me autentico en la API de Geocodificación?
Para REST, envíe su TrackServiceKey en el encabezado X-API-Key. Para SOAP, envíe su TrackServiceKey en SessionIDHeader como SessionID.
¿Por qué la geocodificación puede devolver varios resultados?
Algunas direcciones son ambiguas o incompletas, por lo que la API puede devolver varias ubicaciones candidatas. Use MatchCode y los detalles de la dirección devuelta para elegir el mejor resultado.
¿Por qué debería geocodificar antes de la optimización de rutas?
Geocodificar antes de la optimización de rutas mejora la precisión de la ruta, las ETAs, la asignación de paradas y los cálculos de distancia al garantizar que cada parada tenga coordenadas válidas.

Siguiente paso: optimice rutas con coordenadas precisas

Después de geocodificar direcciones, use Dispatch o Route con coordenadas de latitud/longitud para generar ETAs, distancias y secuencias de ruta más precisas.

Ir a Dispatch API Ver Swagger UI