Pesquisa de local próximo (Novo)

Selecione a plataforma: Android iOS JavaScript Web Service

Uma solicitação de Nearby Search (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 apenas os lugares do tipo "restaurante", "padaria" e "café" sejam incluídos na resposta 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 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();
    });

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 tempo de processamento e cobranças 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.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 Nearby Search (Avançado):

      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

    • Os campos a seguir acionam o SKU Nearby Search (Preferred):

      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

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

    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 primário geral, como "restaurant" ou "hotel", a resposta pode conter lugares com um tipo primário 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".

    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 a serem pesquisados. 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 de distância a partir da localização especificada.

    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 de 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), enquanto o código ISO 3166-1 é "gb" (tecnicamente, para a entidade "Reino Unido da Grã-Bretanha e da 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 exibir as atribuições necessárias.

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