Pesquisa de local próximo (Novo)

Selecione a plataforma: Android iOS JavaScript Web Service

Uma solicitação de Nearby Search (novo) usa como entrada a região para pesquisar especificado como um círculo, definido pela latitude e longitude, coordenadas do ponto central do círculo e o raio em metros. O request retorna uma lista de locais correspondentes, cada um representado por uma Place , dentro da área de pesquisa especificada.

Por padrão, a resposta contém locais de todos os tipos na área de pesquisa. Você pode, opcionalmente, filtrar a resposta especificando uma lista de tipos de lugar para incluir ou excluir explicitamente da resposta. Por exemplo, é possível especificar incluir apenas os lugares na resposta que sejam 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 de Nearby Search (novo) chamando PlacesClient.searchNearby, transmitir um SearchNearbyRequest que define os parâmetros da solicitação.

O objeto SearchNearbyRequest especifica todos os atributos obrigatórios e opcionais, parâmetros para a solicitação. Os parâmetros obrigatórios incluem:

  • A lista de campos a serem retornados no objeto Place, que também é conhecido como um máscara de campo. Se você não especificar pelo menos um campo na lista ou se você omitir a lista de campos, a chamada retornará um erro.
  • A restrição de local para a área de pesquisa, definida como um par de latitude/longitude e valor do raio, em metros.

Este exemplo de solicitação de pesquisa por perto especifica que a resposta os objetos Place contêm os campos de lugar Place.Field.ID e Place.Field.NAME para cada Place nos resultados da pesquisa. Ele também filtra a resposta apenas para retornar lugares do tipo "restaurante" e "café", mas excluir lugares do tipo "restaurante_pizza" 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();
    });

Respostas do Nearby Search (novo)

O SearchNearbyResponse representa a resposta de uma solicitação de pesquisa. Um SearchNearbyResponse contém:

  • Uma lista de objetos Place que representam todos os lugares correspondentes, com um Place objeto por lugar correspondente.
  • Cada objeto Place contém apenas os campos definidos pela lista de campos passada 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 local correspondente. Em seguida, use o 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 o Place campos de dados de objetos.

Parâmetros obrigatórios

Use o SearchNearbyRequest para especificar os parâmetros necessários para a pesquisa.

  • Lista de campos

    Ao solicitar detalhes do lugar, você deve 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 ao 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 de faturamento desnecessárias.

    Especifique um ou mais dos seguintes campos:

    • Os campos a seguir acionam o recurso Nearby Search (Básico) SKU:

      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, Place.Field.WHEELCHAIR_ACCESSIBLE_ENTRANCE

    • Os campos a seguir acionam o recurso Nearby Search (Avançado) SKU:

      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 o recurso Nearby Search (Preferencial) SKU:

      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, 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 O objeto Place retornado por uma solicitação contém Place.Field.ID e Campos 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 LocationRestriction objeto que define a região a ser pesquisada, especificado como um círculo, definido por ponto central e o raio em metros. O raio deve estar entre maior que 0,0 e menor ou igual a 50000,0, tendo em mente que especificar um raio muito pequeno retornam 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 SearchNearbyRequest para especificar os parâmetros opcionais da pesquisa.

  • Tipos e tipos principais

    Permite especificar uma lista de tipos de tipos Tabela A usada para filtrar nos resultados da pesquisa. Até 50 tipos podem ser especificados em cada categoria de restrição.

    Um lugar só pode ter um único tipo principal dos tipos Tabela A associada a reimplantá-lo. Por exemplo, o tipo principal pode ser "mexican_restaurant" ou "steak_house". Usar includedPrimaryTypes e excludedPrimaryTypes para filtrar os resultados o tipo principal de um lugar.

    Um lugar também pode ter vários valores de tipo de tipos. Tabela A associados a ele. Por exemplo, um restaurante pode ter os seguintes tipos: "seafood_restaurant", "restaurant" e "food". "point_of_interest", "establishment". Usar o includedTypes e excludedTypes para filtrar os resultados na lista de tipos associados a de um lugar.

    Se uma pesquisa for especificada com várias restrições de tipo, apenas lugares que satisfaçam todas as restrições são retornadas. Por exemplo, se você especificar includedTypes = Arrays.asList("restaurant") e excludedPrimaryTypes = Arrays.asList("steak_house"), os Os lugares retornados oferecem serviços relacionados ao "restaurant", mas não funcionam principalmente como "steak_house".

    Para ver 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 a ser pesquisada. 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 de Tabela A para excluir de uma pesquisa.

    Se você especificar o includedTypes (como "school") e o excludedTypes (como "primary_school") na solicitação, depois o a resposta inclui lugares categorizados como "school", mas não como "primary_school". A resposta inclui locais que correspondem a pelo menos um dos a includedTypes e nenhuma da excludedTypes.

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

    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 de 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 lugar de Tabela A a ser excluída de uma pesquisa.

    Se houver algum tipo principal conflitante, como um tipo que aparece includedPrimaryTypes e excludedPrimaryTypes, uma 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 em um local específico.

    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 de dois caracteres. Não há valor padrão.

    Se o nome do país do campo formattedAddress na resposta corresponder ao regionCode, o código do país é omitido do formattedAddress.

    A maioria dos códigos CLDR é idêntica 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 os "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 recebidas de PlacesClient, como fotos e avaliações, o app também precisará exibir as atribuições necessárias.

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