Nearby Search (novo)

Selecione a plataforma: Android iOS JavaScript Web Service

Uma solicitação de pesquisa Nearby (nova) usa como entrada a região a ser pesquisada especificada como um círculo, definido 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 na área de pesquisa especificada.

Por padrão, a resposta contém lugares de todos os tipos na área de pesquisa. Você pode filtrar a resposta especificando uma lista de tipos de lugar para incluir ou excluir explicitamente da resposta. Por exemplo, é possível especificar que a resposta deve incluir apenas lugares do tipo "restaurante", "padaria" e "café" ou excluir todos os lugares do tipo "escola".

Observação: a Pesquisa nas proximidades (nova) 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. Para mais informações sobre o uso das APIs do Kotlin adicionadas na versão 4.0.0, consulte a Visão geral de referência.

Solicitações do Nearby Search (novo)

Faça uma solicitação de pesquisa do Nearby (nova) 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 da 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 de campos ou se omitir a lista de campos, a chamada vai retornar um erro.
• A restrição de local para a área de pesquisa, definida como um par de latitude/longitude e um valor de raio, em metros.

Este exemplo de solicitação de pesquisa nas proximidades especifica que os objetos Place da resposta contêm os campos de lugar Place.Field.ID e Place.Field.DISPLAY_NAME para cada objeto Place nos resultados da pesquisa. Ele também filtra a resposta para retornar apenas lugares do tipo "restaurante" e "café", mas exclui lugares do tipo "pizza_restaurant" e "american_restaurant".

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

Observação:para mais informações sobre como inicializar PlacesClient, consulte Inicializar o cliente da API Places.

É possível usar um CancellationToken para tentar cancelar uma solicitação para qualquer uma das classes de solicitação (por exemplo, FetchPlaceRequest). O cancelamento é feito da melhor forma possível. Depois que uma solicitação de cancelamento é emitida, nenhuma resposta é retornada. Emitir um token de cancelamento NÃO garante que uma solicitação específica seja cancelada, e você ainda pode ser cobrado 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 do lugar correspondente. Em seguida, use os métodos Place.getId() e Place.getName() para acessar esses campos em cada objeto Place.

Para mais exemplos de acesso a dados em um objeto Place, consulte Acessar campos de dados de objetos do 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 do lugar, você precisa especificar os dados a serem retornados no objeto Place do lugar 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 boa prática de design para garantir que você não solicite dados desnecessários, o que ajuda a evitar tempos de processamento e cobrança desnecessários.

  Especifique um ou mais dos seguintes campos:

  • Os campos a seguir acionam o SKU do produto de pesquisa por proximidade:

    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.PRIMARY_TYPE
Place.Field.PRIMARY_TYPE_DISPLAY_NAME
Place.Field.ID
Place.Field.NAME
Place.Field.TYPES
Place.Field.UTC_OFFSET
Place.Field.VIEWPORT
Place.Field.WHEELCHAIR_ACCESSIBLE_ENTRANCE

  • Os campos a seguir acionam o SKU do Enterprise do Nearby Search:

    Place.Field.CURRENT_OPENING_HOURS
Place.Field.CURRENT_SECONDARY_OPENING_HOURS
Place.Field.INTERNATIONAL_PHONE_NUMBER
Place.Field.NATIONAL_PHONE_NUMBER
Place.Field.OPENING_HOURS
Place.Field.PRICE_LEVEL
Place.Field.RATING
Place.Field.SECONDARY_OPENING_HOURS
Place.Field.USER_RATING_COUNT
Place.Field.WEBSITE_URI
    
    Campos descontinuados:os campos Place.Field.PHONE_NUMBER e Place.Field.USER_RATINGS_TOTAL foram descontinuados na versão 4.0 do SDK do Places para Android. Em vez disso, use Place.Field.INTERNATIONAL_PHONE_NUMBER e Place.USER_RATING_COUNT, respectivamente.

  • Os campos a seguir acionam a SKU Enterprise Plus da Pesquisa Nearby:

    Place.Field.ALLOWS_DOGS
