Pesquisa de local próximo (Novo)

Selecione a plataforma: Android iOS JavaScript Serviço da Web

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".

Observação :o Nearby Search (novo) está disponível no SDK do Places para Android versão 3.5.0 e mais recentes. Para mais informações, consulte Escolher a versão do SDK.

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();
    });

Você pode usar um CancellationToken para tentar cancelar uma solicitação para qualquer uma das classes de solicitação (por exemplo, FetchPlaceRequest). O cancelamento é feito na medida do possível. Quando uma solicitação de cancelamento é emitida, nenhuma resposta é retornada. A emissão de um token de cancelamento NÃO garante que uma solicitação específica será cancelada. Você ainda poderá receber cobranças pela solicitação mesmo que nenhuma resposta seja retornada.

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 objeto Place 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 de Place.Field para o objeto SearchNearbyRequest. 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 e Place.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 e Place.Field.TAKEOUT

  Para definir o parâmetro da lista de campos, chame o método setPlaceFields() ao criar o objeto SearchNearbyRequest.

  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 campos Place.Field.ID e Place.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 objeto SearchNearbyRequest.

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.

  Observação : os valores na Tabela B são retornados apenas na resposta. Não é possível usar os valores da Tabela B como filtro.

  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". Use includedPrimaryTypes e excludedPrimaryTypes 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". Use includedTypes e excludedTypes 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") e excludedPrimaryTypes = 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".

  Se você omitir includedTypes, excludedTypes, includedPrimaryTypes e excludedPrimaryTypes da solicitação, a pesquisa vai retornar lugares para todos os tipos dentro dos limites de restrição de local.

  Para ver um exemplo de como usar includedTypes e excludedTypes, 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 objeto SearchNearbyRequest.

  Tipos excluídos

  Uma lista de tipos de lugar da Tabela A para excluir de uma pesquisa.

  Se você especificar includedTypes (como "school") e excludedTypes (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 dos includedTypes e nenhuma do excludedTypes.

  Se houver algum tipo conflitante, como um tipo que aparece em includedTypes e excludedTypes, um erro INVALID_REQUEST será retornado.

  Para definir o parâmetro de tipos excluídos, chame o método setExcludedTypes() ao criar o objeto SearchNearbyRequest.

  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 objeto SearchNearbyRequest.

  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 e excludedPrimaryTypes, um erro INVALID_ARGUMENT será retornado.

  Para definir o parâmetro de tipos principais excluídos, chame o método setExcludedPrimaryTypes() ao criar o objeto SearchNearbyRequest.

• 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 objeto SearchNearbyRequest.

• 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 objeto SearchNearbyRequest.

• 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 a regionCode, o código do país será omitido de formattedAddress.

  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 objeto SearchNearbyRequest.

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.