Introducción

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

Nota: Este servicio no devuelve información detallada de la ruta. La información de ruta se puede obtener pasando el origen y el destino únicos deseados a la API de Direcciones.

Antes de comenzar

Este documento está destinado a desarrolladores que desean 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 la información de uso y facturación de la API (necesita 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 uno de los siguientes valores:

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

Nota: Las URL deben estar codificadas correctamente para ser válidas y están limitadas a 8192 caracteres para todos los servicios web. Ten en cuenta este límite al construir tus URL. Tenga en cuenta que los diferentes navegadores, servidores proxy y servidores también pueden tener diferentes límites de caracteres de URL.

La seguridad HTTPS o HTTP

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

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

Parámetros de solicitud

Se requieren ciertos parámetros, mientras que otros son opcionales. Como es habitual en las URL, todos los parámetros se separan utilizando el carácter ampersand (&). Todos los caracteres reservados (por ejemplo, el signo más «+») deben estar codificados en URL.La lista de parámetros y sus posibles valores se enumeran a continuación.

Parámetros requeridos

• origins div — – 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 tubería (|), 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 Google Maps Platform Premium. Puede recuperar los ID de lugar de la API de geocodificación y la API de Lugares (incluido el autocompletado de lugares). Para ver un ejemplo de uso de ID de lugar de Autocompletar Lugares, consulte Autocompletar lugares y Direcciones. Para obtener más información sobre los ID de lugar, consulte la descripción general de ID de lugar.
  • 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 geocodificación, por ejemplo, una entrada de edificio en lugar de su centro.

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

    Nota: se prefiere usar identificadores de lugar a usar direcciones o coordenadas de latitud/longitud. El uso de coordenadas siempre resultará en que el punto se enganche a la carretera más cercana a esas coordenadas, que puede no ser un punto de acceso a la propiedad, o incluso una carretera que conduzca de forma rápida o segura al destino.
  • 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 existe 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 tienen escape de url a %2B y los espacios tienen escape de url a %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 largo con una ubicación explícita (CWC8+R9 Mountain View, CA, EE.UU. es CWC8%2BR9%20Mountain%20View%20CA%20USA).
  • Alternativamente, puede proporcionar un conjunto codificado de coordenadas utilizando el algoritmo de Polilínea Codificada. Esto es particularmente útil si tiene un gran número 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 de 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 tubería (|). Por ejemplo: origins=enc:wc~oAwquwMdlTxiKtqLyiK:|enc:c~vnAamswMvlTor@tjGi}L:|enc:udymA{~bxM:
• destinations — Una o más ubicaciones para utilizar como punto de terminar para el cálculo de distancia y 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 solicitud para fines de gestión de cuotas. Aprende a conseguir una llave. Nota

  : Los clientes del plan Premium de Google Maps Platform pueden usar una clave de API o un ID de cliente válido y una firma digital en sus solicitudes de Matriz de distancia. Obtenga más información sobre los parámetros de autenticación para los clientes del Plan Premium.

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

El siguiente ejemplo utiliza códigos plus para especificar las coordenadas de destino:

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

Parámetros opcionales

• mode(el valor predeterminado es driving): Especifica el modo de transporte que se utilizará al calcular la distancia. Los valores válidos y otros detalles de la solicitud se especifican en la sección Modos de viaje de este documento.
• language div — – El idioma en el que devolver los resultados.
  • Consulte la lista de idiomas admitidos. Google a menudo actualiza los idiomas admitidos, por lo que esta lista puede no ser exhaustiva.
  • Si no se proporciona language, la API intenta utilizar el idioma preferido especificado en el encabezado Accept-Language, o el idioma nativo del dominio desde el que se envía la solicitud.
  • La API hace todo lo posible para proporcionar una dirección que sea legible tanto para el usuario como para los locales. Para lograr ese objetivo, devuelve las direcciones en el idioma local, transliteradas a un guion legible por el usuario si es necesario, observando el idioma preferido. Todas las demás direcciones se devuelven en el idioma preferido. Todos los componentes de dirección se devuelven en el mismo idioma, que se elige del primer componente.
  • Si un nombre no está disponible en el idioma preferido, la API utiliza la coincidencia más cercana.
  • El idioma preferido tiene una pequeña influencia en el conjunto de resultados que la API elige devolver y en el orden en que se devuelven. El geocodificador interpreta las abreviaturas de manera diferente dependiendo del idioma, como las abreviaturas para los tipos de calle,o los sinónimos que pueden ser válidos en un idioma pero no en otro. Por ejemplo, utca y tér son sinónimos de calle en húngaro.
• region div — – El código de región, especificado como un valor de dos caracteres ccTLD (dominio de nivel superior de código de país). La mayoría de los códigos ccTLD son idénticos a los códigos ISO 3166-1, con algunas excepciones. Este parámetro solo influirá, no restringirá completamente, los resultados del geocodificador. Si existen resultados más relevantes fuera de la región especificada, pueden incluirse.
• avoid Introduce restricciones a la ruta. Los valores válidos se especifican en la sección Restricciones de este documento. Solo se puede especificar una restricción.
• units div — – Especifica el sistema de unidades que se utilizará al expresar la distancia como texto. Consulte la sección Sistemas de unidades de este documento para obtener más información.
• arrival_time div — – Especifica la hora de llegada deseada para las solicitudes de tránsito, en segundos desde la medianoche del 1 de enero de 1970 UTC. Puede especificar departure_time o arrival_time, pero no tanto. Tenga en cuenta que arrival_time debe especificarse como un entero.
• departure_time div — – La hora de salida deseada. Puede especificar la hora como un entero en segundos desde la medianoche del 1 de enero de 1970 UTC. Si se especifica un departure_time posterior a 9999-12-31T23:59:59.999999999 Z, la API retrocederá el departure_time a 9999-12-31T23:59:59.9999999999 Z. Alternativamente, puede especificar un valor de now, que establece la hora de salida a la hora actual (correcta al segundo más cercano). La hora de salida se puede especificar en dos casos:
  • Para solicitudes en las que el modo de viaje es de tránsito: Opcionalmente, puede especificar uno de departure_time o arrival_time. Si no se especifica ninguna hora, el valor predeterminado dedeparture_time es ahora (es decir, la hora de salida es la hora actual).
  • Para solicitudes en las que se está conduciendo el modo de viaje: Puede especificar el departure_time para recibir una ruta y una duración del viaje (campo de respuesta: duration_in_traffic) que tengan en cuenta las condiciones del tráfico. Esta opción solo está disponible si la solicitud contiene una clave de API válida o un ID de cliente y firma válidos del plan Premium de Google Maps Platform. El departure_time debe establecerse en la hora actual o en algún momento en el futuro. No puede estar en el pasado.

    Nota: Si no se especifica la hora de salida, la elección de la ruta y la duración se basan en la red de carreteras y en las condiciones de tráfico independientes del tiempo medio. Los resultados de una solicitud determinada pueden variar con el tiempo debido a cambios en la red de carreteras, condiciones de tráfico promedio actualizadas y la naturaleza distribuida del servicio. Los resultados también pueden variar entre rutas casi equivalentes en cualquier momento o frecuencia.

    Nota: Las solicitudes de matriz de distancia que especifican departure_time cuando mode=driving están limitadas a un máximo de 100 elementos por solicitud. El número de orígenes multiplicado por el número de destinos define el número de elementos.

• traffic_model(el valor predeterminado es best_guess): Especifica las suposiciones que se deben usar al calcular el tiempo en el tráfico. Esta configuración afecta al valor devuelto en el campo duration_in_traffic de la respuesta, que contiene el tiempo previsto en el tráfico en función de los promedios históricos. El parámetro traffic_model solo se puede especificar para solicitudes en las que el modo de viaje es driving, y en las que la solicitud incluye 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 el duration_in_traffic devuelto debe ser la mejor estimación del tiempo de viaje dado lo que se conoce sobre las condiciones de tráfico histórico y el tráfico en vivo. El tráfico en tiempo real se vuelve más importante cuanto más cerca está de departure_time.
  • pessimistic indica que el duration_in_traffic devuelto debe ser más largo 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.
  • optimistic indica que el duration_in_traffic devuelto debe ser más corto 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 preferidos de tránsito. Este parámetro solo se puede especificar para solicitudes en las que mode es 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 debe preferir viajar en metro.
  • train indica que la ruta calculada debe preferir viajar en tren.
  • tram indica que la ruta calculada debe preferir viajar en tranvía y tren ligero.
  • rail indica que la ruta calculada debe preferir viajar en tren, tranvía, tren ligero y metro. Esto es equivalente a transit_mode=train|tram|subway.
• transit_routing_preference div — – Especifica las preferencias para las 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 en las que mode es transit. El parámetro admite los siguientes argumentos:
  • less_walking indica que la ruta calculada debe preferir cantidades limitadas de caminata.
  • fewer_transfers indica que la ruta calculada debe preferir un número limitado de transferencias.

modos de transporte

Para el cálculo de distancias, usted puede especificar el transporte mode para usar. 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 senderos peatonales & aceras (donde esté disponible).
• bicycling solicita el cálculo de la distancia para andar en bicicleta a través de carriles para bicicletas & 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 de API o un ID de cliente del plan Google Maps Platform Premium. Si establece el modo de transit opcionalmente, se puede especificar un departure_time o un arrival_time. Si no se especifica ninguna hora, el valor predeterminado dedeparture_time es ahora (es decir, la hora de salida es la hora actual). También puede incluir opcionalmente un transit_mode y/o transit_routing_preference.

Información de tráfico

La información de tráfico se utiliza cuando se aplican todas las siguientes condiciones (estas son las condiciones requeridas para recibir el campo duration_in_traffic en la respuesta de la matriz de distancia):

• El parámetro travel mode es driving, o no está especificado (driving es el modo de viaje predeterminado).
• La solicitud incluye un parámetro válido departure_time. El departure_time se puede establecer en la hora actual o en algún momento en el futuro. No puede estar en el pasado.

Opcionalmente, puede incluir el parámetro traffic_model 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 distancias para distancias de conducción entre Boston, MA o Charlestown, MA, y Lexington, MA y Concord, MA. La solicitud incluye una hora de salida, que cumple con todos los requisitos para devolver el campo duration_in_traffic en la respuesta de la matriz de distancia.

Restricciones

Se pueden calcular distancias que cumplan con ciertas restricciones. Las restricciones se indican mediante el uso del parámetro avoid, y un argumento para ese parámetro que indica la restricción a evitar. Las restricciones siguientes son compatibles:

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

* Nota: la adición de restricciones no impide que las rutas que incluyen restricciones en función de los sesgos que el resultado más favorable de las rutas.

Sistemas de unidades

Los resultados de la matriz de distancia contienen campos textdentro de distance para indicar la distancia de la ruta calculada. El sistema de unidad a usar se puede especificar:

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

* Nota: esta configuración del sistema de unidad solo afecta a los campos text que se muestran dentro de distance. Los campos distance también contienen values que siempre se expresan en metros.

Respuestas de matriz de distancia

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

A continuación se muestran dos solicitudes HTTP de muestra, solicitando distancia y duración desde Vancouver, BC, Canadá y desde Seattle, WA, EE.UU., a San Francisco, CA, EE. UU. y a Victoria, BC, Canadá.

Esta solicitud se muestra usando la bandera JSON output :

Esta solicitud se muestra el uso del XML output marca:

Esta petición devolverá cuatro elementos – dos orígenes veces dos destinos:

los Resultados se devuelven en filas, cada fila contiene un origen vinculado con cada destino.

Puede probar esto introduciendo la URL en su navegador web (asegúrese de reemplazar YOUR_API_KEY con su clave de API real).

Seleccione las pestañas siguientes para ver las respuestas JSON y XML de ejemplo.

El resto de esta documentación utilizará sintaxis JSON.

Elementos de respuesta de matriz de distancia

Las respuestas de 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 que devuelve 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 que devuelve la API de su solicitud original. Al igual que con origin_addresses, estos se localizan si es apropiado.
• rows contiene un array de elements, que a su vez contienen cada una un statusduration y distance elemento.

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 Matriz de distancias 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 y destino en particular.

Códigos de estado de nivel superior

• OK indica que la respuesta contiene un resultválido.
• INVALID_REQUEST indica que la solicitud no es válida.
• MAX_ELEMENTS_EXCEEDED indica que el producto de los orígenes y destinos supera el límite por consulta.
• MAX_DIMENSIONS_EXCEEDED indica que el número de orígenes o destinos supera el límite por consulta.
• OVER_DAILY_LIMIT indica cualquiera de las siguientes cosas:
  • La clave de API falta o no es válida.
  • La facturación no se ha habilitado en su cuenta.
  • Se ha excedido 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 Mapas para aprender a solucionar esto.

• 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 de matriz de distancia por parte de su aplicación.
• UNKNOWN_ERROR indica que una solicitud de matriz de distancia no se pudo procesar 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.

Mensajes de error

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

Nota: No se garantiza que este campo esté siempre presente, y su contenido está sujeto a cambios.

Filas

Cuando la API de Matriz de distancias devuelve resultados, los coloca dentro de una matriz JSON rows. Incluso si no se devuelven resultados (por ejemplo, cuando los orígenes y/o destinos no existen), devuelve una matriz vacía. Las respuestas XML consisten en cero o más elementos <row>.Las filas

se ordenan de acuerdo con 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 de origen con un destination valor.

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

Elementos

La información sobre cada emparejamiento origen-destino se devuelve en una entrada element. An 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 campo value) y como text. La representación textual se localiza de acuerdo con el parámetro language de la consulta.

• duration_in_traffic: El tiempo que se tarda en recorrer esta ruta, en función de las condiciones de tráfico actuales e históricas. Consulte el parámetro de solicitud traffic_model para ver las opciones que puede usar para solicitar que el valor devuelto sea optimista, pesimista o una estimación de mejor estimación. La duración se expresa en segundos (el value campo) y como text. La representación textual se localiza de acuerdo con el parámetro language de la consulta. La duración en el tráfico se devuelve solo si todo lo siguiente es verdadero:

  • La solicitud incluye un parámetro departure_time.
  • La solicitud incluye una clave de API válida o un ID de cliente y firma válidos del plan Premium de Google Maps Platform.
  • Las condiciones de tráfico están disponibles para la ruta solicitada.
  • El parámetromode se establece en driving.
• distance: La distancia total de la ruta, expresada en metros (value) y text. El valor textual utiliza 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, los costos totales del boleto) en esta ruta. Este hotel solo se devuelve para solicitudes de transporte y solo para proveedores de transporte en los que se dispone de información sobre tarifas. La información incluye:
  • currency : Un código de moneda ISO 4217 que indica la moneda en la que se expresa la cantidad.
  • value: El importe 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 un element que contiene información de tarifas:

El parámetro sensor

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