Nearby Search (novo)

Uma solicitação de Nearby Search (novo) recebe 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 Place objeto, na área de pesquisa especificada.

Por padrão, a resposta contém lugares de todos os tipos na área de pesquisa. Opcionalmente, é possível filtrar a resposta especificando uma lista de tipos de lugares a serem incluídos ou excluídos da resposta. Por exemplo, você pode 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 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 por proximidade especifica que os objetos Place de resposta contenham 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, é 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 de objetos de lugar.

Parâmetros obrigatórios

Use o SearchNearbyRequest objeto para especificar os parâmetros obrigatórios da pesquisa.

• Lista de campos

  Ao solicitar detalhes do lugar, você precisa especificar os dados a serem retornados no objeto Place para o 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árias.

  Especifique um ou mais dos seguintes campos:

  • Os campos a seguir acionam a SKU Pro do Nearby Search:

    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 foi descontinuado.
    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 campos a seguir acionam a SKU Enterprise do Nearby Search:

    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 foi descontinuado.
    Place.Field.WEBSITE_URI

  • Os campos a seguir acionam a Nearby Search 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 da lista de campos, chame o setPlaceFields() método ao criar o SearchNearbyRequest objeto.

  O exemplo a seguir define uma lista de dois valores de campo para especificar que o Place objeto retornado por uma solicitação contém os Place.Field.ID e Place.Field.DISPLAY_NAME campos:

// 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 LocationRestriction objeto 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.Especificar um raio muito pequeno vai retornar ZERO_RESULTS como resposta.

  Para definir o parâmetro de restrição de local, chame o setLocationRestriction() método ao criar o SearchNearbyRequest objeto.

Parâmetros opcionais

Use o SearchNearbyRequest objeto para especificar os parâmetros opcionais da pesquisa.

• Tipos e tipos principais

  Permite especificar uma lista de tipos da Tabela A de tipos 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 único tipo principal da Tabela A de tipos 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 de tipos associados a ele. Por exemplo, um restaurante pode ter os seguintes tipos: "seafood_restaurant", "restaurant", "food", "point_of_interest", "establishment". Use includedTypes and excludedTypes para filtrar os resultados na lista de tipos associados a a place.

  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 então conter lugares com um tipo principal de "restaurant", mas a resposta 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 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 fornecer serviços relacionados a "restaurant", mas não vão operar principalmente como uma "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 de 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 setIncludedTypes() método ao criar o SearchNearbyRequest objeto.

  Tipos excluídos

  Uma lista de tipos de lugar de Tabela A a serem excluídos 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 de includedTypes e nenhum de excludedTypes.

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

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

  Tipos principais incluídos

  Uma lista de tipos de lugar principais de Tabela A a serem incluídos em uma pesquisa.

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

  Tipos principais excluídos

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

  Se houver tipos principais conflitantes, como um tipo que aparece em includedPrimaryTypes e excludedPrimaryTypes, um INVALID_ARGUMENT erro será retornado.

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

• Número máximo de resultados

  Especifica o número máximo de resultados de lugares 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 setMaxResultCount() ao criar o 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 deles.
  • 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 setRankPreference() método ao criar o SearchNearbyRequest objeto.

• Código de região

  O código de região usado para formatar a resposta, especificado como um código CLDR de duas letras valor. 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 do "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 setRegionCode() método ao criar o SearchNearbyRequest objeto.

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