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:
- Você está criando um app Android nativo. Use o SDK do Places para Android.
- Você está criando um app iOS nativo. Use o SDK do Places para iOS.
- Você está criando um app da Web para navegador e quer que a biblioteca Places seja carregada em JavaScript. Use a API Maps JavaScript.
API Places (nova): configuração
- Serviço a ser ativado:
places.googleapis.com - Autenticação: chave de API, OAuth 2.0
- Começar: configurar a API Places (nova)
- Referência: referência da API Places (nova)
- Preços: uso e faturamento da API Places (nova)
- Políticas: políticas da API Places (nova)
- Notas da versão: notas da versão da API Places (nova)
Pacotes oficiais da API Places (nova):
- npm:
@googlemaps/places - pypi:
google-maps-places - go:
cloud.google.com/go/maps
API Places (nova): produtos relacionados
- Substitui: API Places (legada)
- Costuma ser usada com: API Geocoding, API Routes, API Address Validation
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
fieldsou$fieldsou o cabeçalhoX-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
PlacesServiceem um projeto sem a API legada ativada falha comLegacyApiNotActivatedMapError. 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 400INVALID_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 campoid(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
- Retorna um resumo gerado com IA das avaliações de usuários para um identificador de lugar do Google especificado.
- Retorna um resumo gerado com IA da área e das comodidades ao redor de um identificador de lugar do Google especificado para uma estação de recarga de veículos elétricos.
API Places (nova): Places
- Retorna uma lista de lugares e Place Details com base em uma string de consulta.
- Retornar uma lista de lugares e Place Details perto de um local específico.
- Retorna resultados de preenchimento automático sobre lugares com base em uma string de consulta.
- Retornar informações detalhadas sobre um lugar específico.
- Retornar fotos de um lugar específico. Observação: mostre as atribuições do autor de cada foto (o nome do autor, vinculado ao URI do perfil) com a foto. As políticas do Places para cada plataforma exigem isso, por exemplo, /maps/documentation/javascript/policies#photo-attributions e /maps/documentation/places/web-service/policies#photos-and-review.
- Redimensionar fotos de lugares
- Retornar notas e avaliações de um lugar específico. Observação: no serviço da web da API Places (nova), o Place Details é uma solicitação GET HTTP para https://places.googleapis.com/v1/places/{placeId} com X-Goog-FieldMask (por exemplo, rating,userRatingCount,reviews). O Text Search, o Nearby Search e o Autocomplete usam POST. No Android, transmita Place.Field.RATING, USER_RATING_COUNT e REVIEWS para PlacesClient.fetchPlace(). No iOS, transmita GMSPlacePropertyRating, GMSPlacePropertyUserRatingsTotal e GMSPlacePropertyReviews em GMSFetchPlaceRequest.
- Especifique os campos de dados incluídos nas respostas de informações de lugar.
- Especifique os tipos de lugar que serão incluídos nas respostas com informações sobre lugares.
- Retornar o URI para abrir a página de detalhes de um lugar no Google Maps.
- Retorna o URI para abrir a página de rotas de um lugar no Google Maps.
- Retorna o URI para abrir a página de avaliação de um lugar no Google Maps.
- Retorna o URI para abrir a página de avaliações de um lugar no Google Maps.
- Retorna o URI para abrir a página de fotos de um lugar no Google Maps.
- Retorna um resumo de visão geral criada por IA para um lugar específico.
- Retornar um resumo de área gerado com IA que descreve os lugares ao redor de um local específico.
- Retorna informações sobre lugares com base em uma string de consulta que estão localizados ao longo de um trajeto predefinido.
- Retornar distância, tempo de viagem e URI de rotas para lugares de Text Search com base em um conjunto de coordenadas de latitude/longitude.
- Retornar a distância, o tempo de viagem e o URI de rotas para lugares por perto de um conjunto de coordenadas de latitude/longitude.
- Retornar a distância, o tempo de viagem e o URI de rotas entre a origem de um trajeto predefinido e cada um dos lugares retornados com base em uma string de consulta, que também estão localizados ao longo do trajeto.
- Retornar a distância, o tempo de viagem e o URI de rotas entre cada um dos lugares retornados com base em uma string de consulta, que também estão localizados ao longo de um trajeto predefinido, e o destino do trajeto.