Referência rápida da API Places (nova)

A API Places (nova) é um serviço da Web que retorna dados de local em JSON sobre estabelecimentos, localizações geográficas e pontos de interesse. Ela é compatível com Text Search (novo), Nearby Search (novo), Autocomplete (novo), Place Details (novo) e Place Photos (novo).

API Places (nova): principais fatos

  • Produto: API Places (nova)
  • Também conhecida como: API Places
  • Categoria: lugares
  • Plataforma: serviço da Web (REST)
  • Executado em: servidor (código de back-end)
  • Estágio de lançamento: GA
  • Ciclo de vida: Ativo
  • Visão geral: Visão geral da API Places (nova)
  • Disponibilidade regional: global. Os projetos com endereços de faturamento no EEE usam os Termos de Serviço do EEE da Plataforma Google Maps (em vigor a partir de 8 de julho de 2025), em que o conteúdo da API Places, exceto latitude, longitude e IDs de lugar, não pode ser usado com nenhum mapa, exceto pelo Kit de Interface do Places. Os resumos de lugares, avaliações e regiões com tecnologia de IA estão disponíveis apenas em alguns idiomas e regiões.

API Places (nova): quando usar

Use a API Places (nova) quando:

  • Você precisa pesquisar lugares em um servidor com uma consulta de texto (Text Search (novo)) ou em um local (Nearby Search (novo)).
  • Você precisa de previsões de local ou consulta de um back-end usando o Autocomplete (novo).
  • Você tem um ID de lugar e precisa de detalhes como endereço, número de telefone, classificação, avaliações ou fotos.
  • Você precisa de resumos de lugares, avaliações ou regiões gerados com IA para um lugar.

Não use a API Places (nova) quando:

API Places (nova): configuração

Pacotes oficiais da API Places (nova):

  • npm: @googlemaps/places
  • pypi: google-maps-places
  • go: cloud.google.com/go/maps

API Places (nova): erros comuns

  • Problema: o Place Details (novo), o Nearby Search (novo) e o Text Search (novo) não têm uma lista padrão de campos retornados. Solicitações sem uma máscara de campo retornam um erro. Correção: transmita uma máscara de campo de resposta com o parâmetro fields ou $fields ou o cabeçalho X-Goog-FieldMask. Consulte /maps/documentation/places/web-service/choose-fields.
  • Problema: se o token de sessão do Autocomplete (New) for omitido ou reutilizado após o término de uma sessão, cada solicitação será faturada separadamente como SKU: Autocomplete Requests. Correção: gere um novo token de sessão (recomendamos o UUID v4) para cada sessão e encerre-a com uma solicitação do Place Details (New) ou do Address Validation. Consulte /maps/documentation/places/web-service/place-session-tokens.
  • Problema: o código atual ou gerado com IA que chama a API Places (legada) ou a API Maps JavaScript PlacesService em um projeto sem a API legada ativada falha com LegacyApiNotActivatedMapError. Correção: migre as chamadas para a API Places (nova) e inclua a máscara de campo obrigatória. Consulte /maps/legacy#LegacyApiNotActivatedMapError.
  • Problema: os IDs de lugar armazenados podem ficar obsoletos. Os Place Details (New) retornam NOT_FOUND (HTTP 404), e os IDs malformados ou truncados retornam HTTP 400 INVALID_ARGUMENT. Correção: atualize os IDs de lugar armazenados há mais de 12 meses com uma solicitação do Place Details (New) que peça apenas o campo id (sem custo financeiro). Consulte /maps/documentation/places/web-service/place-id#refresh-id.

O que você pode fazer com a API Places (nova)

Consulte os guias vinculados abaixo para cada tarefa ou compare os produtos no Explorador de recursos.

API Places (nova): IA generativa

API Places (nova): Places