Guía de migración de la API de Routes

Organiza tus páginas con colecciones Guarda y categoriza el contenido según tus preferencias.

Actualmente, Google Maps Platform admite la API de Directions y la API de Distance Matrix. Esta versión de la API de Routes contiene la versión optimizada para el rendimiento de la siguiente API de Directions y la API de Distance Matrix existentes:

  • Rutas de procesamiento: calcula las instrucciones sobre cómo llegar entre ubicaciones con datos de enrutamiento globales completos y tráfico en tiempo real.
  • Matriz de ruta de procesamiento: calcula la distancia y el tiempo de viaje para una lista de pares de origen y destino.

La API de Routes incluye muchas funciones nuevas, incluidas las siguientes:

  • Recorrido vehicular de dos ruedas
  • Cálculo de los peajes
  • Polilínea basada en el tráfico
  • Controles de calidad de polilínea
  • Controles de latencia de calidad
  • Rutas ecológicas
  • Transmisión de resultados (solo procesamiento de Matriz de ruta de Compute con gRPC)
  • Compatibilidad con gRPC

Para obtener más información sobre la API de Routes, consulta la descripción general del producto.

En esta guía, se describe cómo migrar tus apps existentes que usan la API de Directions y la API de Distance Matrix para usar la API de Routes.

Cambios de funcionalidad en la API de Routes

En un nivel alto, la API de Routes realiza los siguientes cambios en las API de Directions y de Distance Matrix:

  • Consolida las rutas de Compute y la Matriz de ruta de Compute en un solo servicio llamado API de Routes.

    Debes habilitar la API de Routes en la Consola de API para poder usar las rutas de Compute y Matrix Route de Compute. Actualmente, debes habilitar la API de Directions y la API de Distance Matrix como servicios independientes en la Consola de API.

    Para obtener más información, consulta Configuración en la Consola de API de Google.

  • La nueva API de Routes usa solicitudes HTTP POST

    En la API de Routes, pasas parámetros en el cuerpo de la solicitud o en los encabezados como parte de una solicitud HTTP POST. En cambio, con la API de Directions y de Distance Matrix, debes pasar los parámetros de URL mediante una solicitud HTTP GET.

    Para ver ejemplos, consulta:

  • La configuración de campo es obligatoria

    Cuando llamas a la API de Routes para calcular una ruta o una matriz de ruta, debes especificar qué campos quieres que se muestren en la respuesta. No hay una lista predeterminada de campos mostrados. Si omites esta lista, los métodos muestran un error.

    Especifica la lista de campos mediante la creación de una máscara de campo de respuesta. Luego, debes pasar la máscara del campo de respuesta a cada método mediante el parámetro de URL $fields o fields, o mediante el encabezado HTTP/gRPC X-Goog-FieldMask.

    El enmascaramiento de campos es una buena práctica de diseño para garantizar que no solicites datos innecesarios, ya que ayuda a evitar tiempos de procesamiento y cargos de facturación innecesarios.

    Para obtener más información, consulta Elige los campos que se mostrarán.

  • Nuevos límites de solicitud para la matriz de rutas de Compute

    La API de Distance Matrix aplicó los siguientes límites de solicitudes:

    • Un máximo de 25 orígenes o 25 destinos por solicitud.
    • 100 elementos como máximo (cantidad de orígenes × cantidad de destinos) por solicitud del servidor

    La Matriz de ruta de Compute aplica los siguientes límites de solicitud:

    • La cantidad de elementos no puede ser superior a 625.

    • Si especificas TRAFFIC_AWARE_OPTIMAL, la cantidad de elementos no puede superar los 100. Para obtener más información sobre TRAFFIC_AWARE_OPTIMAL, consulta Cómo configurar la calidad frente a la latencia.

    • La cantidad máxima de waypoints (orígenes + destinos) que puedes especificar mediante un ID de lugar es 50.

  • Nuevas opciones para configurar la calidad frente a la latencia

    La API de Routes admite tres preferencias de enrutamiento que puedes usar para configurar de forma explícita la calidad de la ruta en comparación con la latencia de respuesta:

    • TRAFFIC_UNAWARE (predeterminado): usa los datos de tráfico promedio independiente del tiempo, no los datos de tráfico en vivo, para calcular la ruta, lo que da como resultado la menor latencia de respuesta. Esta configuración equivale a cuando el tráfico no se usa en las API de Directions y de Distance Matrix.

    • TRAFFIC_AWARE: Calidad del tráfico en vivo optimizada para el rendimiento con latencia reducida. Esta configuración es nueva para la API de Routes y no tiene un equivalente en la API de Directions y de Distance Matrix.

      A diferencia de TRAFFIC_AWARE_OPTIMAL, se aplican algunas optimizaciones para reducir la latencia de manera significativa.

    • TRAFFIC_AWARE_OPTIMAL: datos de tráfico integrales y de alta calidad sin aplicar la mayoría de las optimizaciones de rendimiento. Esta configuración produce la latencia más alta y es equivalente a la configuración de departure_time en la API de Directions y de Distance Matrix.

      La preferencia de enrutamiento TRAFFIC_AWARE_OPTIMAL es equivalente al modo que usan maps.google.com y la app para dispositivos móviles de Google Maps.

    En la API de Directions y de Distance Matrix, solo proporcionamos el equivalente a las opciones TRAFFIC_AWARE_OPTIMAL y TRAFFIC_UNAWARE. Estas opciones se configuraron de forma implícita en función de si configuraste departure_time.

    En la siguiente tabla, se comparan las opciones de la API de Directions API actual y de la API de Distance Matrix con las opciones de la API de rutas:

    Mode Actual API de Routes Notas
    Sin tráfico en tiempo real No se configuró la propiedad departure_time TRAFFIC_UNAWARE La latencia más rápida de los tres modos.
    Se aplicaron las condiciones de tráfico en vivo Sin equivalente TRAFFIC_AWARE

    Se agregó un modo nuevo mediante la API de Routes. Proporciona una latencia un poco mayor que TRAFFIC_UNAWARE, con un pequeño costo de calidad de ETA.

    Tiene una latencia mucho menor que TRAFFIC_AWARE_OPTIMAL.
    Se aplicaron datos de tráfico en vivo integrales y de alta calidad Se estableció la propiedad departure_time TRAFFIC_AWARE_OPTIMAL

    Equivalente al modo que usan maps.google.com y la app para dispositivos móviles de Google Maps.

    En el caso de la matriz de rutas de Compute, la cantidad de elementos en una solicitud (cantidad de orígenes × destinos) no puede ser superior a 100.

    La API de Routes también modifica la forma en que se configura la propiedad de respuesta duration, y modifica las propiedades que se muestran en la respuesta actual de la API de Directions y de la API de Distance Matrix, como se muestra en la siguiente tabla:

    Tipo de hora de llegada estimada Actual API de Routes
    El tráfico no reconoce el ETA independiente del tiempo.

    Corresponde a que departure_time no se haya establecido en la solicitud.

    • ETA incluido en la propiedad de respuesta duration.
    • No se muestra la propiedad de respuesta duration_in_traffic.

    Corresponde a TRAFFIC_UNAWARE.

    • ETA incluido en la propiedad de respuesta duration.
    • Las propiedades de respuesta duration y staticDuration contienen el mismo valor.
    ETA que tiene en cuenta el tráfico en tiempo real.

    Corresponde a la configuración de departure_time en la solicitud.

    • La hora de llegada estimada, que tiene en cuenta el tráfico en tiempo real, se encuentra en la propiedad de respuesta duration_in_traffic.

    Corresponde a TRAFFIC_AWARE o TRAFFIC_AWARE_OPTIMAL.

    • La hora de llegada estimada, que tiene en cuenta el tráfico en tiempo real, se encuentra en la propiedad de respuesta duration.
    • La propiedad de respuesta staticDuration incluye la duración de viajar por la ruta sin tener en cuenta las condiciones de tráfico.
    • La propiedad duration_in_traffic ya no se muestra.

    Para obtener más información, consulta Cómo configurar la calidad frente a la latencia.

