Text Search (novo)

Selecione a plataforma: Android iOS JavaScript Web Service

Desenvolvedores do Espaço Econômico Europeu (EEE)

O Text Search (novo) retorna informações sobre um conjunto de lugares com base em uma string, por exemplo, "pizza em São Paulo", "loja de sapatos perto do Rio de Janeiro" ou "Avenida Brasil, 123". O serviço responde com uma lista de locais correspondentes à string de texto e a todos os direcionamentos de localização definidos.

Além dos parâmetros obrigatórios, o Text Search (novo) oferece suporte ao refinamento de consultas usando parâmetros opcionais para melhores resultados.

O Text Search (novo) é semelhante ao Nearby Search (novo). A principal diferença entre os dois é que o Text Search (novo) permite especificar uma string de pesquisa arbitrária, enquanto o Nearby Search (novo) exige uma área específica em que pesquisar.

Solicitações do Text Search

Uma solicitação do Text Search tem o seguinte formato:

// Specify the list of fields to return.
final List<Place.Field> placeFields = Arrays.asList(Place.Field.ID, Place.Field.DISPLAY_NAME);

// Define latitude and longitude coordinates of the search area.
LatLng southWest = new LatLng(37.38816277477739, -122.08813770258874);
LatLng northEast = new LatLng(37.39580487866437, -122.07702325966572);

// Use the builder to create a SearchByTextRequest object.
final SearchByTextRequest searchByTextRequest = SearchByTextRequest.builder("Spicy Vegetarian Food", placeFields)
  .setMaxResultCount(10)
  .setLocationRestriction(RectangularBounds.newInstance(southWest, northEast)).build();

// Call PlacesClient.searchByText() to perform the search.
// Define a response handler to process the returned List of Place objects.
placesClient.searchByText(searchByTextRequest)
    .addOnSuccessListener(response -> {
      List<Place> places = response.getPlaces();
    });

Neste exemplo, você:

  • Define a lista de campos para incluir apenas Place.Field.ID e Place.Field.DISPLAY_NAME. Isso significa que os objetos Place na resposta que representam cada lugar correspondente contêm apenas esses dois campos.

  • Use SearchByTextRequest.Builder para criar um SearchByTextRequest objeto que define a pesquisa.

    • Define a string de consulta de texto como "Comida vegetariana apimentada".

    • Define o número máximo de lugares de resultado como 10. O padrão e o máximo são 20.

    • Restringe a área de pesquisa ao retângulo definido pelas coordenadas de latitude e longitude. Nenhuma correspondência fora dessa área é retornada.

  • Adiciona um OnSuccessListener e recebe os lugares correspondentes do SearchByTextResponse objeto.

Respostas do Text Search

A classe SearchByTextResponse representa a resposta de uma solicitação de pesquisa. Um objeto SearchByTextResponse 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:

// Specify the list of fields to return.
final List<Place.Field> placeFields = Arrays.asList(Place.Field.ID, Place.Field.DISPLAY_NAME);

Essa lista de campos significa que cada objeto Place na resposta contém apenas o ID de lugar 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.

Paginação

A classe SearchByTextResponse do Text Search fornece acesso à paginação de resultados da pesquisa de texto pelo método getPagination(), que retorna um objeto de paginação.

Use o método hasNextPage() do objeto de paginação para determinar se há mais páginas de resultados disponíveis. Esse método retorna um valor booleano (verdadeiro ou falso).

Enquanto hasNextPage() retornar verdadeiro, chame o método fetchNextPage() para recuperar a próxima página de resultados.

O exemplo a seguir mostra como verificar se uma próxima página está disponível e, em seguida, carregar a página.

Kotlin

val searchByTextRequest =
      searchByTextRequest("restaurants", Arrays.asList(Place.Field.NAME)) {
        maxResultCount = 10
      }

