Elige qué información mostrar

Cuando llamas a un método para calcular una ruta o una matriz de rutas, debes especificar qué información deseas enumerando los campos que se mostrarán en la respuesta. No hay una lista predeterminada de campos que se muestran. Si omites esta lista, los métodos mostrarán un error.

Para especificar la lista de campos, crea una máscara de campo de respuesta. Luego, pasa la máscara del campo de respuesta a cualquiera de los métodos con el parámetro de URL $fields o fields, o con el encabezado HTTP o gRPC X-Goog-FieldMask.

Usar una máscara de campo es una práctica de diseño recomendada para garantizar que no solicites datos innecesarios, lo que ayuda a evitar tiempos de procesamiento y cargos de facturación adicionales.

Para obtener más información sobre los parámetros de URL, consulta Parámetros del sistema.

Define una máscara de campo de respuesta

La máscara de campo de respuesta es una lista de rutas separadas por comas, en la que cada ruta especifica un campo único en el mensaje de respuesta. La ruta de acceso comienza en el mensaje de respuesta de nivel superior y usa una ruta de acceso separada por puntos al campo especificado.

Crea y especifica una ruta de acceso de campo de la siguiente manera:

  1. Busca los campos que contienen la información que necesitas en la API de Routes. Para obtener más detalles, consulta Referencias de campos.
  2. Determina las rutas de los campos que necesitas y crea las máscaras de campo para ellos: Para obtener más información, consulta Determina qué máscara de campo quieres usar.

  3. Combina las máscaras de campo de todos los campos que necesites y sepáralas con comas. Por ejemplo, para solicitar el distanceMeters del tramo de la ruta, además de la duración de cada paso del tramo, ingresa ambos, separados por una coma, sin espacios:

    routes.legs.distanceMeters,routes.legs.steps.duration

  4. Envía la máscara de campo con tu solicitud a la API. Por ejemplo, en una solicitud de cURL, especificarías la máscara de campo con -H y X-Goog-FieldMask:

    -H X-Goog-FieldMask: routes.legs.distanceMeters,routes.legs.steps.duration
Para ver ejemplos y más detalles, consulta las siguientes secciones.

Referencias de campos

Para ver los campos que puedes solicitar en una respuesta a través de máscaras de campo, consulta las referencias de la API de Routes vinculadas en la siguiente lista. Especifica los campos en mayúsculas y minúsculas, como se muestra en la referencia. Por ejemplo, routePreference.

Estas referencias incluyen los campos que están disponibles. Sin embargo, debes consultar la jerarquía de los campos para determinar la ruta de acceso completa de la máscara de campo. Para obtener detalles sobre cómo obtener la jerarquía de los campos, consulta Determina qué máscara de campo deseas usar.

  • Cómo calcular la máscara de campo de ruta
    • REST: Especifica los campos del objeto Route en la respuesta que se mostrará, con el prefijo routes., por ejemplo, routes.distanceMeters.
    • gRPC: Especifica los campos del objeto Route en la respuesta que se mostrará.
  • Máscaras de campo de la matriz de rutas de Compute

Determina qué máscaras de campo usar

Sigue estos pasos para determinar qué campos deseas usar y construir las máscaras de campo para ellos:

  1. Solicita todos los campos con una máscara de campo de *.
  2. Observa la jerarquía de los campos en la respuesta para los campos que deseas.

  3. Crea tus máscaras de campo con la jerarquía de los campos que se muestra en el paso anterior, con este formato:

    topLevelField[.secondLevelField][.thirdLevelField][...]

Por ejemplo, para esta respuesta parcial de una ruta:

"routes": [
    {
        "legs": [
            {  "steps": [
                    {"distanceMeters": 119},
                    {"distanceMeters": 41}  ]
            }
        ],
        "distanceMeters": 160
    }
]

Si deseas mostrar solo el campo distanceMeters para el tramo de la ruta, es decir, el último distanceMeters del ejemplo anterior, tu máscara de campo es la siguiente:

routes.legs.distanceMeters

Si, en cambio, deseas mostrar el campo distanceMeters para cada paso de la etapa de la ruta, es decir, el distanceMeters debajo de steps en el ejemplo anterior, tu máscara de campo es la siguiente:

