Cuando realizas una solicitud de geocodificación, puedes usar una máscara de campo para especificar la lista de campos que se devolverán en la respuesta. De forma predeterminada, la solicitud devuelve todos los campos en el objeto de respuesta.
Usa una máscara de campo para asegurarte de no solicitar datos innecesarios, lo que, a su vez, ayuda a reducir la latencia de respuesta.
Cómo definir una máscara de campo de respuesta
La máscara de campo de respuesta es una lista separada por comas de rutas de acceso sin espacios, en la que cada ruta especifica un campo único en el objeto de respuesta. La ruta de acceso comienza desde el campo de respuesta de nivel superior y usa una ruta separada por puntos hasta un campo especificado.
Pasa la máscara de campo de respuesta a una solicitud con el parámetro de URL $fields o fields, o bien con el encabezado HTTP o gRPC X-Goog-FieldMask.
Ejemplos de máscaras de campo
A continuación, se muestra la respuesta completa de una solicitud de codificación geográfica directa:
{ "results": [ { "place": "//places.googleapis.com/places/ChIJF4Yf2Ry7j4AR__1AkytDyAE", "placeId": "ChIJF4Yf2Ry7j4AR__1AkytDyAE", "location": { "latitude": 37.422010799999995, "longitude": -122.08474779999999 }, "granularity": "ROOFTOP", "viewport": { "low": { "latitude": 37.420656719708511, "longitude": -122.08547523029148 }, "high": { "latitude": 37.4233546802915, "longitude": -122.0827772697085 } }, "formattedAddress": "1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA", ... }
Construye tus máscaras de campo con la jerarquía de los campos de respuesta, de la siguiente manera:
topLevelField[.secondLevelField][.thirdLevelField][...]
Por ejemplo, para devolver solo el campo placeId en la respuesta, usa una máscara de campo con el siguiente formato:
curl -X GET -H 'Content-Type: application/json' \ -H 'X-Goog-FieldMask: results.placeId' \ -H "X-Goog-Api-Key: API_KEY" \ "https://"geocode.googleapis.com/v4beta/"geocode/address/1600+Amphitheatre+Parkway,+Mountain+View,+CA"
La respuesta ahora es la siguiente:
{ "results": [ { "placeId": "ChIJF4Yf2Ry7j4AR__1AkytDyAE" } ] }
Para devolver el campo viewport, la máscara de campo debe ser la siguiente:
-H 'X-Goog-FieldMask: results.viewport'
La respuesta ahora es la siguiente:
{ "results": [ { "viewport": { "low": { "latitude": 37.420654569708496, "longitude": -122.08547618029148 }, "high": { "latitude": 37.423352530291496, "longitude": -122.0827782197085 } } } ] }
Para devolver ambos:
-H 'X-Goog-FieldMask: results.placeId,results.viewport'
La respuesta ahora es la siguiente:
{ "results": [ { "placeId": "ChIJF4Yf2Ry7j4AR__1AkytDyAE", "viewport": { "low": { "latitude": 37.420654569708496, "longitude": -122.08547618029148 }, "high": { "latitude": 37.423352530291496, "longitude": -122.0827782197085 } } } ] }
Máscaras de campo de gRPC
En el caso de gRPC, establece una variable que contenga la máscara de campo de respuesta. Luego, puedes pasar esa variable a la solicitud.
const ( fieldMask = "results.placeId,results.viewport" )
Consideraciones sobre la ruta del campo
Incluye solo los campos que necesitas en la respuesta para que se muestren solo los campos que necesitas:
- Disminuye los tiempos de procesamiento, por lo que los resultados se devuelven 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.
- Genera un tamaño de respuesta más pequeño, lo que se traduce en un mayor rendimiento de la red.
Para obtener más detalles sobre cómo construir una máscara de campo, consulta field_mask.proto.