Cómo obtener instrucciones sobre cómo llegar a través de la API de Directions (heredada)

Desarrolladores del Espacio Económico Europeo (EEE)

Este producto se encuentra en estado heredado. A partir de octubre de 2026, ya no se podrá habilitar la API de Directions (heredada) para los proyectos nuevos de Google Cloud. Los proyectos existentes siguen siendo totalmente compatibles. Para obtener funciones nuevas y un mejor rendimiento, migra a la API de Routes.

Para los cálculos de instrucciones sobre cómo llegar que responden en tiempo real a la entrada del usuario (por ejemplo, dentro de un elemento de la interfaz de usuario), puedes usar la API de Directions (heredada) o, si usas la API de Maps JavaScript, puedes usar el servicio de Directions. Para el uso del servidor, puedes utilizar los clientes de Java, Python, Go y Node.js para los servicios de Google Maps.

Con la API de Directions (heredada), puedes hacer lo siguiente:

  • Busca instrucciones sobre cómo llegar para varios medios de transporte, como transporte público, automóvil, a pie o en bicicleta.
  • Mostrar indicaciones en varias partes usando una serie de waypoints.
  • Especifica los orígenes, los destinos y los puntos de referencia como cadenas de texto (es decir, "Chicago, IL" o "Darwin, NT, Australia"), como IDs de lugar o como coordenadas de latitud y longitud.

La API devuelve las rutas más eficientes cuando calcula las instrucciones sobre cómo llegar. La duración del viaje es el factor principal que se optimiza, pero la API también puede tener en cuenta otros factores, como la distancia, la cantidad de giros y muchos más, para decidir cuál es la ruta más eficiente.

Antes de comenzar

Antes de comenzar a usar la API de Directions (heredada), debes tener un proyecto con una cuenta de facturación y la API de Directions (heredada) habilitada. Si deseas obtener más información, consulta el artículo sobre cómo configurar tu proyecto en la consola de Cloud.

Compila tus solicitudes a la API de Directions (heredada)

Una solicitud a la API de Directions (heredada) adopta el siguiente formato:

https://maps.googleapis.com/maps/api/directions/outputFormat?parameters

donde outputFormat puede ser cualquiera de los siguientes valores:

  • json (recomendado) indica el resultado en notación de objetos de JavaScript (JSON).
  • xml indica que el resultado es XML.

Nota: Las URLs deben estar codificadas correctamente para ser válidas y tienen un límite de 16,384 caracteres en todos los servicios web. Ten en cuenta este límite cuando construyas tus URLs.

Tal como es práctica estándar para las URLs, todos los parámetros se separan usando el signo et (&). Todos los caracteres reservados (por ejemplo, el signo más "+") deben estar codificados para URL. A continuación, se proporciona una lista de los parámetros y sus posibles valores.

Parámetros obligatorios

  • destino

    Es el ID de lugar, la dirección o el valor textual de latitud y longitud para el que deseas calcular las instrucciones sobre cómo llegar. Las opciones para el parámetro de destino son las mismas que para el parámetro de origen.

  • origin

    Es el ID de lugar, la dirección o el valor textual de latitud y longitud desde donde deseas calcular las rutas.

    • Los IDs de lugar deben tener el prefijo place_id:. Puedes recuperar los IDs de lugar de las APIs de Geocoding y Places (incluido Place Autocomplete). Para ver un ejemplo que use IDs de lugar de Place Autocomplete, consulta el artículo Place Autocomplete y Directions. Para obtener más información sobre los IDs de lugar, consulta la descripción general de los IDs de lugar. 

      origin=place_id:ChIJ3S-JXmauEmsRUcIaWtf4MzE

    • Si pasas una dirección, el servicio de Directions geocodifica la cadena y la convierte en una coordenada de latitud y longitud para calcular las instrucciones sobre cómo llegar. Esta coordenada puede ser diferente de la que devuelve la API de Geocoding, por ejemplo, la entrada de un edificio en lugar de su centro. 

      origin=24+Sussex+Drive+Ottawa+ON

      Se recomienda usar IDs de lugar en lugar de direcciones o coordenadas de latitud y longitud. El uso de coordenadas siempre dará como resultado que el punto se ajuste a la ruta más cercana a esas coordenadas, que puede no ser un punto de acceso a la propiedad o incluso una ruta que lleve de forma rápida o segura al destino.

    • Si pasas coordenadas, el punto se ajustará a la ruta más cercana. Se recomienda pasar un ID de lugar. Si pasas coordenadas, asegúrate de que no haya espacio entre los valores de latitud y longitud. 

      origin=41.43206,-81.38992

    • Los Plus Codes deben tener el formato de un código global o un código compuesto. Asigna formato a los Plus Codes como se muestra aquí (los signos más se escapan en la URL como %2B y los espacios se escapan en la URL como %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).
      • 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.UU. es CWC8%2BR9%20Mountain%20View%20CA%20USA).
    Nota: Para mayor eficiencia y precisión, usa los IDs de lugar siempre que sea posible. Estos IDs son explícitos de forma única, como un par de valores de latitud y longitud, y proporcionan beneficios de geocodificación para el enrutamiento, como puntos de acceso y variables de tráfico. A diferencia de una dirección, los IDs no requieren que el servicio realice una búsqueda o una solicitud intermedia de Place Details; por lo tanto, el rendimiento es mejor.

