Uma solicitação de Nearby Search (novo) usa como entrada a região a ser pesquisada especificada como um círculo, definida pelas coordenadas de latitude e longitude do ponto central do círculo e o raio em metros. A solicitação retorna uma lista de lugares correspondentes, cada um representado por um objeto Place
, dentro da área de pesquisa especificada.
Por padrão, a resposta contém locais de todos os tipos na área de pesquisa. Se quiser, filtre a resposta especificando uma lista de tipos de lugar para incluir ou excluir explicitamente. Por exemplo, você pode especificar para incluir na resposta apenas os lugares do tipo "restaurante", "padaria" e "café", ou excluir todos os lugares do tipo "escola".
Solicitações do Nearby Search (novo)
Faça uma solicitação do Nearby Search (novo) chamando PlacesClient.searchNearby
, transmitindo um objeto SearchNearbyRequest
que define os parâmetros da solicitação.
O objeto SearchNearbyRequest
especifica todos os parâmetros obrigatórios e opcionais
para a solicitação. Os parâmetros obrigatórios incluem:
- A lista de campos a serem retornados no objeto
Place
, também conhecido como máscara de campo. Se você não especificar pelo menos um campo na lista ou omitir a lista, a chamada retornará um erro. - A restrição de local para a área de pesquisa, definida como um par de latitude/longitude e valor de raio, em metros.
Este exemplo de solicitação de pesquisa por perto especifica que os objetos Place
de resposta contêm os campos de lugar Place.Field.ID
e Place.Field.NAME
para cada objeto Place
nos resultados da pesquisa. Ele também filtra a resposta para retornar apenas lugares dos tipos "restaurante" e "café", mas exclui lugares do tipo "pizza_restaurante" e "american_restaurante".
// Define a list of fields to include in the response for each returned place. final List<Place.Field> placeFields = Arrays.asList(Place.Field.ID, Place.Field.NAME); // Define the search area as a 1000 meter diameter circle in New York, NY. LatLng center = new LatLng(40.7580, -73.9855); CircularBounds circle = CircularBounds.newInstance(center, /* radius = */ 1000); // Define a list of types to include. final List<String> includedTypes = Arrays.asList("restaurant", "cafe"); // Define a list of types to exclude. final List<String> excludedTypes = Arrays.asList("pizza_restaurant", "american_restaurant"); // Use the builder to create a SearchNearbyRequest object. final SearchNearbyRequest searchNearbyRequest = SearchNearbyRequest.builder(/* location restriction = */ circle, placeFields) .setIncludedTypes(includedTypes) .setExcludedTypes(excludedTypes) .setMaxResultCount(10) .build()); // Call placesClient.searchNearby() to perform the search. // Define a response handler to process the returned List of Place objects. placesClient.searchNearby(searchNearbyRequest) .addOnSuccessListener(response -> { List<Place> places = response.getPlaces(); });
Respostas do Nearby Search (novo)
A classe SearchNearbyResponse
representa a resposta de uma solicitação de pesquisa. Um objeto SearchNearbyResponse
contém:
- Uma lista de objetos
Place
que representam todos os lugares correspondentes, com um objetoPlace
por lugar correspondente. - Cada objeto
Place
contém apenas os campos definidos pela lista de campos transmitida na solicitação.
Por exemplo, na solicitação, você definiu uma lista de campos como:
// Define a list of fields to include in the response for each returned place. final List<Place.Field> placeFields = Arrays.asList(Place.Field.ID, Place.Field.NAME);
Essa lista de campos significa que cada objeto Place
na resposta contém apenas o ID e o nome de cada lugar correspondente. É possível usar os métodos Place.getId()
e Place.getName()
para acessar esses campos em cada objeto Place
.
Para mais exemplos de como acessar dados em um objeto Place
, consulte Acessar campos de dados do objeto Place.
Parâmetros obrigatórios
Use o objeto SearchNearbyRequest
para especificar os parâmetros necessários para a pesquisa.
Lista de campos
Ao solicitar detalhes sobre o lugar, especifique os dados a serem retornados no objeto
Place
dele como uma máscara de campo. Para definir a máscara de campo, transmita uma matriz de valores dePlace.Field
para o objetoSearchNearbyRequest
. 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 e tempo de processamento desnecessários.Especifique um ou mais dos seguintes campos:
Os campos a seguir acionam a SKU Nearby Search (Basic):
Place.Field.ADDRESS_COMPONENTS
,Place.Field.BUSINESS_STATUS
,Place.Field.ADDRESS
,Place.Field.ICON_BACKGROUND_COLOR
,Place.Field.ICON_URL
,Place.Field.LAT_LNG
,Place.Field.PHOTO_METADATAS
,Place.Field.PLUS_CODE
,Place.Field.ID
,Place.Field.NAME
,Place.Field.TYPES
,Place.Field.UTC_OFFSET
,Place.Field.VIEWPORT
ePlace.Field.WHEELCHAIR_ACCESSIBLE_ENTRANCE
Os campos a seguir acionam a SKU Nearby Search (Advanced):
Place.Field.CURRENT_OPENING_HOURS
,Place.Field.SECONDARY_OPENING_HOURS
,Place.Field.PHONE_NUMBER
,Place.Field.PRICE_LEVEL
,Place.Field.RATING
,Place.Field.OPENING_HOURS
,Place.Field.USER_RATINGS_TOTAL
,Place.Field.WEBSITE_URI
Os campos a seguir acionam a SKU Nearby Search (Preferencial):
Place.Field.CURBSIDE_PICKUP
,Place.Field.DELIVERY
,Place.Field.DINE_IN
,Place.Field.EDITORIAL_SUMMARY
,Place.Field.RESERVABLE
,Place.Field.REVIEWS
,Place.Field.SERVES_BEER
,Place.Field.SERVES_BREAKFAST
,Place.Field.SERVES_BRUNCH
,Place.Field.SERVES_DINNER
,Place.Field.SERVES_LUNCH
,Place.Field.SERVES_VEGETARIAN_FOOD
,Place.Field.SERVES_WINE
ePlace.Field.TAKEOUT
Para definir o parâmetro da lista de campos, chame o método
setPlaceFields()
ao criar o objetoSearchNearbyRequest
.O exemplo a seguir define uma lista de dois valores de campo para especificar que o objeto
Place
retornado por uma solicitação contém os camposPlace.Field.ID
ePlace.Field.NAME
:
// Define a list of fields to include in the response for each returned place. final List<Place.Field> placeFields = Arrays.asList(Place.Field.ID, Place.Field.NAME);
Restrição de local
Um objeto
LocationRestriction
que define a região a ser pesquisada especificada como um círculo, definido pelo ponto central e pelo raio em metros. O raio precisa estar entre maior que 0,0 e menor ou igual a 50.000,0.Lembre-se de que especificar um raio muito pequeno retornaráZERO_RESULTS
como resposta.Para definir o parâmetro de restrição de local, chame o método
setLocationRestriction()
ao criar o objetoSearchNearbyRequest
.
Parâmetros opcionais
Use o objeto SearchNearbyRequest
para especificar os parâmetros opcionais da pesquisa.
-
Tipos e tipos principais
Permite especificar uma lista de tipos dos tipos da Tabela A usados para filtrar os resultados da pesquisa. Até 50 tipos podem ser especificados em cada categoria de restrição.
Um lugar só pode ter um único tipo principal dos tipos da Tabela A associados a ele. Por exemplo, o tipo principal pode ser
"mexican_restaurant"
ou"steak_house"
. UseincludedPrimaryTypes
eexcludedPrimaryTypes
para filtrar os resultados com base no tipo principal de um lugar.Um lugar também pode ter vários valores de tipo dos tipos da Tabela A associados a ele. Por exemplo, um restaurante pode ter os seguintes tipos:
"seafood_restaurant"
,"restaurant"
,"food"
,"point_of_interest"
,"establishment"
. UseincludedTypes
eexcludedTypes
para filtrar os resultados na lista de tipos associados a um lugar.Se uma pesquisa for especificada com várias restrições de tipo, apenas lugares que atenderem a todas elas serão retornados. Por exemplo, se você especificar
includedTypes = Arrays.asList("restaurant")
eexcludedPrimaryTypes = Arrays.asList("steak_house")
, os lugares retornados vão fornecer serviços relacionados a"restaurant"
, mas não vão funcionar principalmente como um"steak_house"
.Para ver um exemplo de como usar
includedTypes
eexcludedTypes
, consulte Solicitações de Nearby Search (novo).Tipos incluídos
Uma lista dos tipos de lugar da Tabela A para pesquisar. Se esse parâmetro for omitido, lugares de todos os tipos serão retornados.
Para definir o parâmetro de tipos incluídos, chame o método
setIncludedTypes()
ao criar o objetoSearchNearbyRequest
.Tipos excluídos
Uma lista de tipos de lugar da Tabela A para excluir de uma pesquisa.
Se você especificar
includedTypes
(como"school"
) eexcludedTypes
(como"primary_school"
) na solicitação, a resposta incluirá locais categorizados como"school"
, mas não como"primary_school"
. A resposta inclui locais que correspondem a pelo menos um dosincludedTypes
e nenhuma doexcludedTypes
.Se houver algum tipo conflitante, como um tipo que aparece em
includedTypes
eexcludedTypes
, um erroINVALID_REQUEST
será retornado.Para definir o parâmetro de tipos excluídos, chame o método
setExcludedTypes()
ao criar o objetoSearchNearbyRequest
.Tipos principais incluídos
Uma lista dos principais tipos de lugar da Tabela A para incluir em uma pesquisa.
Para definir o parâmetro de tipos principais incluído, chame o método
setIncludedPrimaryTypes()
ao criar o objetoSearchNearbyRequest
.Tipos principais excluídos
Uma lista dos principais tipos de lugares da Tabela A para excluir de uma pesquisa.
Se houver algum tipo principal conflitante, como um tipo que aparece em
includedPrimaryTypes
eexcludedPrimaryTypes
, um erroINVALID_ARGUMENT
será retornado.Para definir o parâmetro de tipos principais excluídos, chame o método
setExcludedPrimaryTypes()
ao criar o objetoSearchNearbyRequest
. -
Contagem máxima de resultados
Especifica o número máximo de resultados de lugar a serem retornados. Precisa estar entre 1 e 20 (padrão).
Para definir o parâmetro de contagem máxima de resultados, chame o método
setMaxResultCount()
ao criar o objetoSearchNearbyRequest
. -
Preferência de classificação
O tipo de classificação a ser usado. Se esse parâmetro for omitido, os resultados serão classificados por popularidade. Pode ser uma das seguintes opções:
POPULARITY
(padrão) classifica os resultados com base na popularidade.DISTANCE
Classifica os resultados em ordem crescente de distância do local especificado.
Para definir o parâmetro de preferência de classificação, chame o método
setRankPreference()
ao criar o objetoSearchNearbyRequest
. -
Código de região
O código da região usado para formatar a resposta, especificado como um valor de código CLDR de dois caracteres. Não há valor padrão.
Se o nome do país do campo
formattedAddress
na resposta corresponder aregionCode
, o código do país será omitido deformattedAddress
.A maioria dos códigos CLDR é idêntica aos códigos ISO 3166-1, com algumas exceções notáveis. Por exemplo, o ccTLD do Reino Unido é "uk" (.co.uk), enquanto o código ISO 3166-1 é "gb" (tecnicamente para a entidade "Reino Unido da Grã-Bretanha e Irlanda do Norte"). O parâmetro pode afetar os resultados com base na legislação aplicável.
Para definir o parâmetro do código da região, chame o método
setRegionCode()
ao criar o objetoSearchNearbyRequest
.
Exibir atribuições no seu aplicativo
Quando o app exibe informações coletadas em
PlacesClient
,
como fotos e avaliações, ele também precisa mostrar as atribuições necessárias.
Para mais informações, consulte Políticas do SDK do Places para Android.