Escolher campos para retornar

Ao fazer uma solicitação de geocodificação, use uma máscara de campo para especificar a lista de campos que vão ser retornados na resposta. As máscaras de campo ajudam na latência de resposta, garantindo que você não solicite dados desnecessários.

Para métodos básicos de geocodificação (Geocodificar um endereço, Geocodificar um local e Geocodificar um lugar), todos os campos no objeto de resposta são retornados por padrão, ao contrário de Pesquisar destinos, em que é necessário especificar uma máscara de campo. Embora uma máscara de campo não seja necessária para métodos básicos, recomendamos que você use uma para reduzir a latência de resposta.

Definir uma máscara de campo de resposta

A máscara de campo de resposta é uma lista de caminhos separada por vírgulas 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 para 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 o cabeçalho HTTP ou gRPC X-Goog-FieldMask.

Exemplos de máscaras de campo

Veja 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 as máscaras de campo usando a hierarquia dos campos de resposta, no formato:

topLevelField[.secondLevelField][.thirdLevelField][...]

Pesquisar máscaras de campo de destinos

Ao chamar SearchDestinations, especifique os atributos de destino exatos de que você precisa, como os detalhes do lugar principal, entradas, pontos de navegação, contornos de edifícios (displayPolygon) e pontos de referência:

curl -X POST -d '{"addressQuery": {"addressQuery": "1600 Amphitheatre Pkwy, Mountain View, CA"}}' \
-H 'Content-Type: application/json' \
-H 'X-Goog-FieldMask: destinations.primary.displayName,destinations.primary.displayPolygon,destinations.entrances,destinations.navigationPoints,destinations.landmarks' \
-H "X-Goog-Api-Key: API_KEY" \
https://geocode.googleapis.com/v4/geocode/destinations

Máscaras de campo de geocodificação principal

Por exemplo, para retornar apenas o campo placeId em uma resposta GeocodeAddress, use uma máscara de campo de:

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/v4/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 do 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á haver uma degradação de desempenho quando novos campos forem adicionados e incluídos automaticamente na resposta.
• Resulta em um tamanho de resposta menor, o que se traduz em maior capacidade de rede.

Para mais detalhes sobre como criar uma máscara de campo, consulte field_mask.proto.