Visão geral
Com as funções na biblioteca Places, a API Maps JavaScript permite que seu aplicativo pesquise lugares (definidos nessa API como estabelecimentos, localizações geográficas ou pontos de interesse importantes) em uma área definida, como limites de um mapa ou ao redor de um ponto fixo.
A API Places disponibiliza um recurso de preenchimento automático para que os aplicativos ofereçam pesquisa durante a digitação no campo de busca do Google Maps. Quando alguém começa a digitar um endereço, o preenchimento automático completa o restante. Para mais informações, consulte a documentação de preenchimento automático.
Começar
Se você não conhece a API Maps JavaScript ou o JavaScript, recomendamos estudar o JavaScript e consultar Ter uma chave de API antes de começar.
Ativar APIs
Antes de usar a biblioteca Places na API Maps JavaScript, verifique se ela está ativada no console do Google Cloud, no mesmo projeto configurado para a API Maps JavaScript.
Para saber quais são as APIs ativadas:
- Acesse o console do Google Cloud.
- Clique no botão Selecionar um projeto, escolha o que você configurou para a API Maps JavaScript e selecione Abrir.
- Na lista de APIs do Painel, procure API Places.
- A API Places vai aparecer na lista se já estiver ativada. Se não encontrar, faça o seguinte para ativar a API:
- Na parte de cima da página, selecione ATIVAR APIs E SERVIÇOS para acessar a guia Biblioteca. Outra opção é selecionar Biblioteca no menu lateral esquerdo.
- Pesquise e selecione API Places na lista de resultados.
- Clique em ATIVAR. Quando o processo terminar, a API Places vai aparecer na lista de APIs do Painel.
Carregar a biblioteca
O serviço Places é uma biblioteca independente e separada do código principal da API Maps JavaScript. Carregue essa biblioteca usando o parâmetro libraries
no URL de inicialização da API Maps para usar as funcionalidades dela:
<script async
src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&loading=async&libraries=places&callback=initMap">
</script>
Consulte a Visão geral das bibliotecas para mais informações.
Adicionar a API Places à lista de restrições de chaves de API
Quando você aplica restrições de API às chaves, isso limita o uso da chave de API a uma ou mais APIs ou SDKs. As solicitações para uma API ou SDK associado à chave de API vão ser processadas. Vai ocorrer uma falha caso esses itens não sejam associados. Para restringir o uso de uma chave de API à biblioteca Places, na API Maps JavaScript, faça o seguinte:- Acesse o console do Google Cloud.
- Clique na lista suspensa do projeto e selecione o projeto que contém a chave de API que você quer proteger.
- Clique no botão de menu
e escolha Plataforma Google Maps > Credenciais.
- Na página Credenciais, clique no nome da chave de API que você quer proteger.
- Na página Restringir e renomear a chave de API, defina as restrições:
- Restrições da API
- Selecione Restringir chave.
- Clique em Selecionar APIs e escolha API Maps JavaScript e API Places.
Vai ser preciso ativar a API que não estiver na lista.
- Clique em SALVAR.
Políticas e limites de uso
Cotas
A biblioteca Places compartilha uma cota de utilização com a API Places, conforme descrito na documentação sobre limites de uso dessa API.
Políticas
A biblioteca Places e a API Maps JavaScript precisam ser usadas de acordo com as políticas da API Places.
Place Searches
Com o serviço Places, você realiza os seguintes tipos de pesquisa:
- Find Place from Query (Encontrar lugar pela consulta): retorna um lugar com base em uma consulta de texto, por exemplo, o nome ou o endereço de um lugar.
- Find Place from Phone (Encontrar lugar pelo telefone): retorna um lugar com base em um número de telefone.
- Nearby Search (Pesquisa de locais por perto): retorna uma lista de locais por perto com base na localização da pessoa.
- Text Search (Pesquisa por texto): retorna uma lista de locais por perto com base em uma string de pesquisa, por exemplo, "Pizza".
- Place Details requests (Solicitações do Place Details): retornam mais detalhes sobre um lugar, incluindo avaliações dos usuários.
As informações retornadas podem incluir estabelecimentos, como restaurantes, lojas, escritórios e resultados de "geocodificação" que indicam endereços, áreas políticas (como áreas urbanas e cidades) e outros pontos de interesse.
Solicitações do Find Place
Com uma solicitação do Find Place, você pesquisa um lugar por consulta de texto ou número de telefone. Há dois tipos de solicitações do Find Place:
Find Place from Query
O recurso Find Place from Query recebe uma entrada de texto e retorna um lugar. A entrada pode ser qualquer tipo de dados de lugar, por exemplo, nome ou endereço da empresa. Para fazer uma solicitação "Find Place from Query", chame o método findPlaceFromQuery()
do PlacesService
, que aceita os seguintes parâmetros:
query
(obrigatório) A string de texto em que pesquisar, por exemplo, "restaurante" ou "Rua Principal, 123". Precisa ser o nome, endereço ou categoria de estabelecimentos. Qualquer outro tipo de entrada pode gerar erros e não garante o retorno de resultados válidos. A API Places retorna as correspondências possíveis de acordo com essa string e ordena os resultados com base na relevância.fields
(obrigatório) Um ou mais campos especificando os tipos de dados de lugar a serem retornados.locationBias
(opcional) Coordenadas que definem a área a ser pesquisada. O tipo pode ser:- Um conjunto de coordenadas de latitude/longitude especificadas como LatLngLiteral ou objeto LatLng
- Limites retangulares (dois pares de latitude/longitude ou um objeto LatLngBounds)
- Raio (em metros) centralizado em uma latitude/longitude
Também é necessário transmitir um método de callback para findPlaceFromQuery()
, o que permite processar o objeto de resultados e a resposta google.maps.places.PlacesServiceStatus
.
O exemplo a seguir mostra uma chamada para findPlaceFromQuery()
, pesquisando "Museu de Arte Contemporânea da Austrália" e incluindo os campos name
e geometry
.
var map; var service; var infowindow; function initMap() { var sydney = new google.maps.LatLng(-33.867, 151.195); infowindow = new google.maps.InfoWindow(); map = new google.maps.Map( document.getElementById('map'), {center: sydney, zoom: 15}); var request = { query: 'Museum of Contemporary Art Australia', fields: ['name', 'geometry'], }; var service = new google.maps.places.PlacesService(map); service.findPlaceFromQuery(request, function(results, status) { if (status === google.maps.places.PlacesServiceStatus.OK) { for (var i = 0; i < results.length; i++) { createMarker(results[i]); } map.setCenter(results[0].geometry.location); } }); }Exemplo
Find Place from Phone Number
O serviço "Find Place from Phone Number" recebe um número de telefone e retorna um lugar. Para fazer uma solicitação "Find Place from Phone Number", chame o método findPlaceFromPhoneNumber()
do PlacesService
, que aceita os seguintes parâmetros:
phoneNumber
(obrigatório) Um número de telefone no formato E.164.fields
(obrigatório) Um ou mais campos especificando os tipos de dados de lugar a serem retornados.locationBias
(opcional) Coordenadas que definem a área a ser pesquisada. O tipo pode ser:- Um conjunto de coordenadas de latitude/longitude especificadas como LatLngLiteral ou objeto LatLng
- Limites retangulares (quatro pontos de latitude/longitude ou um objeto LatLngBounds)
- Raio (em metros) centralizado em uma latitude/longitude
Também é necessário transmitir um método de callback para findPlaceFromPhoneNumber()
, o que permite processar o objeto de resultados e a resposta google.maps.places.PlacesServiceStatus
.
Campos (métodos Find Place)
Use o parâmetro fields
para especificar uma matriz de tipos de dados de lugar a serem retornados.
Exemplo: fields: ['formatted_address', 'opening_hours', 'geometry']
.
Use um ponto quando especificar valores compostos. Exemplo: opening_hours.weekday_text
.
Os campos correspondem aos resultados do Place Search e são divididos em três categorias de faturamento: "Basic", "Contact" e "Atmosphere". Os campos "Basic" são faturados na taxa básica e não geram cobranças extras. Os campos "Contact" e "Atmosphere" são faturados em uma taxa maior. Consulte a tabela de preços para mais informações. As atribuições (html_attributions
) são sempre retornadas a cada chamada, independentemente de o campo ter sido solicitado.
Basic
A categoria "Basic" inclui os seguintes campos:
business_status
, formatted_address
, geometry
,
icon
,icon_mask_base_uri
, icon_background_color
,
name
, permanently_closed
(descontinuado),
photos
, place_id
, plus_code
, types
Contact
A categoria "Contact" inclui o campo a seguir:opening_hours
(descontinuado na biblioteca do Places na API Maps JavaScript. Use uma solicitação do Place Details para ver os resultados de
opening_hours
).
Atmosphere
A categoria Atmosphere inclui os seguintes campos:price_level
, rating
, user_ratings_total
Os métodos findPlaceFromQuery()
e findPlaceFromPhoneNumber()
usam os e podem retornar os mesmos campos nas respectivas respostas.
Definir direcionamento de local (métodos Find Place)
Use o parâmetro locationBias
para fazer com que o Find Place favoreça os resultados de uma determinada área. É possível definir locationBias
assim:
Direcionamento dos resultados para uma área específica:
locationBias: {lat: 37.402105, lng: -122.081974}
Defina uma área retangular para pesquisar:
locationBias: {north: 37.41, south: 37.40, east: -122.08, west: -122.09}
Você também pode usar um LatLngBounds.
Defina um raio para pesquisar (em metros) centralizado em uma área específica:
locationBias: {radius: 100, center: {lat: 37.402105, lng: -122.081974}}
Solicitações do Nearby Search
Uma Nearby Search permite pesquisar locais em uma área especificada por palavra-chave ou tipo. Ela precisa sempre incluir um local, que pode ser especificado de duas formas:
-
LatLngBounds
. - uma área circular definida como a combinação da propriedade
location
, especificando o centro do círculo como um objetoLatLng
, e um raio, medido em metros.
Uma pesquisa do Places Nearby é iniciada com uma chamada para o método nearbySearch()
do
PlacesService
, que retorna uma matriz de objetos
PlaceResult
. O método nearbySearch()
substitui o método search()
a partir da versão 3.9.
service = new google.maps.places.PlacesService(map); service.nearbySearch(request, callback);
Esse método recebe solicitações com os seguintes campos:
- Uma das seguintes opções:
bounds
, que precisa ser um Objetogoogle.maps.LatLngBounds
que define o retângulo área de pesquisa. A distância diagonal máxima para os limites área é de aproximadamente 100.000 metros.- um
location
e umradius
. O primeiro usa um objetogoogle.maps.LatLng
e o último usa um número inteiro simples, representando o raio do círculo em metros. O máximo raio permitido é de 50.000 metros. QuandorankBy
for definido como DISTÂNCIA, você vai ter que especificar umlocation
, mas não vai ser possível especificar umradius
oubounds
.
keyword
(opcional): um termo que deve ser comparado com todos os campos disponíveis, inclusive, entre outros, nome, tipo e endereço, avaliações de clientes e outros materiais de terceiros.minPriceLevel
emaxPriceLevel
(opcional): restringe os resultados apenas aos lugares no intervalo especificado. Valores válidos estão no intervalo de 0 (mais barato) a 4 (mais caro).name
descontinuado. Equivalente akeyword
. Os valores nesse campo são combinados com os valores no campokeyword
e transmitidos como parte da mesma string de pesquisa.openNow
(opcional): um valor booleano indicando que o serviço Places precisa retornar somente os locais que estão no horário de funcionamento no momento em que a consulta é enviada. Locais que não especificam horário de funcionamento no banco de dados do Google Places não vão ser retornados se esse parâmetro for incluído na consulta. DefiniropenNow
comofalse
não tem efeito.rankBy
(opcional): especifica a ordem em que os resultados são listados. Valores possíveis:google.maps.places.RankBy.PROMINENCE
(padrão). Essa opção classifica os resultados com base na importância. Dos locais dentro do raio especificado, a classificação vai priorizar os locais com mais destaque. O destaque pode ser afetado pela classificação de um local no índice do Google, pela popularidade global e outros fatores. Quandogoogle.maps.places.RankBy.PROMINENCE
é especificado, o parâmetroradius
é obrigatório.google.maps.places.RankBy.DISTANCE
Essa opção classifica os resultados em ordem crescente de distância dolocation
especificado (obrigatório). Não é possível especificar umbounds
e/ouradius
personalizado se você definirRankBy.DISTANCE
. Quando você especificaRankBy.DISTANCE
, é necessário informar um ou mais parâmetroskeyword
,name
outype
.
type
: restringe os resultados aos lugares correspondentes ao tipo especificado. Só um tipo pode ser especificado (se mais de um tipo for fornecido, todos os outros após a primeira entrada vão ser ignorados). Consulte a lista de tipos compatíveis.
Também é necessário transmitir um método de callback para nearbySearch()
com o objetivo de processar o objeto de resultados e a resposta google.maps.places.PlacesServiceStatus
.
var map; var service; var infowindow; function initialize() { var pyrmont = new google.maps.LatLng(-33.8665433,151.1956316); map = new google.maps.Map(document.getElementById('map'), { center: pyrmont, zoom: 15 }); var request = { location: pyrmont, radius: '500', type: ['restaurant'] }; service = new google.maps.places.PlacesService(map); service.nearbySearch(request, callback); } function callback(results, status) { if (status == google.maps.places.PlacesServiceStatus.OK) { for (var i = 0; i < results.length; i++) { createMarker(results[i]); } } }
Solicitações Text Search
A Pesquisa de texto do Google Places é um serviço da Web que retorna informações sobre um conjunto de locais com base em uma string, por exemplo, "pizza em São Paulo", "loja de sapatos perto do Rio de Janeiro". O serviço responde com uma lista de locais correspondentes à string de texto e a todos os direcionamentos de localização definidos. A resposta da pesquisa inclui uma lista de locais. É possível enviar uma solicitação de Place Details para mais informações sobre qualquer um dos locais na resposta.
As pesquisas de texto são iniciadas com uma chamada para o método textSearch()
do PlacesService
.
service = new google.maps.places.PlacesService(map); service.textSearch(request, callback);
Esse método recebe solicitações com os seguintes campos:
query
(obrigatório) A string de texto em que pesquisar, por exemplo, "restaurante" ou "Rua Principal, 123". Precisa ser o nome, endereço ou categoria de estabelecimentos. Qualquer outro tipo de entrada pode gerar erros e não garante o retorno de resultados válidos. O serviço Places retorna as correspondências possíveis de acordo com essa string e ordena os resultados com base na relevância. Esse parâmetro se torna opcional se o parâmetrotype
também é usado na solicitação de pesquisa.- Opcionalmente:
openNow
: um valor booleano indicando que o serviço Places precisa retornar somente os locais que estão no horário de funcionamento no momento em que a consulta é enviada. Locais que não especificam horário de funcionamento no banco de dados do Google Places não vão ser retornados se esse parâmetro for incluído na consulta. DefiniropenNow
comofalse
não tem efeito.minPriceLevel
emaxPriceLevel
: restringe os resultados apenas a lugares no nível de preço especificado. Valores válidos estão no intervalo de 0 (mais barato) a 4 (mais caro).- Uma das seguintes opções:
bounds
, que precisa ser um Objetogoogle.maps.LatLngBounds
que define o retângulo área de pesquisa. A distância diagonal máxima para os limites área é de aproximadamente 100.000 metros.- Um
location
e umradius
: você pode influenciar os resultados de um círculo especificado ao transmitir um parâmetrolocation
eradius
. Isso vai instruir o serviço Places para mostrar preferencialmente os resultados dentro desse círculo. Os resultados fora da área definida ainda podem ser exibidos. O local usa um objetogoogle.maps.LatLng
, e o raio recebe um número inteiro simples, representando o raio do círculo em metros. O raio máximo permitido é de 50.000 metros.
type
: restringe os resultados aos lugares correspondentes ao tipo especificado. Só um tipo pode ser especificado (se mais de um tipo for fornecido, todos os outros após a primeira entrada vão ser ignorados). Veja a lista de tipos compatíveis.
Também é necessário transmitir um método de callback para textSearch()
com o objetivo de processar o objeto de resultados e a resposta google.maps.places.PlacesServiceStatus
.
var map; var service; var infowindow; function initialize() { var pyrmont = new google.maps.LatLng(-33.8665433,151.1956316); map = new google.maps.Map(document.getElementById('map'), { center: pyrmont, zoom: 15 }); var request = { location: pyrmont, radius: '500', query: 'restaurant' }; service = new google.maps.places.PlacesService(map); service.textSearch(request, callback); } function callback(results, status) { if (status == google.maps.places.PlacesServiceStatus.OK) { for (var i = 0; i < results.length; i++) { var place = results[i]; createMarker(results[i]); } } }
Respostas de pesquisa
Códigos de status
O objeto de resposta PlacesServiceStatus
contém o status da solicitação e pode conter informações de depuração para ajudar a rastrear o motivo da falha da solicitação de lugar. Os valores de status possíveis são:
INVALID_REQUEST
: esta solicitação era inválida.OK
: a resposta contém um resultado válido.OVER_QUERY_LIMIT
: a página excedeu sua cota de solicitações.REQUEST_DENIED
: a página não tem permissão para usar PlacesService.UNKNOWN_ERROR
: a solicitação de PlacesService não foi processada devido a um erro de servidor. Se você tentar novamente, a solicitação poderá dar certo.ZERO_RESULTS
: nenhum resultado foi encontrado para esta solicitação.
Resultados de Place Search
As funções findPlace()
, nearbySearch()
e textSearch()
retornam uma matriz de objetos PlaceResult
.
Cada objeto PlaceResult
pode incluir as seguintes propriedades:
business_status
indica o status operacional do lugar, se for uma empresa, e pode conter um dos seguintes valores:OPERATIONAL
CLOSED_TEMPORARILY
CLOSED_PERMANENTLY
business_status
não vai ser retornado.formatted_address
é uma string que contém o endereço legível do local. A propriedadeformatted_address
só é retornada para uma Pesquisa de texto.Esse endereço costuma ser equivalente ao endereço postal. Alguns países, como o Reino Unido, não permitem a distribuição de endereços postais verdadeiros devido a restrições de licenciamento.
O endereço formatado é composto de maneira lógica por um ou mais componentes de endereço. Por exemplo, o endereço "Avenida Paulista, 111, São Paulo, SP" consiste nos seguintes componentes: "Avenida Paulista" (o trajeto), "111" (o número), "São Paulo" (a cidade) e "SP" (o estado brasileiro).
Não analise o endereço formatado de maneira programática. Em vez disso, use os componentes de endereço individuais, que a resposta da API inclui, além do campo de endereço formatado.
geometry
: informações relacionadas à geometria do local. Isso inclui o seguinte:location
informa a latitude e a longitude do local.viewport
define a janela de visualização preferida no mapa ao visualizar este local.
permanently_closed
(descontinuado) é uma sinalização booleana que indica se o lugar foi encerrado de forma permanente ou temporária (valortrue
). Não usepermanently_closed
. Em vez disso, usebusiness_status
para ver o status de funcionamento das empresas.plus_code
(consulte Open Location Code e Plus Codes; links em inglês) é uma referência de local codificada, derivada de coordenadas de latitude e longitude, que representa uma área: 1/8000 de um grau por 1/8000 de um grau (aproximadamente 14m x 14m na Linha do Equador) ou menor. Os Plus Codes podem ser usados em vez de endereços nos lugares em que não existem, ou seja, quando os imóveis não estão numerados ou as ruas não têm nome.O Plus Code é formatado como um código global e um composto:
global_code
é um código de área com quatro caracteres e um código local com, pelo menos, seis caracteres (849VCWC8+R9).compound_code
é um código local com, pelo menos, seis caracteres e um local explícito (CWC8+R9, Mountain View, CA, EUA). Não analise esse conteúdo de forma programática.
html_attributions
: uma matriz de atribuições que precisam aparecer com os resultados da pesquisa. Cada entrada na matriz contém o texto HTML para uma única atribuição. Observação: esta é uma agregação de todas as atribuições para toda a resposta da pesquisa. Todos os objetosPlaceResult
na resposta, portanto, contêm listas de atribuição idênticas.icon
retorna o URL de um ícone PNG colorido de 71 x 71 pixels.icon_mask_base_uri
retorna o URL base de um ícone não colorido, menos a extensão .svg ou .png.icon_background_color
retorna o código de cor hexadecimal padrão para a categoria do local.name
: o nome do local.opening_hours
pode conter as seguintes informações:open_now
é um valor booleano que indica se o local está aberto no momento (descontinuado na biblioteca Places, na API Maps JavaScript, useutc_offset_minutes
).
place_id
é um identificador textual que determina um local de forma exclusiva. Para recuperar informações sobre o local, transmita esse identificador na solicitação do Place Details. Saiba mais sobre como fazer referência a um local com o respectivo ID.rating
contém a nota do lugar (0,0 a 5,0), com base nas avaliações de usuários agregadas.types
: uma matriz de tipos para esse lugar (por exemplo,["political", "locality"]
ou["restaurant", "lodging"]
). Essa matriz pode conter diversos valores ou estar vazia. Novos valores podem ser adicionados sem aviso prévio. Consulte a lista de tipos compatíveis.vicinity
: um endereço simplificado para o local, incluindo o nome da rua, o número da rua e a localidade, mas não província/estado, código postal ou país. Por exemplo, o escritório do Google em Sydney, na Austrália, tem um valor de5/48 Pirrama Road, Pyrmont
devicinity
.
Acesso a resultados adicionais
Por padrão, cada pesquisa de local retorna até 20 resultados por consulta. No entanto, cada pesquisa pode retornar até 60 resultados, divididos em três páginas.
Páginas adicionais estão disponíveis no objeto PlaceSearchPagination
. Para acessar outras páginas, é necessário capturar o objeto PlaceSearchPagination
usando uma função de callback. O objeto PlaceSearchPagination
é definido como:
hasNextPage
é uma propriedade booleana que indica se outros resultados estão disponíveis.true
é usado quando há uma página de resultados adicionais.nextPage()
é uma função que retorna o próximo conjunto de resultados. Após a execução de uma pesquisa, é necessário aguardar dois segundos antes que a próxima página de resultados fique disponível.
Para ver o próximo conjunto de resultados, chame nextPage
.
Cada página de resultados precisa ser mostrada antes da próxima. Cada pesquisa conta como uma única solicitação em relação aos limites de uso.
O exemplo a seguir demonstra como mudar a função de callback para capturar o objeto PlaceSearchPagination
, permitindo enviar várias solicitações de pesquisa.
TypeScript
// This example requires the Places library. Include the libraries=places // parameter when you first load the API. For example: // <script src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&libraries=places"> function initMap(): void { // Create the map. const pyrmont = { lat: -33.866, lng: 151.196 }; const map = new google.maps.Map( document.getElementById("map") as HTMLElement, { center: pyrmont, zoom: 17, mapId: "8d193001f940fde3", } as google.maps.MapOptions ); // Create the places service. const service = new google.maps.places.PlacesService(map); let getNextPage: () => void | false; const moreButton = document.getElementById("more") as HTMLButtonElement; moreButton.onclick = function () { moreButton.disabled = true; if (getNextPage) { getNextPage(); } }; // Perform a nearby search. service.nearbySearch( { location: pyrmont, radius: 500, type: "store" }, ( results: google.maps.places.PlaceResult[] | null, status: google.maps.places.PlacesServiceStatus, pagination: google.maps.places.PlaceSearchPagination | null ) => { if (status !== "OK" || !results) return; addPlaces(results, map); moreButton.disabled = !pagination || !pagination.hasNextPage; if (pagination && pagination.hasNextPage) { getNextPage = () => { // Note: nextPage will call the same handler function as the initial call pagination.nextPage(); }; } } ); } function addPlaces( places: google.maps.places.PlaceResult[], map: google.maps.Map ) { const placesList = document.getElementById("places") as HTMLElement; for (const place of places) { if (place.geometry && place.geometry.location) { const image = { url: place.icon!, size: new google.maps.Size(71, 71), origin: new google.maps.Point(0, 0), anchor: new google.maps.Point(17, 34), scaledSize: new google.maps.Size(25, 25), }; new google.maps.Marker({ map, icon: image, title: place.name!, position: place.geometry.location, }); const li = document.createElement("li"); li.textContent = place.name!; placesList.appendChild(li); li.addEventListener("click", () => { map.setCenter(place.geometry!.location!); }); } } } declare global { interface Window { initMap: () => void; } } window.initMap = initMap;
JavaScript
// This example requires the Places library. Include the libraries=places // parameter when you first load the API. For example: // <script src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&libraries=places"> function initMap() { // Create the map. const pyrmont = { lat: -33.866, lng: 151.196 }; const map = new google.maps.Map(document.getElementById("map"), { center: pyrmont, zoom: 17, mapId: "8d193001f940fde3", }); // Create the places service. const service = new google.maps.places.PlacesService(map); let getNextPage; const moreButton = document.getElementById("more"); moreButton.onclick = function () { moreButton.disabled = true; if (getNextPage) { getNextPage(); } }; // Perform a nearby search. service.nearbySearch( { location: pyrmont, radius: 500, type: "store" }, (results, status, pagination) => { if (status !== "OK" || !results) return; addPlaces(results, map); moreButton.disabled = !pagination || !pagination.hasNextPage; if (pagination && pagination.hasNextPage) { getNextPage = () => { // Note: nextPage will call the same handler function as the initial call pagination.nextPage(); }; } }, ); } function addPlaces(places, map) { const placesList = document.getElementById("places"); for (const place of places) { if (place.geometry && place.geometry.location) { const image = { url: place.icon, size: new google.maps.Size(71, 71), origin: new google.maps.Point(0, 0), anchor: new google.maps.Point(17, 34), scaledSize: new google.maps.Size(25, 25), }; new google.maps.Marker({ map, icon: image, title: place.name, position: place.geometry.location, }); const li = document.createElement("li"); li.textContent = place.name; placesList.appendChild(li); li.addEventListener("click", () => { map.setCenter(place.geometry.location); }); } } } window.initMap = initMap;
Testar amostra
Place Details
Além de fornecer uma lista de locais dentro de uma área, o serviço Places também pode retornar informações detalhadas sobre um local específico. Depois que um local é retornado em uma resposta de pesquisa de local, seu ID de lugar pode ser usado para pedir mais detalhes, como endereço completo, telefone, classificações e avaliações de usuários.
Solicitações do Place Details
Place Details são solicitados com uma chamada ao método getDetails()
do serviço.
service = new google.maps.places.PlacesService(map); service.getDetails(request, callback);
Esse método recebe uma solicitação com o placeId
do lugar e campos que indicam quais tipos de dados do Places retornar. Saiba mais sobre como fazer referência a um local com o respectivo ID.
Ele também recebe um método de callback, que precisa lidar com o código de status transmitido na resposta google.maps.places.PlacesServiceStatus
, além do objeto google.maps.places.PlaceResult
.
var request = { placeId: 'ChIJN1t_tDeuEmsRUsoyG83frY4', fields: ['name', 'rating', 'formatted_phone_number', 'geometry'] }; service = new google.maps.places.PlacesService(map); service.getDetails(request, callback); function callback(place, status) { if (status == google.maps.places.PlacesServiceStatus.OK) { createMarker(place); } }
Fields (detalhes do lugar)
O parâmetrofields
usa uma matriz de strings (nomes de campo).
Use o parâmetro fields
para especificar uma matriz de tipos de dados de lugar a serem retornados.
Exemplo: fields: ['address_components', 'opening_hours', 'geometry']
.
Use um ponto quando especificar valores compostos. Exemplo: opening_hours.weekday_text
.
Os campos correspondem aos resultados do Place Details e são divididos em três categorias de faturamento: "Basic", "Contact" e "Atmosphere". Os campos "Basic" são faturados na taxa básica e não geram cobranças extras. Os campos "Contact" e "Atmosphere" são faturados em uma taxa maior. Consulte a tabela de preços para mais informações. As atribuições (html_attributions
) são sempre retornadas a cada chamada, independente de terem sido solicitadas.
Basic
A categoria "Basic" inclui os seguintes campos:
address_components
,adr_address
,business_status
,
formatted_address
,geometry
,icon
,
icon_mask_base_uri
,icon_background_color
,name
,
permanently_closed
(descontinuado)photo
,place_id
,plus_code
,type
,
url
,utc_offset
(descontinuado na biblioteca Places, na API Maps JavaScript),utc_offset_minutes
,
vicinity
Contact
A categoria "Contact" inclui os seguintes campos:
formatted_phone_number
, international_phone_number
,opening_hours
e website
.
Atmosphere
A categoria "Atmosphere" inclui os seguintes campos:
price_level
, rating
, reviews
,
user_ratings_total
Saiba mais sobre os campos de local. Para mais informações sobre como as solicitações de dados de lugar são faturadas, consulte Uso e faturamento.
Respostas do Place Details
Códigos de status
O objeto de resposta PlacesServiceStatus
contém o status da solicitação e pode conter informações de depuração que ajudam a rastrear o motivo da falha na solicitação do Place Details. Os valores de status possíveis são:
INVALID_REQUEST
: esta solicitação era inválida.OK
: a resposta contém um resultado válido.OVER_QUERY_LIMIT
: a página excedeu sua cota de solicitações.NOT_FOUND
: o local indicado não foi encontrado no banco de dados do Places.REQUEST_DENIED
: a página não tem permissão para usar PlacesService.UNKNOWN_ERROR
: a solicitação de PlacesService não foi processada devido a um erro de servidor. Se você tentar novamente, a solicitação poderá dar certo.ZERO_RESULTS
: nenhum resultado foi encontrado para esta solicitação.
Resultados do Place Details
Uma chamada getDetails()
que funciona retorna um objeto PlaceResult
com as seguintes propriedades:
address_components
: uma matriz contendo os componentes separados aplicáveis a esse endereço.Normalmente, cada componente de endereço contém os seguintes campos:
types[]
é uma matriz que indica o tipo do componente de endereço. Consulte a lista de tipos compatíveis.long_name
é a descrição completa em texto ou o nome do componente do endereço retornado pelo geocodificador.short_name
é um nome abreviado, no formato de texto, para o componente de endereço, se estiver disponível. Por exemplo, um componente de endereço para o estado do Alasca pode ter umlong_name
de "Alaska" e umshort_name
de "AK", usando a abreviação postal de 2 letras.
Observe os seguintes fatos sobre a matriz
address_components[]
:- A matriz de componentes de endereço pode conter mais componentes do que
formatted_address
. - A matriz não inclui necessariamente todas as entidades políticas que contêm um endereço, além daquelas incluídas em
formatted_address
. Para recuperar todas as entidades políticas que contêm um endereço específico, use a geocodificação inversa, transmitindo a latitude/longitude do endereço como um parâmetro para a solicitação. - Não há garantia de que o formato da resposta vai permanecer o mesmo entre as solicitações. Especificamente, o número de
address_components
varia de acordo com o endereço solicitado e pode mudar para o mesmo endereço. Um componente pode mudar a posição na matriz. O tipo do componente pode mudar. Pode faltar um componente específico em uma resposta posterior.
business_status
indica o status operacional do lugar, se for uma empresa, e pode conter um dos seguintes valores:OPERATIONAL
CLOSED_TEMPORARILY
CLOSED_PERMANENTLY
business_status
não vai ser retornado.formatted_address
: o endereço legível do lugar.Esse endereço costuma ser equivalente ao endereço postal. Alguns países, como o Reino Unido, não permitem a distribuição de endereços postais verdadeiros devido a restrições de licenciamento.
O endereço formatado é composto de maneira lógica por um ou mais componentes de endereço. Por exemplo, o endereço "Avenida Paulista, 111, São Paulo, SP" consiste nos seguintes componentes: "Avenida Paulista" (o trajeto), "111" (o número), "São Paulo" (a cidade) e "SP" (o estado brasileiro).
Não analise o endereço formatado de maneira programática. Em vez disso, use os componentes de endereço individuais, que a resposta da API inclui, além do campo de endereço formatado.
formatted_phone_number
: o número de telefone do lugar, formatado de acordo com a convenção regional do número.geometry
: informações relacionadas à geometria do local. Isso inclui o seguinte:location
informa a latitude e a longitude do local.viewport
define a janela de visualização preferida no mapa ao visualizar este local.
permanently_closed
(descontinuado) é uma sinalização booleana que indica se o lugar foi encerrado de forma permanente ou temporária (valortrue
). Não usepermanently_closed
. Em vez disso, usebusiness_status
para ver o status de funcionamento das empresas.plus_code
(consulte Open Location Code e Plus Codes; links em inglês) é uma referência de local codificada, derivada de coordenadas de latitude e longitude, que representa uma área: 1/8000 de um grau por 1/8000 de um grau (aproximadamente 14m x 14m na Linha do Equador) ou menor. Os Plus Codes podem ser usados em vez de endereços nos lugares em que não existem, ou seja, quando os imóveis não estão numerados ou as ruas não têm nome.O Plus Code é formatado como um código global e um composto:
global_code
é um código de área com quatro caracteres e um código local com, pelo menos, seis caracteres (849VCWC8+R9).compound_code
é um código local com, pelo menos, seis caracteres e um local explícito (CWC8+R9, Mountain View, CA, EUA). Não analise esse conteúdo de forma programática.
html_attributions
: texto de atribuição a ser exibido para esse resultado de local.icon
: URL de um recurso de imagem que pode ser usado para representar o tipo do local.international_phone_number
: contém o número de telefone do local no formato internacional. O formato internacional inclui o código do país e é prefixado pelo sinal de adição (+). Por exemplo, ointernational_phone_number
do escritório do Google em Sydney, Austrália, é+61 2 9374 4000
.name
: o nome do local.utc_offset
Descontinuado na biblioteca Places, na API Maps JavaScript, useutc_offset_minutes
.utc_offset_minutes
: contém a diferença em minutos entre o fuso horário do lugar em questão e o UTC. Por exemplo, para locais em Sydney, na Austrália, durante o horário de verão, o valor seria 660 (11 horas à frente do UTC) e, para lugares na Califórnia, fora do horário de verão, seria -480 (8 horas atrás do UTC).opening_hours
contém as seguintes informações:open_now
(descontinuado na biblioteca Places, na API Maps JavaScript; use opening_hours.isOpen(). Assista a este vídeo para saber como usarisOpen
com o Place Details.) é um valor booleano, que indica se o lugar está aberto no horário atual.periods[]
: é uma matriz de períodos de funcionamento cobrindo sete dias, começando no domingo, em ordem cronológica. Cada período contém:open
: que contém um par de objetos de dia e hora descrevendo quando o local abre:day
: um número de 0-6, correspondente aos dias da semana, começando no domingo. Por exemplo, 2 significa terça-feira.time
: pode conter uma hora do dia no formato hhmm de 24 horas (valores na faixa de 0000 a 2359). Otime
vai ser relatado no fuso horário do lugar.
close
pode conter um par de objetos de dia e hora que descrevem o horário de fechamento do local. Observação: se um lugar estiver sempre aberto, a seçãoclose
não vai aparecer na resposta. Os aplicativos têm o status de "sempre aberto" representado como um períodoopen
período contendoday
com valor 0 etime
com valor 0000, semclose
.
weekday_text
é uma matriz de sete strings que representam os horários de funcionamento formatados para cada dia da semana. Se um parâmetrolanguage
for especificado na solicitação do Place Details, o serviço Places vai direcionar os resultados para avaliações escritas naquele idioma. A ordem dos elementos nessa matriz depende do parâmetrolanguage
. Alguns idiomas iniciam a semana na segunda-feira e outros no domingo.
permanently_closed
(descontinuado) é uma sinalização booleana que indica se o lugar foi encerrado de forma permanente ou temporária (valortrue
). Não usepermanently_closed
. Em vez disso, usebusiness_status
para ver o status de funcionamento das empresas.photos[]
: uma matriz de objetosPlacePhoto
. UmPlacePhoto
pode ser usado para obter uma foto com o métodogetUrl()
ou você pode examinar o objeto procurando os seguintes valores:height
: a altura máxima da imagem, em pixels.width
: a largura máxima da imagem, em pixels.html_attributions
: texto de atribuição que vai ser mostrado para essa foto do local.
place_id
: um identificador textual que identifica um local de forma exclusiva e pode ser usado para recuperar informações sobre ele com uma solicitação do Place Details. Saiba mais sobre como fazer referência a um local com o respectivo ID.rating
: a nota do lugar (0,0 a 5,0), com base nas avaliações de usuários agregadas.reviews
: uma matriz de até cinco avaliações. Cada uma delas consiste em vários componentes:aspects[]
: contém uma matriz de objetosPlaceAspectRating
, cada uma fornecendo uma classificação de um único atributo do estabelecimento. O primeiro objeto na matriz é considerado o aspecto principal. CadaPlaceAspectRating
é definido como:type
é o nome do aspecto que está sendo avaliado. Os seguintes tipos são aceitos:appeal
,atmosphere
,decor
,facilities
,food
,overall
,quality
eservice
.rating
: avaliação do usuário para este aspecto em particular, entre 0 a 3.
author_name
: o nome do usuário que enviou a avaliação. Comentários anônimos são atribuídos a "Alguém que usa o Google". Se o parâmetro de idioma foi definido, a frase "Alguém que usa o Google" vai retornar uma string localizada.author_url
: o URL para o perfil do Google+ das pessoas, se disponível.language
: um código de idioma IETF indicando o idioma usado na avaliação do usuário. Esse campo contém somente a tag do idioma principal e não a tag secundária indicando o país ou a região. Por exemplo, todas as avaliações em inglês são marcadas como "en", e não "en-AU" ou "en-UK", e assim por diante.rating
: classificação geral do usuário para este lugar. É um número inteiro, de 1 a 5.text
: avaliação do usuário. Ao avaliar um local com o Google Places, as avaliações de texto são opcionais. Portanto, esse campo pode ficar vazio.
types
: uma matriz de tipos para esse lugar (por exemplo,["political", "locality"]
ou["restaurant", "lodging"]
). Essa matriz pode conter diversos valores ou estar vazia. Novos valores podem ser adicionados sem aviso prévio. Consulte a lista de tipos compatíveis.url
: URL da página oficial do Google desse local. Essa é a página do estabelecimento no Google com as melhores informações disponíveis sobre o local. Os aplicativos precisam vincular ou incorporar essa página em todas as telas que mostrem resultados detalhados do local para as pessoas.vicinity
: um endereço simplificado para o local, incluindo o nome da rua, o número da rua e a localidade, mas não província/estado, código postal ou país. Por exemplo, o escritório do Google em Sydney, na Austrália, tem um valor de5/48 Pirrama Road, Pyrmont
devicinity
. A propriedadevicinity
só é retornada para uma Pesquisa nas proximidades.website
: lista o site oficial do lugar, como a página inicial da empresa na Web.
Observação: classificações multidimensionais não estão disponíveis para todos os locais. Se houver poucas avaliações, a resposta de detalhes vai incluir uma avaliação herdada na escala de 0.0 a 5.0 (se disponível) ou nenhuma classificação.
Usar o componente Place Overview
Observação: este exemplo usa uma biblioteca de código aberto. Confira o README para receber suporte e feedback relacionados à biblioteca.
Teste componentes da Web. Use o Componente da Web "Visão geral do lugar" para ver detalhes do lugar com uma representação visual.
![Imagem mostrando as variações de tamanho extra, pequeno, médio, grande e extragrande do
Componente de visão geral do lugar mostrado com base no campo de tamanho inserido pelo usuário.](https://developers-dot-devsite-v2-prod.appspot.com/static/maps/documentation/javascript/images/place-overview-sizes.png?authuser=7&hl=pt)
Fazer referência a um local com um ID de local
Um ID de lugar é uma referência exclusiva a um local em um mapa do Google. Esses IDs estão disponíveis para a maioria dos lugares, incluindo empresas, pontos turísticos, parques e cruzamentos.
Para usar um ID de lugar no app, encontre antes o ID, que está disponível no PlaceResult
retornado por uma solicitação do Place Search ou Details.
Você pode usar esse ID de lugar para procurar no Place Details.
Os IDs de lugares estão isentos das restrições de armazenamento em cache definidas na Seção 3.2.3(b) dos Termos de Serviço da Plataforma Google Maps. Portanto, você pode armazenar os valores desses IDs para usar depois. Para ver as práticas recomendadas na hora de armazenar IDs de lugar, consulte a visão geral de IDs de lugar.
var map; function initialize() { // Create a map centered in Pyrmont, Sydney (Australia). map = new google.maps.Map(document.getElementById('map'), { center: {lat: -33.8666, lng: 151.1958}, zoom: 15 }); // Search for Google's office in Australia. var request = { location: map.getCenter(), radius: '500', query: 'Google Sydney' }; var service = new google.maps.places.PlacesService(map); service.textSearch(request, callback); } // Checks that the PlacesServiceStatus is OK, and adds a marker // using the place ID and location from the PlacesService. function callback(results, status) { if (status == google.maps.places.PlacesServiceStatus.OK) { var marker = new google.maps.Marker({ map: map, place: { placeId: results[0].place_id, location: results[0].geometry.location } }); } } google.maps.event.addDomListener(window, 'load', initialize);
Place Photo (Foto do lugar)
Com o recurso Place Photo, você adiciona fotos de alta qualidade ao seu site. O serviço Photo permite acessar milhões de fotos armazenadas nos bancos de dados de locais do Places e do Google+. Quando você consegue informações de local usando uma solicitação do Place Details, são retornadas referências de fotos para o conteúdo fotográfico relevante. As solicitações de Nearby Search e Text Search também retornam uma única referência de foto por local, quando relevante. Usando o serviço Photo, é possível acessar as fotos referenciadas e redimensionar a imagem de acordo com o tamanho ideal para o aplicativo.
Uma matriz de objetos PlacePhoto
vai ser retornada como parte do objeto PlaceResult
para qualquer solicitação getDetails()
, textSearch()
ou nearbySearch()
feita para um PlacesService
.
Observação: o número de fotos retornadas varia de acordo com a solicitação.
- Uma solicitação de Nearby Search ou Text Search retorna, no máximo, um objeto
PlacePhoto
. - Uma solicitação de Details retorna até dez objetos
PlacePhoto
.
Para solicitar o URL da imagem associada, chame o método PlacePhoto.getUrl()
e transmita um objeto PhotoOptions
válido. O objeto PhotoOptions
permite especificar a altura e a largura máximas da imagem. Se você especificar um valor para maxHeight
e maxWidth
, o serviço de fotos vai redimensionar a imagem para o menor de dois tamanhos que mantenha a proporção da imagem original.
O fragmento de código a seguir aceita um objeto de local e adiciona um marcador ao mapa se existir uma foto. A imagem do marcador padrão é substituída por uma pequena versão da foto.
function createPhotoMarker(place) { var photos = place.photos; if (!photos) { return; } var marker = new google.maps.Marker({ map: map, position: place.geometry.location, title: place.name, icon: photos[0].getUrl({maxWidth: 35, maxHeight: 35}) }); }
Fotos retornadas pelo serviço Photo têm origem em vários locais, inclusive de proprietários de empresas e imagens enviadas pelos usuários. Na maioria dos casos, essas fotos podem ser usadas sem atribuição ou a atribuição necessária vai ser incluída na imagem. No entanto, se o elemento photo
retornado incluir um valor no campo html_attributions
, vai ser necessário incluir a atribuição adicional no aplicativo sempre que você mostrar a imagem.