Parámetros opcionales

  • Alternativas

    Si se establece en true, especifica que el servicio Directions puede proporcionar más de una ruta alternativa en la respuesta. Ten en cuenta que proporcionar rutas alternativas puede aumentar el tiempo de respuesta del servidor. Esta opción solo está disponible para las solicitudes sin puntos de referencia intermedios. Para obtener más información, consulta la guía de puntos de referencia.

  • arrival_time

    Especifica la hora de llegada preferida para las rutas en transporte público, en segundos desde la medianoche del 1 de enero de 1970 (UTC). Puedes especificar departure_time o arrival_time, pero no ambos. Ten en cuenta que arrival_time debe especificarse como un número entero.

  • evitar

    Indica que las rutas calculadas deben evitar las características indicadas. Este parámetro admite los siguientes argumentos:

    • tolls indica que la ruta calculada debe evitar las rutas o los puentes con peaje.
    • highways indica que la ruta calculada debe evitar las autopistas.
    • ferries indica que la ruta calculada debe evitar los transbordadores.
    • indoor indica que, para la ruta calculada, deben evitarse los pasos en interiores en las instrucciones sobre cómo llegar a pie y en transporte público.

    Puedes solicitar una ruta que evite cualquier combinación de peajes, autopistas y transbordadores pasando varias restricciones al parámetro avoid. Por ejemplo: 

    avoid=tolls|highways|ferries.

  • departure_time

    Especifica la hora de salida preferida. Puedes especificar la hora como un número entero en segundos desde la medianoche del 1 de enero de 1970 (UTC). Si se especifica un departure_time posterior al 31 de diciembre de 9999 a las 23:59:59.999999999Z, la API recurrirá al departure_time del 31 de diciembre de 9999 a las 23:59:59.999999999Z. Como alternativa, puedes especificar un valor de now, que establece la hora de salida en la hora actual (con una precisión de un segundo). La hora de partida se puede especificar en dos casos:

    • Para las solicitudes en las que el medio de transporte es público, puedes especificar de manera opcional departure_time o arrival_time. Si no se especifica ninguna hora, el valor predeterminado de departure_time es ahora (es decir, la hora de salida se establece de forma predeterminada en la hora actual).
    • En las solicitudes en las que el medio de transporte es en automóvil, puedes especificar el parámetro departure_time para recibir una ruta y una duración del viaje (campo de respuesta: duration_in_traffic) que tengan en cuenta las condiciones de tráfico. departure_time se debe establecer en la hora actual o en un horario futuro. No puede ser un horario 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 rutas y las condiciones de tráfico promedio independientemente del tiempo. Los resultados de una solicitud determinada pueden variar con el tiempo debido a cambios en la red de rutas, actualizaciones de las condiciones de tráfico promedio y la naturaleza distribuida del servicio. Los resultados también pueden variar entre rutas muy similares en cualquier momento o con cualquier frecuencia.
    Nota: Las solicitudes de matriz de distancia que especifican departure_time cuando mode=driving se limitan a un máximo de 100 elementos por solicitud. La cantidad de orígenes multiplicada por la cantidad de destinos define la cantidad de elementos.

  • idioma

    Es el idioma en el que se devolverán los resultados. Ten en cuenta que esto solo se aplica a las direcciones geocodificadas en start_address y end_address, el texto localizado en los campos distance y duration (en tramos y pasos) y la descripción de las maniobras en html_instructions, pero no a los nombres y las direcciones en html_instructions, que tienen el formato de su idioma y escritura locales.

    • Consulta la lista de idiomas disponibles. Google suele actualizar los idiomas admitidos, por lo que es posible que esta lista no sea exhaustiva.
    • Si no se proporciona language, la API intenta usar el idioma preferido, como se especifica en el encabezado Accept-Language.
    • 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 direcciones en el idioma local, transliteradas a una escritura legible por el usuario si es necesario, respetando el idioma preferido. Todas las demás direcciones se devuelven en el idioma preferido. Todos los componentes de la dirección se devuelven en el mismo idioma, que se elige a partir del primer componente.
    • Si un nombre no está disponible en el idioma preferido, la API usa la coincidencia más cercana.
    • El idioma preferido tiene una pequeña influencia en el conjunto de resultados que la API elige mostrar y en el orden en que se muestran. El geocodificador interpreta las abreviaturas de manera diferente según el idioma, como las abreviaturas de los tipos de calles 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.

  • Standard

    Para el cálculo de distancias y rutas, puedes especificar el medio de transporte que se usará. De forma predeterminada, se usa el modo driving. De forma predeterminada, las rutas se calculan como rutas en auto. Se admiten los siguientes medios de transporte:

    • driving (predeterminado) indica la ruta en auto o la distancia estándar por la red de rutas.
    • walking solicita instrucciones sobre cómo llegar a un lugar a pie o la distancia a través de rutas peatonales y veredas (cuando estén disponibles).
    • bicycling solicita la ruta en bicicleta o la distancia por ciclovías y calles preferidas (cuando estén disponibles).
    • transit solicita instrucciones sobre cómo llegar a un lugar o la distancia por medio de rutas de transporte público (cuando estén disponibles). Si configuras el modo como transporte público, puedes especificar de manera opcional un valor para departure_time o arrival_time. Si no se especifica ninguna hora, el valor predeterminado de departure_time es ahora (es decir, la hora de salida predeterminada es la hora actual). También puedes incluir un transit_mode o un transit_routing_preference de forma opcional. Los viajes en transporte público están disponibles para un máximo de 7 días en el pasado o hasta 100 días en el futuro, según la disponibilidad de la información de transporte público que proporcionen los proveedores de datos. Los horarios del transporte público cambian con frecuencia, los viajes disponibles pueden cambiar con el tiempo y no se garantiza que se proporcionen resultados coherentes para las predicciones con mucha anticipación.
    Nota: Es posible que las instrucciones sobre cómo llegar a pie y las rutas en bicicleta no incluyan rutas peatonales o ciclovías claras, por lo que estas instrucciones mostrarán advertencias en el resultado que se devuelva, que debes mostrar al usuario.

  • región

    Es el código de región, especificado como un valor de ccTLD ("dominio de nivel superior") de dos caracteres. La mayoría de los códigos ccTLD son idénticos a los códigos ISO 3166-1, con algunas excepciones notables. Por ejemplo, el ccTLD del Reino Unido es "uk" (.co.uk), mientras que su código ISO 3166-1 es "gb" (técnicamente para la entidad "Reino Unido de Gran Bretaña e Irlanda del Norte").

  • traffic_model

    Especifica las suposiciones que se usarán cuando se calcule el tiempo en el tráfico. Este parámetro de configuración afecta el valor que se muestra en el campo duration_in_traffic de la respuesta, que contiene el tiempo previsto en el tráfico según los promedios históricos. El parámetro traffic_model solo se puede especificar para las rutas en auto en las que la solicitud incluye un departure_time. Los valores disponibles para este parámetro son los siguientes:

    • best_guess (predeterminado) indica que el valor de duration_in_traffic que se muestra debe ser la mejor estimación de la duración del viaje según lo que se conoce sobre las condiciones de tráfico histórico y tráfico en tiempo real. Cuanto más se acerque el valor de departure_time al momento presente, más importancia cobrará el tráfico en tiempo real.
    • pessimistic indica que el valor de duration_in_traffic que se muestra debe ser mayor que la duración del viaje real la mayoría de los días; no obstante, es posible que se supere este valor determinados días en que las condiciones de tráfico son particularmente desfavorables.
    • optimistic indica que el valor de duration_in_traffic que se muestra debe ser menor que la duración del viaje real en la mayoría de los días, aunque puede llegar a ser aún más corto en determinados días en que las condiciones de tráfico sean particularmente buenas.

    El valor predeterminado de best_guess proporcionará las predicciones más útiles para la gran mayoría de los casos de uso. Es posible que la predicción de la duración del viaje de best_guess sea más corta que la de optimistic o, por el contrario, más larga que la de pessimistic, debido a la forma en que el modelo predictivo de best_guess integra la información del tráfico en tiempo real.

  • transit_mode

    Especifica uno o más medios de transporte público preferidos. Este parámetro solo se puede especificar para las rutas en transporte público. El parámetro admite los siguientes argumentos:

    • bus indica que, para la ruta calculada, debe priorizarse el transporte en autobús.
    • subway indica que, para la ruta calculada, debe priorizarse el transporte en metro.
    • train indica que, para la ruta calculada, debe priorizarse el transporte en tren.
    • tram indica que, para la ruta calculada, debe priorizarse el transporte en tranvía y tren ligero.
    • rail indica que, para la ruta calculada, debe priorizarse el transporte en tren, tranvía, tren ligero y metro. Esto equivale a transit_mode=train|tram|subway.

  • transit_routing_preference

    Especifica las preferencias para las rutas en transporte público. Con este parámetro, puedes personalizar las opciones que se muestran en lugar de aceptar la mejor ruta predeterminada que selecciona la API. Este parámetro solo se puede especificar para las rutas en transporte público. Este parámetro admite los siguientes argumentos:

    • less_walking indica que, para la ruta calculada, debe priorizarse una distancia limitada de recorrido a pie.
    • fewer_transfers indica que, para la ruta calculada, debe priorizarse una cantidad limitada de transbordos.

  • unidades

    Especifica el sistema de unidades que se usará cuando se muestren los resultados.

    Los resultados de las instrucciones sobre cómo llegar contienen texto dentro de los campos de distancia que se pueden mostrar al usuario para indicar la distancia de un "paso" en particular de la ruta. De forma predeterminada, este texto usa el sistema de unidades del país o la región de origen.

    Por ejemplo, para una ruta de "Chicago, IL" a "Toronto, ONT" los resultados se mostrarán en millas, mientras que para la ruta inversa se mostrarán en kilómetros. Para anular este sistema de unidades, configura una unidad explícitamente en el parámetro units de la solicitud con uno de los siguientes valores:

    • metric especifica el uso del sistema métrico. Las distancias textuales se devuelven en kilómetros y metros.
    • imperial especifica el uso del sistema imperial (inglés). Las distancias textuales se devuelven en millas y pies.
    Nota: Esta configuración del sistema de unidades solo afecta el texto que se muestra en los campos de distancia. Los campos de distancia también contienen valores que siempre se expresan en metros.

  • puntos de referencia

    Advertencia: Las solicitudes que usan más de 10 puntos de referencia (entre 11 y 25) o que implican la optimización de puntos de referencia se facturan con una tarifa más alta. Obtén más información sobre la facturación de los productos de Google Maps Platform.

    Especifica un array de ubicaciones intermedias para incluir a lo largo de la ruta entre los puntos de origen y destino como ubicaciones de paso o de parada. Los puntos de referencia modifican una ruta para que pase por las ubicaciones especificadas. La API admite puntos de referencia para los siguientes medios de transporte: en automóvil, a pie y en bicicleta, pero no en transporte público. Puedes proporcionar una o más ubicaciones separadas por el carácter de barra vertical (| o %7C), en forma de ID de lugar, dirección o coordenadas de latitud y longitud. De forma predeterminada, el servicio Directions calcula una ruta con los puntos de referencia en el orden en que se proporcionan. La prioridad para analizar el valor del punto de referencia es el ID de lugar, las coordenadas de latitud y longitud, y, luego, la dirección.

    • Si pasas un ID de lugar, debes agregarle el prefijo place_id:. Puedes recuperar los IDs de lugar de la API de Geocoding y la API de Places (incluido Place Autocomplete). Para ver un ejemplo que use IDs de lugar de Place Autocomplete, consulta el artículo Place Autocomplete y Directions. Para obtener más información sobre los IDs de lugar, consulta la descripción general de los IDs de lugar.
      Para mayor eficiencia y precisión, usa IDs de lugar siempre que sea posible. Estos IDs son explícitos de forma única, como un par de valores de latitud y longitud, y proporcionan beneficios de geocodificación para el enrutamiento, como puntos de acceso y variables de tráfico. A diferencia de una dirección, los IDs no requieren que el servicio realice una búsqueda o una solicitud intermedia de Place Details; por lo tanto, el rendimiento es mejor.
    • Si pasas coordenadas de latitud y longitud, los valores se envían directamente al servidor de frontend para calcular las instrucciones sobre cómo llegar sin geocodificación. Los puntos se ajustan a las rutas y es posible que no proporcionen la precisión que necesita tu app. Usa coordenadas cuando tengas la certeza de que los valores especifican los puntos que tu app necesita para la ruta, sin tener en cuenta los posibles puntos de acceso ni los detalles adicionales de geocodificación. Asegúrate de que los valores de latitud y longitud estén separados por una coma (%2C) y no por un espacio (%20).
    • Si pasas una dirección, el servicio de Directions geocodificará la cadena y la convertirá en coordenadas de latitud y longitud para calcular las instrucciones sobre cómo llegar. Si el valor de la dirección es ambiguo, puede provocar una búsqueda para eliminar la ambigüedad de direcciones similares. Por ejemplo, "1st Street" podría ser un valor completo o parcial para "1st street NE" o "1st St SE". Este resultado puede ser diferente del que devuelve la API de Geocoding. Puedes evitar posibles interpretaciones erróneas con los IDs de lugar.
    • Como alternativa, puedes proporcionar un conjunto de puntos codificados con el algoritmo de polilínea codificada. Verás que un conjunto codificado es útil para una gran cantidad de puntos de referencia, ya que la URL es mucho más corta. Todos los servicios web tienen un límite de 16,384 caracteres para las URLs.
      • Las polilíneas codificadas deben tener el prefijo enc: y estar seguidas de dos puntos (:). Por ejemplo: waypoints=enc:gfo}EtohhU:.
      • También puedes incluir varias polilíneas codificadas, separadas por el carácter de barra vertical (|). Por ejemplo, waypoints=via:enc:wc~oAwquwMdlTxiKtqLyiK:|enc:c~vnAamswMvlTor@tjGi}L:| via:enc:udymA{~bxM:.
    Influye en las rutas con puntos de parada y de paso

    Para cada punto de referencia de la solicitud, la respuesta de instrucciones sobre cómo llegar agrega una entrada al array legs para proporcionar los detalles de las paradas en ese tramo del viaje.

    Si deseas influir en la ruta con puntos de referencia sin agregar una parada, agrega el prefijo via: al punto de referencia. Los puntos de referencia con el prefijo via: no agregarán una entrada al array legs, pero dirigirán el viaje a través del punto de referencia.

    La siguiente URL modifica la solicitud anterior para que el viaje se enrute a través de Lexington sin detenerse: 

    https://maps.googleapis.com/maps/api/directions/json?
origin=Boston,MA&destination=Concord,MA
&waypoints=Charlestown,MA|via:Lexington,MA

    El prefijo via: es más eficaz cuando se crean rutas en respuesta a que el usuario arrastra los puntos de referencia en el mapa. Esto permite que el usuario vea cómo se verá la ruta final en tiempo real y ayuda a garantizar que los puntos de referencia se coloquen en ubicaciones a las que pueda acceder la API de Directions.

    Precaución: Si usas el prefijo via: para evitar las paradas, las instrucciones sobre cómo llegar serán estrictas en su interpretación del punto de referencia. Esta interpretación puede provocar desvíos significativos en la ruta o ZERO_RESULTS en el código de estado de la respuesta si la API de Directions no puede crear instrucciones sobre cómo llegar a través de ese punto.
    Optimiza tus waypoints

    De forma predeterminada, el servicio Directions calcula una ruta a través de los puntos de referencia proporcionados en su respectivo orden. De manera opcional, puedes pasar optimize:true como el primer argumento dentro del parámetro waypoints para permitir que el servicio Directions optimice la ruta proporcionada reordenando los puntos de referencia de una forma más eficiente. (Esta optimización es una aplicación del problema del viajante). La duración del viaje es el factor principal que se optimiza, pero también se pueden considerar otros factores, como la distancia, la cantidad de giros y muchos más, para decidir cuál es la ruta más eficiente. Todos los puntos de referencia deben ser paradas para que el servicio Directions optimice la ruta.

    Si le indicas al servicio Directions que optimice el orden de los puntos de referencia, dicho orden se mostrará en el campo waypoint_order en el objeto routes. El campo waypoint_order devuelve valores basados en cero.

    En el siguiente ejemplo, se calcula un viaje por ruta desde Adelaida, Australia Meridional, hasta cada una de las principales regiones vinícolas de Australia Meridional con la optimización de rutas. 

    https://maps.googleapis.com/maps/api/directions/json?
origin=Adelaide,SA&destination=Adelaide,SA
&waypoints=optimize:true|Barossa+Valley,SA|Clare,SA|Connawarra,SA|McLaren+Vale,SA

    La inspección de la ruta calculada indicará que el cálculo usa puntos de referencia en el siguiente orden: 

    "waypoint_order": [ 3, 2, 0, 1 ]
    Precaución: Las solicitudes que usan la optimización de puntos de referencia se facturan con una tarifa más alta. Obtén más información sobre cómo se facturan los productos de Google Maps Platform.

¿Qué sigue?

Ejemplos de instrucciones sobre cómo llegar

Respuestas de Directions