routes.legs.steps.distanceMeters

Si deseas mostrar ambos, con el resultado anterior, tu máscara de campo es la siguiente:

routes.legs.distanceMeters,routes.legs.steps.distanceMeters

Ejemplos de rutas de máscaras de campo

Esta sección contiene más ejemplos sobre cómo especificar una ruta de campo como parte de una máscara de campo de respuesta en llamadas REST y gRPC.

Llamada REST a computeRoutes

En el primer ejemplo, usas una llamada REST al método computeRoutes para calcular una ruta. En este ejemplo, en el encabezado, especificas máscaras de campo para mostrar los campos distanceMeters y duration de la ruta en la respuesta. Recuerda agregar el prefijo routes al nombre del campo.

X-Goog-FieldMask: routes.distanceMeters,routes.duration

Llamada REST a computeRouteMatrix

Para el método computeRouteMatrix de REST que se usa para calcular una matriz de rutas, en el encabezado, especifica que se muestren originIndex, destinationIndex y duration para cada combinación de origen y destino:

X-Goog-FieldMask: originIndex,destinationIndex,duration

Llamada a gRPC

Para gRPC, establece una variable que contenga la máscara de campo de respuesta. Luego, puedes pasar esa variable a la solicitud.

const (
  fieldMask = "routes.distanceMeters,routes.duration,routes.polyline.encodedPolyline"
)

Consideraciones sobre la ruta de un campo

Incluye solo los campos que necesites en la respuesta para que se muestren solo los campos que necesitas:

  • Disminuye los tiempos de procesamiento, por lo que los resultados se muestran con una latencia más baja.
  • Garantiza un rendimiento de latencia estable. Si seleccionas todos los campos o todos los campos en el nivel superior, es posible que experimentes una degradación del rendimiento cuando se agreguen campos nuevos y, luego, se incluyan automáticamente en tu respuesta.
  • Produce un tamaño de respuesta más pequeño, lo que se traduce en una mayor capacidad de procesamiento de red.
  • Garantiza que no solicites datos innecesarios, lo que ayuda a evitar tiempos de procesamiento y cargos de facturación adicionales.

Para obtener más detalles sobre la construcción de una máscara de campo, consulta field_mask.proto.

Cómo solicitar un token de ruta

Para solicitar que la API de Routes devuelva tokens de ruta para las rutas generadas, sigue estos pasos:

  1. Establece los siguientes parámetros obligatorios para mostrar un token de ruta:
    • Establece travelMode en DRIVE.
    • Establece routingPreference como TRAFFIC_AWARE o TRAFFIC_AWARE_OPTIMAL.
  2. Verifica que ninguno de los puntos de ruta de tu ruta sean puntos via.
  3. Especifica la máscara de campo routes.routeToken para mostrar un token de ruta: 
    X-Goog-FieldMask: routes.routeToken

Puedes usar el token de ruta para tu ruta planificada en el SDK de Navigation. Para obtener más detalles, consulta Cómo planificar una ruta (Android) o Cómo planificar una ruta (iOS).

Ejemplo de token de ruta

Este es un ejemplo de cuerpo de solicitud de cURL para una ruta de un solo origen y un solo destino que usa máscaras de campo para solicitar un token de ruta, junto con la duración, la distancia y la polilínea de la ruta:

curl -X POST -d
{"origin":{
    "location": {
        "latLng":{
            "latitude":  -37.8167,
            "longitude": 144.9619
        }
    }
},
"destination":{
    "location": {
        "latLng":{
            "latitude":-37.8155,
            "longitude": 144.9663
        }
    }
},
"routingPreference":"TRAFFIC_AWARE",
"travelMode":"DRIVE"
}
-H 'X-Goog-Api-Key: YOUR_API_KEY' \
-H X-Goog-FieldMask: routes.routeToken,routes.duration,routes.distanceMeters,routes.polyline.encodedPolyline
'https://routes.googleapis.com/directions/v2:computeRoutes'

Para obtener más detalles, consulta la referencia de la API de Compute Routes.