Funciones existentes no compatibles con la API de Routes

Las siguientes funciones no serán compatibles con la API de Routes:

  • XML como formato de respuesta. Solo se admiten JSON y gRPC.

  • Geocodificación inversa

    Ahora usas la API de geocodificación inversa para esta función, que se creó para este caso práctico y proporciona resultados de mayor calidad.

Migra a la API de Routes

Realizamos varios cambios en la API de Routes. La mayoría de los cambios son retrocompatibles con las API actuales, pero a continuación se enumeran algunos cambios rotundos que requieren tu atención cuando se migran apps a la API de Routes.

Actualiza los extremos de la API de REST

Si usas la API de Directions, actualiza tu código para que use el extremo nuevo de la API de Routes:

API de Directions https://maps.googleapis.com/maps/api/directions/outputFormat?parameters
API de Routes https://routes.googleapis.com/directions/v2:computeRoutes

Si usas la API de Distance Matrix, actualiza tu código para usar el extremo nuevo de la API de Routes:

API de Distance Matrix https://maps.googleapis.com/maps/api/distancematrix/outputFormat?parameters
API de Routes https://routes.googleapis.com/distanceMatrix/v2:computeRouteMatrix

Convertir los parámetros de la URL para usar un cuerpo de solicitud HTTP

Con la API de Directions y la API de Distance Matrix, pasas las propiedades de configuración como parámetros de URL a una solicitud HTTP GET. Por ejemplo, para la API de Directions, haz lo siguiente:

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

Con la API de Routes, pasas parámetros en el cuerpo de una solicitud o en los encabezados como parte de una solicitud HTTP POST. Para ver ejemplos, consulta:

Convertir los parámetros actuales en parámetros de la API de Routes

En la siguiente tabla, se enumeran los parámetros de la API de Directions Directions actual y la matriz de distancia que se modificaron o cambiaron de nombre, o bien los parámetros que no se admiten en la versión de Google Analytics. Actualiza tu código si usas alguno de estos parámetros.

