Nearby Search (novo)

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 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 lugares para incluir ou excluir explicitamente da resposta. Por exemplo, você pode especificar que a resposta inclua 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 (New) 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 conhecida como máscara de campo. Se você não especificar pelo menos um campo na lista de campos ou omitir a lista, 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 por proximidade 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 "pizzaria" e "restaurante americano".

// 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 de cada 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 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 de um 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. A máscara 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 seguintes campos acionam a Pesquisa nas proximidades Pro SKU:

    Place.Field.ADDRESS_COMPONENTS
Place.Field.BUSINESS_STATUS
Place.Field.ADDRESS
Place.Field.DISPLAY_NAME >*
        * Use em vez de Place.Field.NAME, que foi descontinuado.
    Place.Field.ICON_BACKGROUND_COLOR
Place.Field.ICON_MASK_URL*
        * Use em vez de Place.Field.ICON_URL, que está suspenso.
    Place.Field.ID
Place.Field.LAT_LNG
Place.Field.PHOTO_METADATAS
Place.Field.PLUS_CODE
Place.Field.PRIMARY_TYPE
Place.Field.PRIMARY_TYPE_DISPLAY_NAME
Place.Field.RESOURCE_NAME
Place.Field.TYPES
Place.Field.UTC_OFFSET
Place.Field.VIEWPORT
Place.Field.WHEELCHAIR_ACCESSIBLE_ENTRANCE

  • Os seguintes campos acionam a SKU empresarial da pesquisa nas proximidades:

    Place.Field.CURRENT_OPENING_HOURS
Place.Field.CURRENT_SECONDARY_OPENING_HOURS
Place.Field.INTERNATIONAL_PHONE_NUMBER*
        * Use em vez de Place.Field.PHONE_NUMBER, que foi descontinuado.
    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*
        * Use em vez de Place.Field.USER_RATINGS_TOTAL, que está descontinuado.
    Place.Field.WEBSITE_URI

  • Os seguintes campos acionam a Pesquisa nas proximidades Enterprise Plus SKU:

    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 por um ponto central e um raio em metros. O raio precisa ser maior que 0,0 e menor ou igual a 50.000,0.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 da Tabela A usada para filtrar os resultados da pesquisa. É possível especificar até 50 tipos em cada categoria de restrição.

  Um lugar só pode ter um único tipo principal 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 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.

  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 incluir um tipo principal de "restaurant". A resposta pode conter lugares com um tipo principal de "restaurant", mas também pode incluir 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, somente os lugares que atendem 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 oferecer serviços relacionados a "restaurant", mas não vão operar principalmente como um "steak_house".

  Para 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, os 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 "excluded types", 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 para excluir 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.

• Número máximo 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 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), 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 de código da região, chame o método setRegionCode() ao criar o objeto SearchNearbyRequest.

Exibir atribuições no seu aplicativo

Quando seu 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 Políticas do SDK do Places para Android.