Ao chamar os métodos Place Details (New), Nearby Search (New) ou Text Search (New), você precisa especificar quais campos quer retornar na resposta. Não há lista padrão de campos retornados. Se você omitir essa lista, os métodos retornarão um erro.
Para especificar a lista de campos, crie uma máscara de campo de resposta. Em seguida, transmita
a máscara de campo de resposta para qualquer um dos métodos usando o parâmetro $fields ou
fields, ou usando o cabeçalho HTTP ou gRPC X-Goog-FieldMask.
O mascaramento de campo é uma boa prática de design para garantir que você não solicite dados desnecessários, o que ajuda a evitar cobranças de faturamento e tempo de processamento desnecessários.
Definir uma máscara de campo de resposta
A máscara do campo de resposta é uma lista de caminhos separados por vírgulas, em que cada caminho especifica um campo exclusivo na mensagem de resposta. O caminho começa na mensagem de resposta de nível superior e usa um caminho separado por ponto para o campo especificado.
Crie um caminho de campo da seguinte maneira:
topLevelField[.secondLevelField][.thirdLevelField][...]
É possível solicitar todos os campos usando uma máscara de campo de *.
Para mais informações sobre como criar máscaras de campo, consulte field_mask.proto.
Determinar quais máscaras de campo usar
Veja como determinar quais máscaras de campo você quer usar:
- Solicite todos os campos usando uma máscara de campo "*".
- Veja a hierarquia dos campos na resposta e determine quais deles você quer.
- Crie a máscara de campo usando a hierarquia de campos.
Definir uma máscara de campo de resposta para o Nearby Search (New) e o Text Search (New)
O Nearby Search (novo) e o Text Search (novo) retornam uma matriz de objetos do Place no campo places da resposta. Para essas APIs, places é o campo de nível superior
da resposta.
Por exemplo, para ver o objeto de resposta completo de um Text Search (novo):
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'
O objeto de resposta completo de uma chamada de Text Search (New) está no 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"
}, ...
},
...
]
}
Portanto, você especifica uma máscara de campo para essas APIs no formulário:
places[.secondLevelField][.thirdLevelField][...]
Para retornar apenas os campos formattedAddress e displayName, defina
a máscara de campo como:
places.formattedAddress,places.displayName
Especificar displayName inclui os campos text e language de
displayName. Se você quiser apenas o campo text, defina a máscara de campo como:
places.formattedAddress,places.displayName.text
Definir uma máscara de campo de resposta para o Place Details (novo)
O Place Details retorna um único objeto do Place no formulário:
{
"name": "places/ChIJkR8FdQNB0VQRm64T_lv1g1g",
"id": "ChIJkR8FdQNB0VQRm64T_lv1g1g",
"types": [
"locality",
"political"
],
"formattedAddress": "Trinidad, CA 95570, USA",
"displayName": {
"text": "Trinidad",
"languageCode": "en"
}
...
}
Portanto, para especificar uma máscara de campo para essa API, especifique os campos do objeto Place que você quer retornar:
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
Chamada gRPC
Para gRPC, defina uma variável contendo a máscara de campo de resposta. Você pode então passar essa variável para a solicitação.
const ( fieldMask = "places.formattedAddress,places.displayName" )
Considerações sobre o caminho do campo
Inclua somente os campos necessários na resposta. Retornar apenas os campos necessários:
- Diminui o tempo de processamento, para que seus resultados sejam retornados com uma latência menor.
- Garante o desempenho de latência estável caso a API adicione mais campos de resposta no futuro e esses novos campos exigirem mais tempo de computação. Se você selecionar todos os campos ou todos no nível superior, poderá notar uma degradação no desempenho quando todos os novos campos forem incluídos automaticamente na resposta.
- Resulta em um tamanho de resposta menor, que se traduz em maior capacidade de rede.
- Garante que você não solicite dados desnecessários, o que ajuda a evitar tempo de processamento desnecessário e cobranças faturadas.