Place.Field.CURBSIDE_PICKUP
Place.Field.DELIVERY
Place.Field.DINE_IN
Place.Field.EDITORIAL_SUMMARY
Place.Field.EV_CHARGE_OPTIONS
Place.Field.FUEL_OPTIONS
Place.Field.GOOD_FOR_CHILDREN
Place.Field.GOOD_FOR_GROUPS
Place.Field.GOOD_FOR_WATCHING_SPORTS
Place.Field.LIVE_MUSIC
Place.Field.MENU_FOR_CHILDREN
Place.Field.OUTDOOR_SEATING
Place.Field.PARKING_OPTIONS
Place.Field.PAYMENT_OPTIONS
Place.Field.RESERVABLE
Place.Field.RESTROOM
Place.Field.REVIEWS
Place.Field.SERVES_BEER
Place.Field.SERVES_BREAKFAST
Place.Field.SERVES_BRUNCH
Place.Field.SERVES_COCKTAILS
Place.Field.SERVES_COFFEE
Place.Field.SERVES_DESSERT
Place.Field.SERVES_DINNER
Place.Field.SERVES_LUNCH
Place.Field.SERVES_VEGETARIAN_FOOD
Place.Field.SERVES_WINE
Place.Field.TAKEOUT
  Observação:a versão 4.0 do SDK do Places para Android introduziu a descontinuação de vários campos de dados de lugar e a adição de novos campos. Para mais informações, consulte Migrar para os novos campos de dados de lugar no SDK do Places para Android 4.0 .

  Para definir o parâmetro de 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.DISPLAY_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.DISPLAY_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 ser maior que 0,0 e menor ou igual a 50.000,0.Vale lembrar que especificar um raio muito pequeno vai 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 de Tabela A usados para filtrar os resultados da pesquisa. É possível especificar até 50 tipos em cada categoria de restrição de tipo.

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

  Um lugar só pode ter um tipo principal dos tipos da Tabela A associado a ele. Por exemplo, o tipo principal pode ser "mexican_restaurant" ou "steak_house". Use includedPrimaryTypes e excludedPrimaryTypes para filtrar os resultados 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" e "establishment". Use includedTypes e excludedTypes para filtrar os resultados na lista de tipos associados a um lugar.

  Quando você especifica um tipo principal geral, como "restaurant" ou "hotel", a resposta pode conter lugares com um tipo principal mais específico do que o especificado. Por exemplo, você especifica o tipo principal "restaurant". A resposta pode conter lugares com um tipo principal de "restaurant", mas também pode conter lugares com um tipo principal mais específico, como "chinese_restaurant" ou "seafood_restaurant".

  Se uma pesquisa for especificada com várias restrições de tipo, apenas os lugares que atenderem a todas as restrições 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 operar principalmente como "steak_house".

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

  Para conferir um exemplo de como usar includedTypes e excludedTypes, consulte Solicitações do 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 vai incluir lugares categorizados como "school", mas não como "primary_school". A resposta inclui lugares que correspondem a pelo menos um dos includedTypes e nenhum dos excludedTypes.

  Se houver tipos conflitantes, 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 de tipos de lugar principais da Tabela A para incluir em uma pesquisa.

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

  Tipos principais excluídos

  Uma lista de tipos de lugar principais da Tabela A a serem excluídos de uma pesquisa.

  Se houver tipos principais conflitantes, 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), inclusive.

  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 um dos seguintes:

  • POPULARITY (padrão) Classifica os resultados com base na popularidade.
  • DISTANCE Classifica os resultados em ordem crescente pela 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 FORMATTED_ADDRESS na resposta corresponder ao regionCode, o código do país será omitido de FORMATTED_ADDRESS.

  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), e 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 de código de região, chame o método setRegionCode() ao criar o objeto SearchNearbyRequest.

Exibir atribuições no seu aplicativo

Quando o app mostra informações obtidas de PlacesClient, como fotos e avaliações, ele também precisa mostrar as atribuições necessárias.

Para mais informações, consulte as políticas do SDK do Places para Android.