Ao chamar os métodos Place Details (novo), Nearby Search (novo) ou Text Search (novo), é necessário especificar quais campos você quer que sejam retornados na resposta. Não há uma lista padrão de campos retornados. Se você omitir essa lista, os métodos vão retornar um erro.
Uma lista completa dos campos de dados de lugar aceitos e as SKUs correspondentes podem ser encontradas em Campos de dados de lugar (novo). Para informações sobre os campos específicos de cada API, consulte:
- Parâmetros FieldMask de Place Details (New)
- Parâmetros FieldMask do Nearby Search (novo)
- Parâmetros de FieldMask do Text Search (novo)
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 método 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 tempo de processamento e cobrança desnecessários.
Definir uma máscara de campo de resposta
A máscara de campo de resposta é uma lista de caminhos separados por vírgulas, em que cada caminho especifica um campo exclusivo no corpo da 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 o 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 de
*. - Analise a hierarquia dos campos na resposta e determine quais campos você quer.
- Crie sua máscara de campo usando a hierarquia de campos.
Definir uma máscara de campo de resposta para o Nearby Search (novo) e o Text Search (novo)
O Nearby Search (novo) e o Text Search (novo) retornam uma matriz de objetos 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 uma Text Search (nova):
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 (novo) é do tipo:
{
"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, especifique uma máscara de campo para essas APIs no formato:
places[.secondLevelField][.thirdLevelField][...]
Se você quiser retornar apenas os campos formattedAddress e displayName, defina
a máscara de campo como:
places.formattedAddress,places.displayName
A especificação de 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 Place Details (novo)
O Place Details retorna um único objeto 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, você especifica uma máscara de campo para essa API especificando os campos do objeto Place que 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 que contenha a máscara de campo de resposta. Em seguida, é possível transmitir essa variável para a solicitação.
const ( fieldMask = "places.formattedAddress,places.displayName" )
Considerações sobre o caminho do campo
Inclua apenas os campos necessários na resposta. Retorna apenas os campos necessários:
- Diminui os tempos de processamento, para que os resultados sejam retornados com uma latência menor.
- Garante desempenho de latência estável se a API adicionar mais campos de resposta no futuro e esses novos campos exigirem tempo de computação extra. Se você selecionar todos os campos ou todos os campos no nível superior, poderá ocorrer uma degradação no desempenho quando todos os novos campos forem incluídos automaticamente na resposta.
- Resulta em um tamanho de resposta menor, o que se traduz em maior capacidade de processamento da rede.
- Garante que você não solicite dados desnecessários, o que ajuda a evitar tempo de processamento desnecessário e cobranças.