Ao fazer uma solicitação de geocodificação, é possível usar uma máscara de campo para especificar a lista de campos a serem retornados na resposta. Para os endpoints Geocodificar um endereço, Geocodificar um local e Geocodificação de lugar, todos os campos no objeto de resposta são retornados por padrão. Para o endpoint Pesquisar destinos, é necessário especificar uma máscara de campo na solicitação da API.
Use uma máscara de campo para não solicitar dados desnecessários, o que ajuda na latência de resposta.
Definir uma máscara de campo de resposta
A máscara de campo de resposta é uma lista separada por vírgulas de caminhos sem espaços, em que cada caminho especifica um campo exclusivo no objeto de resposta. O caminho começa no campo de resposta de nível superior e usa um caminho separado por pontos até um campo especificado.
Transmita a máscara de campo de resposta para uma solicitação usando o parâmetro de URL $fields
ou fields, ou usando o cabeçalho HTTP ou gRPC X-Goog-FieldMask.
Exemplos de máscaras de campo
Confira abaixo a resposta completa de uma solicitação de geocodificação direta:
{ "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", ... }
Crie suas máscaras de campo usando a hierarquia dos campos de resposta, no formato:
topLevelField[.secondLevelField][.thirdLevelField][...]
Por exemplo, para retornar apenas o campo placeId na resposta, use uma máscara de campo:
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"
A resposta agora é:
{ "results": [ { "placeId": "ChIJF4Yf2Ry7j4AR__1AkytDyAE" } ] }
Para retornar o campo viewport, sua máscara de campo é:
-H 'X-Goog-FieldMask: results.viewport'
A resposta agora é:
{ "results": [ { "viewport": { "low": { "latitude": 37.420654569708496, "longitude": -122.08547618029148 }, "high": { "latitude": 37.423352530291496, "longitude": -122.0827782197085 } } } ] }
Para devolver os dois:
-H 'X-Goog-FieldMask: results.placeId,results.viewport'
A resposta agora é:
{ "results": [ { "placeId": "ChIJF4Yf2Ry7j4AR__1AkytDyAE", "viewport": { "low": { "latitude": 37.420654569708496, "longitude": -122.08547618029148 }, "high": { "latitude": 37.423352530291496, "longitude": -122.0827782197085 } } } ] }
Máscaras de campo gRPC
Para gRPC, defina uma variável que contenha a máscara de campo de resposta. Em seguida, transmita essa variável para a solicitação.
const ( fieldMask = "results.placeId,results.viewport" )
Considerações sobre o caminho do campo
Inclua apenas os campos necessários na resposta para retornar apenas os campos de que você precisa:
- Diminui os tempos de processamento, para que os resultados sejam retornados com uma latência menor.
- Garante um desempenho de latência estável. Se você selecionar todos os campos ou todos os campos no nível superior, poderá ocorrer uma degradação da performance quando novos campos forem adicionados e incluídos automaticamente na sua resposta.
- Resulta em um tamanho de resposta menor, o que se traduz em maior capacidade de processamento da rede.
Para mais detalhes sobre como criar uma máscara de campo, consulte o field_mask.proto.