Distance Matrix API

Este servicio también está disponible como parte de la API de JavaScript de Maps del lado del cliente, o para uso del lado del servidor con el cliente Java, el cliente Python, el cliente Go y el cliente Node.js para los servicios de Google Maps.

La API Distance Matrix es un servicio que proporciona la distancia y el tiempo de viaje para una matriz de orígenes y destinos. La API devuelve información basada en la ruta recomendada entre os puntos inicial y final, calculada por la API de Google Maps, y consta de filas que contienen valores duration y distance para cada par.

Antes de que empieces

Este documento está dirigido a desarrolladores que deseen calcular la distancia y el tiempo de viaje entre varios puntos dentro de los mapas proporcionados por una de las API de Google Maps. Proporciona una introducción al uso de la API y material de referencia sobre los parámetros disponibles.

Antes de comenzar a desarrollar con la API de Distance Matrix, revise los requisitos de autenticación (necesita una clave de API) y el uso de la API y la información de facturación (debe habilitar la facturación en su proyecto).

Solicitudes de matriz de distancia

Una solicitud de API de matriz de distancia tiene la siguiente forma:

donde outputFormat puede ser cualquiera de los siguientes valores:

• json(recomendado), indica la salida en notación de objetos JavaScript (JSON); o
• xml, indica la salida como XML.

HTTPS o HTTP

La seguridad es importante y se recomienda HTTPS siempre que sea posible, especialmente para aplicaciones que incluyen datos confidenciales del usuario, como la ubicación de un usuario, en las solicitudes. El uso de la encriptación HTTPS hace que su aplicación sea más segura y más resistente a espionaje o manipulación.

Si HTTPS no es posible, para acceder a la API de Distance Matrix a través de HTTP, use:

Solicitar parámetros

Algunos parámetros son obligatorios mientras que otros son opcionales. Como es estándar en las URL, todos los parámetros se separan mediante el carácter ampersand (&). Todos los caracteres reservados (por ejemplo, el signo más "+") deben estar codificados como URL . La lista de parámetros y sus posibles valores se enumeran a continuación.

Parámetros requeridos

• origins: El punto de partida para calcular la distancia y el tiempo de viaje. Puede proporcionar una o más ubicaciones separadas por el carácter de barra vertical (|), en forma de un ID de lugar, una dirección o coordenadas de latitud/longitud:
  • Si proporciona un ID de lugar, debe anteponerlo con place_id:. Solo puede especificar un ID de lugar si la solicitud incluye una clave de API o un ID de cliente del Plan Premium de Google Maps Platform. Puede recuperar los ID de lugares de la API de codificación geográfica y la API de lugares (incluida la función Autocompletar de lugares). Para ver un ejemplo de uso de los ID de lugar de Autocompletar de lugares, consulte Place Autocomplete e Indicaciones . Para obtener más información sobre los ID de lugares, consulte la descripción general de los ID de lugares .
  • Si pasa una dirección, el servicio geocodifica la cadena y la convierte en una coordenada de latitud/longitud para calcular la distancia. Esta coordenada puede ser diferente de la devuelta por la API de codificación geográfica, por ejemplo, la entrada de un edificio en lugar de su centro.

origins=Bobcaygeon+ON|24+Sussex+Drive+Ottawa+ON

Si pasa las coordenadas de latitud/longitud, se ajustarán a la carretera más cercana. Se prefiere pasar una identificación de lugar. Si pasa coordenadas, asegúrese de que no exista ningún espacio entre los valores de latitud y longitud.

origins=41.43206,-81.38992|-33.86748,151.20699

origins=place_id:ChIJ3S-JXmauEmsRUcIaWtf4MzE

