Escolher campos para retornar

Ao chamar os métodos Place Details (novo), Nearby Search (novo) ou Text Search (novo), é necessário especificar quais campos você quer retornar na resposta. Não há uma 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 o cabeçalho HTTP ou gRPC X-Goog-FieldMask.

O mascaramento de campo é uma prática recomendada de design para garantir que você não solicite dados desnecessários, o que ajuda a evitar cobranças desnecessárias em tempo de processamento e cobrança.

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 na mensagem de resposta. O caminho começa na mensagem de resposta de nível superior e usa um caminho separado por ponto até 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 construir máscaras de campo, consulte field_mask.proto.

Determinar as máscaras de campo a serem usadas

Confira como determinar quais máscaras de campo você quer usar:

  1. Solicite todos os campos usando uma máscara de campo de "*".
  2. Observe a hierarquia dos campos na resposta e determine quais você quer.
  3. Criar 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 do Place no campo places da resposta. Para essas APIs, places é o campo de nível superior da resposta.

Por exemplo, para conferir o objeto de resposta completo de uma 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 do Text Search (novo) 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 formato:

places[.secondLevelField][.thirdLevelField][...]

Se você quiser retornar apenas os campos formattedAddress e displayName, defina sua 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 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, para especificar uma máscara de campo para essa API, especifique os campos do objeto do 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 do campo de resposta. É 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. Retornar apenas os campos necessários:

  • Diminui o tempo de processamento, para que os resultados sejam retornados com uma latência menor.
  • Garante um 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á haver uma queda no desempenho quando todos os campos novos forem incluídos automaticamente na resposta.
  • Resultados em uma resposta menor, o que resulta em maior capacidade de rede.
  • Garante que você não solicite dados desnecessários, o que ajuda a evitar tempos de processamento desnecessários e cobranças faturadas.