// using pagination object (Preferred)
placesClient.searchByText(searchByTextRequest)   
    .addOnSuccessListener {response: SearchByTextResponse ->
        val places = response.places

        val pagination = response.pagination

        if (pagination.hasNextPage()) {
            pagination.setPageSize(20)
            pagination.fetchNextPage()
                    .addOnSuccessListener { nextPageResponse ->
                          val nextPagePlaces = nextPageResponse.getPlaces()
                    }
                    .addOnFailureListener {// Handle error with given status code}
        }
}
.addOnFailureListener {
// TODO: Handle error with given status code.
exception -> {
          exception.printStackTrace();
        }
}

Java

SearchByTextRequest searchByTextRequest =
  SearchByTextRequest.builder("restaurants", Arrays.asList(Place.Field.NAME)).setMaxResultCount(10).build();

// using pagination object (Preferred)
placesClient.searchByText(searchByTextRequest)
  .addOnSuccessListener((response) -> {
    List<Place> places = response.getPlaces();
    Log.i(TAG, "Places result: " + places);

    Pagination pagination =
      response.getPagination();

    if (pagination.hasNextPage()) {
      pagination.setPageSize(20); // change the page size from 10 to 20
      pagination.fetchNextPage()
    	  .addOnSuccessListener((nextPageResponse) -> {
            List<Place> nextPagePlaces = nextPageResponse.getPlaces();
            Log.i(TAG, "Next page places result: " + nextPagePlaces);
        });
    }
  })
  .addOnFailureListener((exception) -> {
    if (exception instanceof ApiException) {
    	// Handle error with given status code
    }
  });

Parâmetros obrigatórios

Os parâmetros obrigatórios para SearchByTextRequest são:

  • Lista de campos

    Especifique quais campos de dados de lugar precisam ser retornados. Transmita uma lista de Place.Field valores especificando os campos de dados a serem retornados. Não há uma lista padrão de campos retornados na resposta.

    As listas de campos são 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 Text Search Essentials ID Only:

      Place.Field.DISPLAY_NAME*
          * Use em vez de Place.Field.NAME (descontinuado na versão 4.0).
      Place.Field.ID
      Place.Field.RESOURCE_NAME*
          * Contém o nome do recurso de lugar no formato: places/PLACE_ID.
      Use DISPLAY_NAME para acessar o nome de texto do lugar.

      Para uma lista completa de campos e SKUs associadas, consulte Campos de dados de lugar (novo).

    • Os campos a seguir acionam a SKU Text Search Pro:

      Place.Field.ACCESSIBILITY_OPTIONS*
          Use em vez de Place.Field.WHEELCHAIR_ACCESSIBLE_ENTRANCE (descontinuado).
      Place.Field.ADDRESS_COMPONENTS
      Place.Field.ADR_FORMAT_ADDRESS
      Place.Field.BUSINESS_STATUS
      Place.Field.FORMATTED_ADDRESS*
          Use em vez de Place.Field.ADDRESS (descontinuado).
      Place.Field.GOOGLE_MAPS_URI
      Place.Field.ICON_BACKGROUND_COLOR
      Place.Field.ICON_MASK_URL *
          Use em vez de Place.Field.ICON_URL (descontinuado).
      Place.Field.LOCATION*
          Use em vez de Place.Field.LAT_LNG (descontinuado).
      Place.Field.PHOTO_METADATAS
      Place.Field.PLUS_CODE
      Place.Field.PRIMARY_TYPE
      Place.Field.PRIMARY_TYPE_DISPLAY_NAME
      Place.Field.SHORT_FORMATTED_ADDRESS
      Place.Field.SUB_DESTINATIONS
      Place.Field.TYPES
      Place.Field.UTC_OFFSET
      Place.Field.VIEWPORT

      Para uma lista completa de campos e SKUs associadas, consulte Campos de dados de lugar (novo).

    • Os campos a seguir acionam a SKU Text Search Enterprise:

      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 está 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

      Para uma lista completa de campos e SKUs associadas, consulte Campos de dados de lugar (novo).

    • Os campos a seguir acionam a SKU Text Search Enterprise Plus:

      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 uma lista completa de campos e SKUs associadas, consulte Campos de dados de lugar (novo).

    Para definir o parâmetro da lista de campos, chame o setPlaceFields() método ao criar o SearchByTextRequest objeto.

  • Consulta de texto

    A string de texto em que pesquisar, por exemplo, "restaurante", "Rua Principal, 123" ou "melhor lugar para visitar em São Francisco". A API retorna as correspondências possíveis com base nessa string e ordena os resultados com base na relevância.

    Para definir o parâmetro de consulta de texto, chame o setTextQuery() ao criar o SearchByTextRequest.

Parâmetros opcionais

Use o SearchByTextRequest objeto para especificar os parâmetros opcionais da sua solicitação.

  • Tipo incluído

    Restringe os resultados aos lugares correspondentes ao tipo especificado definido por Tabela A. Apenas um tipo pode ser especificado. Exemplo:

    • setIncludedType("bar")
    • setIncludedType("pharmacy")

    Para definir o parâmetro de tipo incluído, chame o setIncludedType() método ao criar o SearchByTextRequest objeto.

  • Direcionamento de local

    Especifica uma área para pesquisar. Esse local serve como um direcionamento, o que significa que resultados em torno do local especificado podem ser retornados, incluindo resultados fora da área especificada.

    É possível especificar a restrição de local ou o direcionamento de local, mas não ambos. Pense na restrição de local como a especificação da região em que os resultados precisam estar e no direcionamento de local como a especificação da região em que os resultados provavelmente estarão ou perto dela. Ao usar o direcionamento de local, os resultados ainda podem estar fora da área especificada.

    Especifique a região como uma janela de visualização retangular ou como um círculo.

    • Um círculo é definido pelo ponto central e pelo raio em metros. O raio precisa estar entre 0,0 e 50.000,0, inclusive. Exemplo:

      // Define latitude and longitude coordinates of the center of the search area.
LatLng searchCenter = new LatLng(37.38816277477739, -122.08813770258874);

// Use the builder to create a SearchByTextRequest object.
// Set the radius of the search area to 500.0 meters.
final SearchByTextRequest searchByTextRequest = SearchByTextRequest.builder("Spicy Vegetarian Food", placeFields)
  .setMaxResultCount(10)
  .setLocationBias(CircularBounds.newInstance(searchCenter, 500.0)).build();

    • Um retângulo é uma janela de visualização de latitude-longitude, representada como dois diagonalmente opostos pontos baixos e altos. O ponto baixo marca o canto sudoeste do retângulo, e o ponto alto representa o canto nordeste do retângulo.

      Uma janela de visualização é considerada uma região fechada, o que significa que ela inclui o limite. Os limites de latitude precisam variar entre -90 e 90 graus, inclusive, e os limites de longitude precisam variar entre -180 e 180 graus, inclusive:

      • Se low = high, a janela de visualização consiste nesse único ponto.
      • Se low.longitude > high.longitude, o intervalo de longitude será invertido (a janela de visualização cruza a linha de longitude de 180 graus).
      • Se low.longitude = -180 graus e high.longitude = 180 graus, a janela de visualização inclui todas as longitudes.
      • Se low.longitude = 180 graus e high.longitude = -180 graus, o intervalo de longitude estará vazio.
      • Se low.latitude > high.latitude, o intervalo de latitude estará vazio.

      Os valores baixo e alto precisam ser preenchidos, e a caixa representada não pode estar vazia. Uma janela de visualização vazia resulta em um erro.

      Por exemplo, de uma janela de visualização retangular, consulte Solicitações do Text Search.

      Para definir o parâmetro de direcionamento de local, chame o setLocationBias() método ao criar o SearchByTextRequest objeto.

  • Restrição de local

    Especifica uma área para pesquisar. Os resultados fora da área especificada não são retornados. Especifique a região como uma janela de visualização retangular. Consulte a descrição do direcionamento de local para informações sobre como definir a janela de visualização.

    É possível especificar a restrição de local ou o direcionamento de local, mas não ambos. Pense na restrição de local como a especificação da região em que os resultados precisam estar e no direcionamento de local como a especificação da região em que os resultados precisam estar próximos, mas podem estar fora da área.

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

  • 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 setMaxResultCount() método ao criar o SearchByTextRequest objeto.

  • Classificação mínima

    Restringe os resultados apenas àqueles cuja avaliação de usuários média seja maior ou igual a esse limite. Os valores precisam estar entre 0,0 e 5,0 (inclusive) em incrementos de 0,5. Por exemplo: 0, 0,5, 1,0, ..., 5,0 inclusive. Os valores são arredondados para o 0,5 mais próximo. Por exemplo, um valor de 0,6 elimina todos os resultados com uma classificação menor que 1,0.

    Para definir o parâmetro de classificação mínima, chame o setMinRating() método ao criar o SearchByTextRequest objeto.

  • Aberto agora

    Se true, retorne apenas os lugares que estão abertos no momento em que a consulta é enviada. Se false, retorne todas as empresas independentemente do status aberto. Os lugares que não especificam horário de funcionamento no banco de dados do Google Places são retornados se você definir esse parâmetro como false.

    Para definir o parâmetro "aberto agora", chame o setOpenNow() método ao criar o SearchByTextRequest objeto.

  • Níveis de preço

    Por padrão, os resultados incluem lugares que oferecem serviços em todos os níveis de preço. Para restringir os resultados a lugares com níveis de preço específicos, transmita uma lista de valores inteiros que correspondam aos níveis de preço dos lugares que você quer retornar:

    • 1 - O lugar oferece serviços baratos.
    • 2 - O lugar oferece serviços com preços moderados.
    • 3 - O lugar oferece serviços caros.
    • 4 - O lugar oferece serviços muito caros.

    Para definir o parâmetro de níveis de preço, chame o setPriceLevels() método ao criar o SearchByTextRequest objeto.

  • Preferência de classificação

    Especifica como os resultados são classificados na resposta com base no tipo de query:

    • Para uma consulta categórica, como "Restaurantes na cidade de Nova York", SearchByTextRequest.RankPreference.RELEVANCE (classificar resultados por relevância da pesquisa) é o padrão. É possível definir a preferência de classificação como SearchByTextRequest.RankPreference.RELEVANCE ou SearchByTextRequest.RankPreference.DISTANCE (classificar resultados por distância).
    • Para uma consulta não categórica, como "Mountain View, CA", recomendamos que você deixe o parâmetro de preferência de classificação não definido.

    Para definir o parâmetro de preferência de classificação, chame o setRankPreference() método ao criar o SearchByTextRequest 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. Esse parâmetro também pode ter um efeito de direcionamento nos resultados da pesquisa. Não há valor padrão.

    Se o nome do país do campo de endereço na resposta corresponder ao código da região, o código do país será omitido do endereço.

    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 lei aplicável.

    Para definir o parâmetro de código de região, chame o setRegionCode() ao criar o SearchByTextRequest.

  • Filtragem de tipo estrita

    Usado com o parâmetro de tipo incluído. Quando definido como true, apenas os lugares que correspondem aos tipos especificados pelo tipo incluído são retornados. Quando false, o padrão, a resposta pode conter lugares que não correspondem aos tipos especificados.

    Para definir o parâmetro de filtragem de tipo estrita, chame o método setStrictTypeFiltering() ao criar o objeto SearchByTextRequest.