• • Los códigos plus deben formatearse como un código global o un código compuesto. Formatee los códigos más como se muestra aquí (los signos más se escapan a la %2B URL y los espacios se escapan a la URL %20):
    • El código global es un código de área de 4 caracteres y un código local de 6 caracteres o más (849VCWC8 + R9 es 849VCWC8%2BR9).
    • El código compuesto es un código local de 6 caracteres o más con una ubicación explícita (CWC8 + R9 Mountain View, CA, EE CWC8%2BR9%20Mountain%20View%20CA%20USA. UU. es ).
  • Alternativamente, puede proporcionar un conjunto codificado de coordenadas utilizando el algoritmo de polilínea codificada . Esto es particularmente útil si tiene una gran cantidad de puntos de origen, porque la URL es significativamente más corta cuando se usa una polilínea codificada.
    • Las polilíneas codificadas deben ir precedidas enc: y seguidas de dos puntos (:). Por ejemplo: origins=enc:gfo}EtohhU:
    • También puede incluir varias polilíneas codificadas, separadas por el carácter de barra vertical (|). Por ejemplo: origins=enc:wc~oAwquwMdlTxiKtqLyiK:|enc:c~vnAamswMvlTor@tjGi}L:|enc:udymA{~bxM:
• destinations: Una o más ubicaciones para usar como punto final para calcular la distancia y el tiempo de viaje. Las opciones para el  parámetro destinations son las mismas que para el parámetro origins, descrito anteriormente.
• key: La clave API de su aplicación. Esta clave identifica su aplicación a los efectos de la gestión de cuotas. Aprenda a obtener una llave.

El siguiente ejemplo utiliza coordenadas de latitud/longitud para especificar las coordenadas de destino:

El siguiente ejemplo utiliza códigos más para especificar las coordenadas de destino:

El siguiente ejemplo muestra la misma solicitud usando una polilínea codificada:

• traffic_model(predeterminado en best_guess): especifica las suposiciones que se utilizarán al calcular el tiempo en el tráfico. Esta configuración afecta el valor devuelto en el duration_in_traffic campo de la respuesta, que contiene el tiempo previsto en el tráfico según los promedios históricos. El traffic_modelparámetro solo se puede especificar para solicitudes en las que se encuentre el modo de viaje drivingy en las que la solicitud incluya un departure_time, y solo si la solicitud incluye una clave de API o un ID de cliente del Plan Premium de Google Maps Platform. Los valores disponibles para este parámetro son:
  • best_guess(predeterminado) indica que la devolución duration_in_trafficdebe ser la mejor estimación del tiempo de viaje dado lo que se conoce tanto sobre las condiciones históricas del tráfico como sobre el tráfico en vivo. El tráfico en vivo se vuelve más importante cuanto más cerca departure_timeestá el ahora.
  • pessimisticindica que la devolución duration_in_trafficdebe ser más larga que el tiempo de viaje real en la mayoría de los días, aunque los días ocasionales con condiciones de tráfico particularmente malas pueden exceder este valor.
  • optimisticindica que la devolución duration_in_trafficdebe ser más corta que el tiempo de viaje real en la mayoría de los días, aunque los días ocasionales con condiciones de tráfico particularmente buenas pueden ser más rápidos que este valor.
• transit_mode- Especifica uno o más modos de tránsito preferidos. Este parámetro solo se puede especificar para solicitudes donde modees transit. El parámetro admite los siguientes argumentos:
  • bus indica que la ruta calculada debe preferir viajar en autobús.
  • subway indica que la ruta calculada debería preferir viajar en metro.
  • train indica que la ruta calculada debería preferir viajar en tren.
  • tram indica que la ruta calculada debería preferir viajar en tranvía y tren ligero.
  • railindica que la ruta calculada debería preferir viajar en tren, tranvía, tren ligero y metro. Esto es equivalente a transit_mode=train|tram|subway.
• transit_routing_preference- Especifica preferencias para solicitudes de tránsito. Con este parámetro, puede sesgar las opciones devueltas, en lugar de aceptar la mejor ruta predeterminada elegida por la API. Este parámetro solo se puede especificar para solicitudes donde modees transit. El parámetro admite los siguientes argumentos:
  • less_walking indica que la ruta calculada debe preferir una caminata limitada.
  • fewer_transfers indica que la ruta calculada debería preferir un número limitado de transferencias.

Modos de viaje

Para el cálculo de distancias, puede especificar el transporte mode a utilizar. De forma predeterminada, las distancias se calculan para el modo de conducción. Se admiten los siguientes modos de viaje:

• driving (predeterminado): indica el cálculo de la distancia utilizando la red de carreteras.
• walking: solicita el cálculo de la distancia para caminar por caminos peatonales y aceras (donde esté disponible).
• bicycling: solicita el cálculo de la distancia para andar en bicicleta a través de carriles bici y calles preferidas (donde estén disponibles)
• transit: solicita el cálculo de la distancia a través de rutas de transporte público (donde esté disponible). Este valor solo se puede especificar si la solicitud incluye una clave API o un ID de cliente del Plan Premium de Google Maps Platform. Si configura el modo en transit, puede especificar opcionalmente un departure_timeo un arrival_time. Si no se especifica ninguna hora departure_time, la hora predeterminada es ahora (es decir, la hora de salida predeterminada es la hora actual). También puede incluir opcionalmente un transit_mode y/o un transit_routing_preference.

Información de tráfico

La información de tráfico se utiliza cuando se aplica todo lo siguiente (estas son las condiciones necesarias para recibir el campo en la respuesta de la Matriz de distancia): duration_in_traffic

• El parámetro de travelmode esdriving o no especificado (driving es el travel mode predeterminado).
• La solicitud incluye un parámetro válido . Se puede establecer en la hora actual o en algún momento en el futuro. No puede estar en el pasado. departure_timedeparture_time

Opcionalmente, puede incluir el traffic_model parámetro en su solicitud para especificar las suposiciones que se utilizarán al calcular el tiempo en el tráfico.

La siguiente URL inicia una solicitud de Matriz de distancia para las distancias de conducción entre Boston, MA o Charlestown, MA, y Lexington, MA y Concord, MA. La solicitud incluye una hora de salida, cumpliendo con todos los requisitos para devolver el duration_in_trafficcampo en la respuesta de Matriz de Distancia.

Restricciones

Se pueden calcular distancias que se adhieran a ciertas restricciones. Las restricciones se indican mediante el uso del parámetro avoid y un argumento a ese parámetro que indica la restricción que se debe evitar. Se admiten las siguientes restricciones:

• avoid=tolls
• avoid=highways
• avoid=ferries
• avoid=indoor

Sistemas unitarios

Los resultados de la matriz de distancia  contienen los campos text dentro de distance para indicar la distancia de la ruta calculada. El sistema de unidades a utilizar se puede especificar:

• units=metric (predeterminado) devuelve distancias en kilómetros y metros.
• units=imperial devuelve distancias en millas y pies.

Respuestas de la matriz de distancia

Las respuestas a las consultas de la API de Distance Matrix se devuelven en el formato indicado por el indicador output dentro de la ruta de la solicitud de URL.

A continuación, se muestran dos ejemplos de solicitudes HTTP, que solicitan la distancia y la duración desde Vancouver, BC, Canadá y desde Seattle, WA, EE. UU., A San Francisco, CA, EE. UU. Y Victoria, BC, Canadá.

Esta solicitud demuestra el uso de la bandera output JSON :

Esta solicitud demuestra el uso de la bandera output XML :

Esta solicitud devolverá cuatro elementos: dos orígenes por dos destinos:

Los resultados se devuelven en filas, cada fila contiene un origen emparejado con cada destino.

Puede probar esto ingresando la URL en su navegador web (asegúrese de reemplazarla YOUR_API_KEYcon su clave API real ).

Elementos de respuesta de la matriz de distancia

Las respuestas de la matriz de distancia contienen los siguientes elementos raíz:

• status: contiene metadatos en la solicitud. Consulte los códigos de estado a continuación.
• origin_addresses: contiene una matriz de direcciones devuelta por la API de su solicitud original. Estos son formateados por el geocodificador y localizados de acuerdo con el parámetro language pasado con la solicitud.
• destination_addresses: contiene una matriz de direcciones devuelta por la API de su solicitud original. Al igual que con origin_addresses, estos están localizados si corresponde.
• rows: contiene una matriz de elements, que a su vez contienen cada una elemento status, duration y distance.

Códigos de estado

Los campos status dentro del objeto de respuesta contienen el estado de la solicitud y pueden contener información de depuración útil. La API de Distance Matrix devuelve un campo de estado de nivel superior, con información sobre la solicitud en general, así como un campo de estado para cada campo de elemento, con información sobre ese emparejamiento de origen-destino en particular.

Códigos de estado de nivel superior

• OKindica que la respuesta contiene un válido result.
• INVALID_REQUEST indica que la solicitud proporcionada no era válida.
• MAX_ELEMENTS_EXCEEDEDindica que el producto de orígenes y destinos supera el límite por consulta .
• MAX_DIMENSIONS_EXCEEDEDindica que el número de orígenes o destinos supera el límite por consulta .
• OVER_DAILY_LIMIT indica cualquiera de los siguientes:
  • Falta la clave API o no es válida.
  • No se ha habilitado la facturación en su cuenta.
  • Se superó un límite de uso autoimpuesto.
  • El método de pago proporcionado ya no es válido (por ejemplo, una tarjeta de crédito ha caducado).

  Consulte las preguntas frecuentes de Maps para saber cómo solucionar este problema.

• OVER_QUERY_LIMIT indica que el servicio ha recibido demasiadas solicitudes de su aplicación dentro del período de tiempo permitido.
• REQUEST_DENIED indica que el servicio denegó el uso del servicio Distance Matrix por parte de su aplicación.
• UNKNOWN_ERRORindica que no se pudo procesar una solicitud de matriz de distancia debido a un error del servidor. La solicitud puede tener éxito si vuelve a intentarlo.

Códigos de estado a nivel de elemento

• OKindica que la respuesta contiene un result válido .
• NOT_FOUND indica que el origen y/o destino de este emparejamiento no se pudo geocodificar.
• ZERO_RESULTS indica que no se pudo encontrar ninguna ruta entre el origen y el destino.
• MAX_ROUTE_LENGTH_EXCEEDED indica que la ruta solicitada es demasiado larga y no se puede procesar.

Error de mensajes

Cuando el código de estado de nivel superior es distinto de OK, puede haber un campo error_message adicional dentro del objeto de respuesta Matriz de distancia. Este campo contiene información más detallada sobre las razones detrás del código de estado dado.

Filas

Cuando la API de Distance Matrix devuelve resultados, los coloca dentro de una rowsmatriz JSON . Incluso si no se devuelven resultados (como cuando los orígenes y / o destinos no existen), todavía devuelve una matriz vacía. Las respuestas XML constan de cero o más <row>elementos.

Las filas se ordenan según los valores del parámetro origin de la solicitud. Cada fila corresponde a un origen, y cada element dentro de esa fila corresponde a un emparejamiento del origen con un valor destination.

Cada matrizrow contiene una o más entradas element, que a su vez contienen la información sobre un único emparejamiento origen-destino.

Elementos

La información sobre cada emparejamiento origen-destino se devuelve en una entrada element. Un element contiene los siguientes campos:

• status: Consulte Códigos de estado para obtener una lista de posibles códigos de estado.
• duration: El tiempo que se tarda en recorrer esta ruta, expresado en segundos (el valuecampo) y como text. La representación textual se localiza según el languageparámetro de la consulta .

• duration_in_traffic: El tiempo que se tarda en recorrer esta ruta, según las condiciones de tráfico actuales e históricas. Consulte el parámetro traffic_model de solicitud para conocer las opciones que puede utilizar para solicitar que el valor devuelto sea optimista, pesimista o una estimación más aproximada. La duración se expresa en segundos (el campo value) y como text. La representación textual se localiza según el parámetro language de la consulta. La duración del tráfico se devuelve solo si se cumplen todas las condiciones siguientes:

  • La solicitud incluye un parámetro departure_time.
  • La solicitud incluye una clave de API válida o una identificación y firma de cliente del Plan Premium de Google Maps Platform válidas.
  • Las condiciones del tráfico están disponibles para la ruta solicitada.
  • El parámetro mode está configurado en driving.
• distance: La distancia total de esta ruta, expresada en metros ( value) y como text. El valor textual usa el sistema de unidades especificado con el parámetro unit de la solicitud original, o la región de origen.
• fare: Si está presente, contiene la tarifa total (es decir, el costo total del boleto) en esta ruta. Esta propiedad solo se devuelve para solicitudes de tránsito y solo para proveedores de tránsito donde la información de tarifas está disponible. La información incluye:
  • currency: Un código de moneda ISO 4217 que indica la moneda en la que se expresa el importe.
  • value: El monto total de la tarifa, en la moneda especificada anteriormente.
  • text: El importe total de la tarifa, formateado en el idioma solicitado.

A continuación se muestra un ejemplo de element que contiene información de tarifa:

{
  "status": "OK",
  "duration": {
    "value": 340110,
    "text": "3 jours 22 heures"
  },
  "distance": {
    "value": 1734542,
    "text": "1 735 km"
  }
  "fare" : {
    "currency" : "USD",
    "value" : 6,
    "text" : "$6.00"
  },
}

El parámetro sensor

La API de Google Maps anteriormente requería que incluyera el parámetro sensor para indicar si su aplicación usaba un sensor para determinar la ubicación del usuario. Este parámetro ya no es necesario.