Parámetro actual Parámetro de la API de Routes Notas
alternatives computeAlternativeRoutes
arrival_time No está disponible porque el modo TRANSIT no está disponible.
avoid routeModifiers
copyrights

No se incluye en la respuesta. Cuando muestres los resultados a tus usuarios, debes incluir la siguiente declaración:

Powered by Google, ©YEAR Google

Por ejemplo:

Powered by Google, ©2022 Google
departure_time departureTime
distance distanceMeters La distancia solo está disponible en metros.
duration_in_traffic Se quitó de la API de Routes y usa duration. Si deseas obtener más información, consulta Cambios de funcionalidad para la nueva API de Routes más arriba.
language languageCode Solo es compatible con las rutas de Compute.
mode travelMode

Se agregó compatibilidad para TWO_WHEELER.

El modo TRANSIT no está disponible.
region regionCode

status No disponible. Usa los códigos de respuesta HTTP para los errores informados por la API. Consulta Soluciona errores de solicitud para obtener más información.
traffic_model No disponible.
transit_mode No está disponible porque el modo TRANSIT no está disponible.
transit_routing_preference No está disponible porque el modo TRANSIT no está disponible.
units No está disponible para la matriz de ruta.
waypoints intermediates
optimize=true para puntos de referencia No disponible.

Migra desde la versión preliminar

La API de Routes se lanzó en vista previa pública (anterior a la disponibilidad general) en septiembre de 2022. Las ofertas de fase previa a la DG están cubiertas por las Condiciones específicas del servicio de Google Maps Platform. Para obtener más información, consulta las descripciones de la etapa de lanzamiento.

En esta sección, se describe cómo migrar una app de la versión preliminar para la versión de disponibilidad general.

Nuevas funciones agregadas a la versión de disponibilidad general

En la versión de Google Analytics, se agregan las siguientes funciones nuevas que no se incluyeron en la vista previa:

  • Además de los IDs de lugar y las coordenadas de latitud y longitud, ahora puedes especificar una ubicación en la versión de Google Analytics mediante lo siguiente:

    • Strings de dirección ("Chicago, IL" o "Darwin, NT, Australia")

      Las strings de dirección suelen ser la forma en que un usuario ingresa una dirección. Sin embargo, primero, {product_name} debe geocodificar la string de dirección de manera interna para convertirla en coordenadas de latitud y longitud antes de calcular una ruta.

      Además, se agregó compatibilidad con el parámetro de solicitud regionCode, lo que te permite especificar que se muestren resultados geocodificados para una región geográfica específica.

    • Códigos plus

      Los Plus Codes son como direcciones para las personas o lugares que no tienen una dirección real. En lugar de direcciones con nombres de calles y números, los Plus Codes se basan en la latitud y longitud, y se muestran como números y letras.

  • La respuesta de rutas de procesamiento ahora contiene el arreglo geocodingResults. Para cada ubicación en la solicitud (origen, destino o punto de referencia intermedio) que se especificó como una string de dirección o un código plus, la API realiza una búsqueda de ID de lugar. Cada elemento de este arreglo contiene el ID de lugar correspondiente a una ubicación junto con metadatos adicionales sobre la ubicación. Las ubicaciones en la solicitud especificadas como ID de lugar o como coordenadas de latitud y longitud se ignoran.

Cambios en las funciones de Preview existentes

Ahora debes habilitar de forma explícita las siguientes funciones en la disponibilidad general mediante el campo extraComputations del arreglo nuevo a la solicitud:

En la versión preliminar, usaste una máscara de campo a fin de especificar la información para estas funciones en la respuesta. Ahora, debe hacer lo siguiente:

  • Configura el nuevo parámetro de solicitud de arreglo extraComputations para habilitar estas funciones.
  • Establece una máscara de campo para especificar que se mostrará la información en la respuesta.

¿Qué debo saber?

Los siguientes campos ya no se incluirán en las respuestas de computeRouteMatrix, a menos que se habiliten explícitamente las opciones extraComputations:

  • travelAdvisory.tollInfo (información de peaje)

Los siguientes campos ya no se incluirán en las respuestas de computeRoutes, a menos que se habiliten de forma explícita con la configuración extraComputations:

  • routes.legs.travelAdvisory.tollInfo(Información de peaje)
  • routes.travelAdvisory.tollInfo(Información de peaje)
  • routes.travelAdvisory.fuelConsumptionMicroliters(Consumo de combustible)
  • routes.travelAdvisory.speedReadingIntervals(Tráfico en una polilínea)
  • routes.legs.travelAdvisory.speedReadingIntervals(Tráfico en una polilínea)

¿Qué debo hacer?

A fin de recibir los campos de respuesta para la información de los peajes, el consumo de combustible o el tráfico en una polilínea, debes configurar el nuevo campo de arreglo de solicitud, extraComputations, a fin de incluir uno o más de los siguientes valores: