Revisa la respuesta de la ruta

Cuando la API de Routes calcula una ruta, toma los puntos de referencia y los parámetros de configuración que proporcionas como entrada. Luego, la API devuelve una respuesta que contiene la ruta predeterminada y una o más rutas alternativas.

Tu respuesta puede incluir diferentes tipos de rutas y otros datos, según los campos que solicites:

Para obtener la lista completa de opciones de entrada, consulta Opciones de ruta disponibles y el cuerpo de la solicitud.

Con la respuesta, puedes proporcionar a tus clientes la información necesaria para seleccionar la ruta adecuada según sus requisitos.

Acerca de las máscaras de campo

Cuando llamas a un método para calcular una ruta, debes especificar una máscara de campo que defina qué campos deseas que se muestren en la respuesta. No hay una lista predeterminada de campos devueltos. Si omites esta lista, los métodos mostrarán un error.

En los ejemplos de este documento, se muestra el objeto de respuesta completo sin tener en cuenta las máscaras de campos. En un entorno de producción, tu respuesta solo incluiría los campos que especificas de forma explícita en la máscara de campo.

Para obtener más información, consulta Cómo elegir la información que se devolverá.

Acerca de la visualización de derechos de autor

Cuando muestres los resultados a los usuarios, debes incluir la siguiente declaración de derechos de autor:

Powered by Google, ©YEAR Google

Por ejemplo:

Powered by Google, ©2023 Google

Acerca de las rutas, los tramos y los pasos

Antes de analizar la respuesta que devuelve la API de Routes, debes comprender los componentes que conforman una ruta:

Tu respuesta puede contener información sobre cada uno de estos componentes de la ruta:

• Ruta: Es todo el viaje desde el punto de referencia de origen, pasando por los puntos de referencia intermedios, hasta el punto de referencia de destino. Una ruta consta de uno o más segmentos.

• Segmento: Es la ruta desde una parada en una ruta hasta la siguiente parada en la ruta. Cada tramo consta de uno o más pasos discretos.

  Una ruta contiene un tramo separado para el camino desde cada punto de referencia hasta el siguiente. Por ejemplo, si la ruta contiene un solo punto de partida y un solo punto de destino, entonces la ruta contiene un solo tramo. Por cada parada adicional que agregues a la ruta después del origen y el destino, denominada parada intermedia, la API agrega un tramo independiente.

  La API no agrega una etapa para un punto de referencia intermedio de transferencia. Por ejemplo, una ruta que contiene un punto de referencia de origen, un punto de referencia intermedio de paso y un punto de referencia de destino contiene solo un tramo desde el origen hasta el destino, mientras pasa por el punto de referencia. Para obtener más información sobre los puntos de referencia de paso, consulta Cómo definir un punto de referencia de paso.

• Paso: Es una sola instrucción a lo largo de la etapa de una ruta. Un paso es la unidad más pequeña de una ruta. Por ejemplo, un paso puede indicar "Gira a la izquierda en la calle principal".

Qué contiene la respuesta

El objeto JSON que representa la respuesta de la API contiene las siguientes propiedades de nivel superior:

• routes, un array de elementos de tipo Route. El array routes contiene un elemento para cada ruta que muestra la API. El array puede contener un máximo de cinco elementos: la ruta predeterminada, la ruta ecológica y hasta tres rutas alternativas.

• geocodingResults, un array de elementos de tipo GeocodingResults. Para cada ubicación de la solicitud (origen, destino o parada intermedia) que especificaste como una cadena de dirección o como un código plus, la API realiza una búsqueda de ID de lugar. Cada elemento de este array contiene el ID de lugar correspondiente a una ubicación. No se incluyen las ubicaciones de la solicitud especificadas como un ID de lugar o como coordenadas de latitud y longitud. Si especificaste todas las ubicaciones con IDs de lugar o coordenadas de latitud y longitud, no se proporciona este array.

• fallbackInfo, de tipo FallbackInfo. Si la API no puede calcular una ruta a partir de todas las propiedades de entrada, es posible que recurra a otra forma de cálculo. Cuando se usa el modo de resguardo, este campo contiene información detallada sobre la respuesta de resguardo. De lo contrario, este campo no se establece.

La respuesta tiene el siguiente formato:

{
  // The routes array.
  "routes": [
    {
      object (Route)
    }
  ],
  // The place ID lookup results.
  "geocodingResults": [
    {
      object (GeocodedWaypoint)
    }
  ],
  // The fallback property.
  "fallbackInfo": {
    object (FallbackInfo)
  }
}

Descifra el array de rutas

La respuesta contiene el array routes, en el que cada elemento es del tipo Route. Cada elemento del array representa una ruta completa desde el origen hasta el destino. La API siempre devuelve al menos una ruta, llamada ruta predeterminada.

Puedes solicitar rutas adicionales. Si solicitas una ruta ecológica, el array puede contener dos elementos: la ruta predeterminada y la ruta ecológica. También puedes establecer computeAlternativeRoutes en true en la solicitud para agregar hasta tres rutas alternativas a la respuesta.

Cada ruta del array se identifica con la propiedad del array routeLabels:

El array legs contiene la definición de cada tramo de la ruta. Las propiedades restantes, como distanceMeters, duration y polyline,, contienen información sobre la ruta en su totalidad:

{
  "routeLabels": [
    enum (RouteLabel)
  ],
  "legs": [
    {
      object (RouteLeg)
    }
  ],
  "distanceMeters": integer,
  "duration": string,
  "routeLabels": [string],
  "staticDuration": string,
  "polyline": {
    object (Polyline)
  },
  "description": string,
  "warnings": [
    string
  ],
  "viewport": {
    object (Viewport)
  },
  "travelAdvisory": {
    object (RouteTravelAdvisory)
  }
  "routeToken": string
}

Debido a las condiciones de conducción actuales y otros factores, la ruta predeterminada y la ruta ecológica pueden ser las mismas. En este caso, el array routeLabels contiene ambas etiquetas: DEFAULT_ROUTE y FUEL_EFFICIENT.

{
  "routes": [
    {
      "routeLabels": [
        "DEFAULT_ROUTE",
        "FUEL_EFFICIENT"
      ],
     …
    }
  ]
}

Información sobre el array de tramos

Cada route de la respuesta contiene un array legs, en el que cada elemento del array legs es de tipo RouteLeg. Cada tramo del array define la ruta desde un punto de referencia hasta el siguiente a lo largo de la ruta. Una ruta siempre contiene al menos un tramo.

La propiedad legs contiene la definición de cada paso a lo largo del tramo en el array steps. Las propiedades restantes, como distanceMeters, duration y polyline, contienen información sobre el tramo.

{
  "distanceMeters": integer,
  "duration": string,
  "staticDuration": string,
  "polyline": {
    object (Polyline)
  },
  "startLocation": {
    object (Location)
  },
  "endLocation": {
    object (Location)
  },
  "steps": [
    {
      object (RouteLegStep)
    }
  ],
  "travelAdvisory": {
    object (RouteLegTravelAdvisory)
  }
}

Comprende el array de pasos

Cada tramo de la respuesta contiene un array steps, en el que cada elemento del array steps es de tipo RouteLegStep. Un paso corresponde a una sola instrucción a lo largo de la etapa. Un tramo siempre contiene al menos un paso.

Cada elemento del array steps incluye la propiedad navigationInstruction, del tipo NavigationInstruction, que contiene la instrucción del paso. Por ejemplo:

"navigationInstruction": {
  "maneuver": "TURN_LEFT",
  "instructions": "Turn left toward Frontage Rd"
}

El objeto instructions puede contener información adicional sobre el paso. Por ejemplo:

"navigationInstruction": {
  "maneuver": "TURN_SLIGHT_LEFT",
  "instructions": "Slight left (signs for I-90 W/Worcester)nParts of this road may be closed at certain times or days"
}

Las propiedades restantes del paso describen información sobre el paso, como distanceMeters, duration y polyline:

{
  "distanceMeters": integer,
  "staticDuration": string,
  "polyline": {
    object (Polyline)
  },
  "startLocation": {
    object (Location)
  },
  "endLocation": {
    object (Location)
  },
  "navigationInstruction": {
    object (NavigationInstruction)
  }
}

