Cuando llamas a los métodos Place Details (nuevo), Nearby Search (nuevo) o Text Search (nuevo), debes especificar qué campos deseas que se muestren en la respuesta. No hay una lista predeterminada de los 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 de campo de respuesta a cualquier método mediante el parámetro $fields o fields, o bien con el encabezado HTTP o de gRPC X-Goog-FieldMask.
El enmascaramiento 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 innecesarios.
Define una máscara de campo de respuesta
La máscara de campo de respuesta es una lista de rutas de acceso separadas por comas, en la que cada ruta especifica un campo único en el mensaje de respuesta. La ruta comienza desde el mensaje de respuesta de nivel superior y usa una ruta de acceso separada por puntos hacia el campo especificado.
Construye una ruta de campo de la siguiente manera:
topLevelField[.secondLevelField][.thirdLevelField][...]
Puedes solicitar todos los campos con una máscara de campo *.
Para obtener más información sobre cómo construir máscaras de campo, consulta field_mask.proto.
Cómo determinar qué máscaras de campo usar
A continuación, te mostramos cómo determinar qué máscaras de campo deseas usar:
- Solicita todos los campos con una máscara de campo `*`.
- Observa la jerarquía de los campos en la respuesta y determina qué campos quieres.
- Compila tu máscara de campo con la jerarquía de campos.
Cómo definir una máscara de campo de respuesta para Nearby Search (nuevo) y Text Search (nuevo)
Nearby Search (nuevo) y Text Search (nuevo) muestran un array de objetos Place en el campo places de la respuesta. Para estas APIs, places es el campo de nivel superior de la respuesta.
Por ejemplo, para ver el objeto de respuesta completo de una búsqueda de texto (nuevo), ejecuta lo siguiente:
curl -X POST -d '{
"textQuery" : "Spicy Vegetarian Food in Sydney, Australia"
}' \
-H 'Content-Type: application/json' -H 'X-Goog-Api-Key: API_KEY' \
-H 'X-Goog-FieldMask: *' \
'https://places.googleapis.com/v1/places:searchText'
El objeto de respuesta completo de una llamada de Text Search (nuevo) tiene el siguiente formato:
{
"places": [
{
"name": "places/ChIJs5ydyTiuEmsR0fRSlU0C7k0",
"id": "ChIJs5ydyTiuEmsR0fRSlU0C7k0",
"types": [
"vegetarian_restaurant",
"vegan_restaurant",
"meal_takeaway",
"restaurant",
"food",
"point_of_interest",
"establishment"
],
"nationalPhoneNumber": "0433 479 794",
"internationalPhoneNumber": "+61 433 479 794",
"formattedAddress": "29 King St, Sydney NSW 2000, Australia",
"displayName": {
"text": "Spiced @ Barangaroo",
"languageCode": "en"
}, ...
},
...
]
}
Por lo tanto, debes especificar una máscara de campo para estas APIs de la siguiente forma:
places[.secondLevelField][.thirdLevelField][...]
Si deseas mostrar solo los campos formattedAddress y displayName, establece la máscara de campo de la siguiente manera:
places.formattedAddress,places.displayName
Si especificas displayName, se incluyen los campos text y language de displayName. Si solo deseas el campo text, establece la máscara de campo de la siguiente manera:
places.formattedAddress,places.displayName.text
Define una máscara de campo de respuesta para Place Details (nuevo)
Place Details devuelve un solo objeto Place con la siguiente forma:
{
"name": "places/ChIJkR8FdQNB0VQRm64T_lv1g1g",
"id": "ChIJkR8FdQNB0VQRm64T_lv1g1g",
"types": [
"locality",
"political"
],
"formattedAddress": "Trinidad, CA 95570, USA",
"displayName": {
"text": "Trinidad",
"languageCode": "en"
}
...
}
Por lo tanto, especifica una máscara de campo para esta API especificando los campos del objeto Place que deseas mostrar:
curl -X GET -H 'Content-Type: application/json' \ -H "X-Goog-Api-Key: API_KEY" \ -H "X-Goog-FieldMask: formattedAddress,displayName" \ https://places.googleapis.com/v1/places/ChIJj61dQgK6j4AR4GeTYWZsKWw
Llamada a gRPC
Para gRPC, configura una variable que contenga la máscara de campo de respuesta. Luego, puedes pasar esa variable a la solicitud.
const ( fieldMask = "places.formattedAddress,places.displayName" )
Consideraciones de la ruta del campo
Incluye solo los campos que necesitas en la respuesta. Mostrar solo los campos que necesitas:
- Disminuye los tiempos de procesamiento, por lo que tus resultados se muestran con una latencia más baja.
- Garantiza un rendimiento de latencia estable si la API agrega más campos de respuesta en el futuro y si esos campos nuevos requieren tiempo de procesamiento adicional. Si seleccionas todos los campos, o si seleccionas todos los campos de nivel superior, es posible que experimentes una degradación del rendimiento cuando todos los campos nuevos se incluyan de forma automática en tu respuesta.
- Genera un tamaño de respuesta más pequeño, lo que se traduce en una mayor capacidad de procesamiento de la red.
- Se asegura de no solicitar datos innecesarios, lo que ayuda a evitar tiempos de procesamiento y cargos facturados innecesarios.