Cómo especificar el idioma de las instrucciones de los pasos

La API devuelve información de la ruta en el idioma local, transliterada a una secuencia de comandos que el usuario pueda leer, si es necesario, y respetando el idioma preferido. Todos los componentes de la dirección se muestran en el mismo idioma.

• Usa el parámetro languageCode de una solicitud para establecer de forma explícita el idioma de la ruta desde la lista de idiomas admitidos. Google actualiza con frecuencia los idiomas admitidos, por lo que es posible que esta lista no sea exhaustiva.

• Si no hay un nombre disponible en el idioma especificado, la API usa la coincidencia más cercana.

• El idioma especificado puede influir 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.

Información sobre el array geocodingResults

Para cada ubicación de la solicitud (origen, destino o parada intermedia) que se especificó como una cadena de dirección o como un código plus, la API intenta encontrar la ubicación más relevante que tenga un ID de lugar correspondiente. Cada elemento del array geocodingResults contiene el campo placeID, que incluye la ubicación como un ID de lugar, y un campo type que especifica el tipo de ubicación, como street_address, premise o airport.

El array geocodingResults contiene tres campos:

• origin: Es el ID de lugar del origen si se especificó como una cadena de dirección o como un Plus Code. De lo contrario, este campo se omite de la respuesta.

• destination: Si se especificó como una cadena de dirección o como un código Plus, es el ID del lugar de destino. De lo contrario, este campo se omite en la respuesta.

• intermediates: Es un array que contiene el ID de lugar de los puntos de parada intermedios especificados como una cadena de dirección o como un Plus Code. Si especificas un punto de ruta intermedio con un ID de lugar o coordenadas de latitud y longitud, se omitirá en la respuesta. Usa la propiedad intermediateWaypointRequestIndex en la respuesta para determinar qué parada intermedia de la solicitud corresponde al ID de lugar en la respuesta.

"geocodingResults": {
    "origin": {
        "geocoderStatus": {},
        "type": [
             enum (Type)
        ],
        "placeId": string
    },
    "destination": {
        "geocoderStatus": {},
        "type": [
            enum (Type)
        ],
        "placeId": string
    },
    "intermediates": [
        {
            "geocoderStatus": {},
            "intermediateWaypointRequestIndex": integer,
            "type": [
                enum (Type)
            ],
            "placeId": string
        },
        {
           "geocoderStatus": {},
           "intermediateWaypointRequestIndex": integer,
            "type": [
                enum (Type)
            ],
            "placeId": string
        }
    ]
}

Comprende los valores de respuesta localizados

Los valores de respuesta localizados son un campo de respuesta adicional que proporciona texto localizado para los valores de parámetros devueltos. Se proporciona texto localizado para la duración, la distancia y el sistema de unidades (métrico o imperial) del viaje. Puedes solicitar valores localizados con una máscara de campo y especificar el idioma y el sistema de unidades, o bien usar los valores que infiere la API. Para obtener más detalles, consulta LocalizedValues.

Por ejemplo, si especificas un código de idioma para alemán (de) y unidades imperiales, obtendrás un valor para distanceMeters de 49889.7, pero también texto localizado que proporciona esa medición de distancia en alemán y unidades imperiales, por lo que se mostrará "31 Meile".

Este es un ejemplo de lo que verías para los valores localizados:

{ "localized_values":
  {
    "distance": { "text": "31,0 Meile/n" },
    "duration": { "text": 38 Minuten}.
    "static_duration": { "text": 36 Minuten}.
  }
}

Si no especificas el idioma o el sistema de unidades, la API infiere el idioma y las unidades de la siguiente manera:

• El método ComputeRoutes infiere las unidades de ubicación y distancia desde el punto de ruta de origen. Por lo tanto, para una solicitud de ruta en EE.UU., la API infiere el idioma en-US y las unidades IMPERIAL.
• El método ComputeRouteMatrix usa de forma predeterminada el idioma "en-US" y las unidades MÉTRICAS.