Text Search (novo)

Selecione a plataforma: Android iOS JavaScript Serviço da Web

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.

O serviço é especialmente útil para fazer consultas de endereço ambíguas em um sistema automatizado, e componentes da string que não são endereços podem corresponder a empresas e endereços. Exemplos de consultas de endereço ambíguas são endereços mal formatados ou solicitações que incluem componentes que não são endereços, como nomes de empresas. Solicitações como os dois primeiros exemplos podem retornar nenhum resultado, a menos que um local, como região, restrição de local ou direcionamento de local, seja definido.

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

"10 High Street, UK" ou "123 Main Street, EUA" Várias "High Street" no Reino Unido e várias "Main Street" nos EUA. A consulta não retorna os resultados desejáveis, a menos que uma restrição de local tenha sido definida.
"ChainRestaurant New York" Vários locais de "ChainRestaurant" em Nova York, sem endereço ou mesmo nome de rua.
"10 High Street, Escher UK" ou "123 Main Street, Pleasanton US" Somente uma "High Street" na cidade de Escher, no Reino Unido, e apenas uma "Main Street" na cidade de Pleasanton CA, nos EUA.
"UniqueRestaurantName New York" Apenas um estabelecimento com esse nome em Nova York. Não é necessário diferenciar um endereço.
"pizzarias em São Paulo" Essa consulta contém a restrição de local, e "pizzaria" é um tipo de lugar bem definido. Ela retorna vários resultados.
"+55 (51) 4670-8700"

Esta consulta contém um número de telefone. Ela retorna vários resultados para lugares associados a esse número de telefone.

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

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

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

    • Defina a string de consulta de texto como "Comida vegetariana picante".

    • Defina o número máximo de locais de resultados como 10. O padrão e o máximo são 20.

    • Restrinja a área de pesquisa ao retângulo definido por coordenadas de latitude e longitude. Nenhuma correspondência fora desta área é retornada.

  • Adicione um OnSuccessListener e acesse os lugares correspondentes do objeto SearchByTextResponse.

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 transmitidos 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.NAME);

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

Parâmetros obrigatórios

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

  • Lista de campos

    Especifique quais campos de dados de lugares devem ser retornados. Transmita uma lista de valores Place.Field 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 prática recomendada de design para garantir que você não solicite dados desnecessários. Isso ajuda a evitar cobranças desnecessárias no tempo de processamento e nas cobranças.

    Especifique um ou mais dos seguintes campos:

    • Os campos a seguir acionam a SKU do Text Search (somente ID):

      Place.Field.ID, Place.Field.NAME

    • Os campos a seguir acionam a SKU do Text 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.TYPES, Place.Field.UTC_OFFSET, Place.Field.VIEWPORT e Place.Field.WHEELCHAIR_ACCESSIBLE_ENTRANCE

    • Os campos a seguir acionam a SKU do Text Search (avançado):

      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 a SKU do Text Search (Preferencial):

      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 e Place.Field.TAKEOUT

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

  • Consulta de texto

    A string de texto a ser pesquisada, por exemplo: "restaurante", "Avenida Central 123" ou "melhor lugar para visitar em São Francisco". A API retorna correspondências possíveis de acordo com essa string e ordena os resultados com base na relevância percebida.

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

Parâmetros opcionais

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

  • Tipo incluído

    Restringe os resultados aos lugares correspondentes ao tipo especificado definido pela Tabela A. Só é possível especificar um tipo. Exemplo:

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

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

  • Viés de local

    Especifica uma área a ser pesquisada. Essa localização serve como um direcionamento que significa que resultados ao redor do local especificado podem ser retornados, incluindo resultados fora da área especificada.

    Você pode 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 viés de local como a especificação da região a que os resultados precisam estar próximos, mas que podem estar fora da área.

    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. 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 e longitude, representada como dois pontos baixo e alto diagonalmente opostos. O ponto baixo marca o canto sudoeste do retângulo, e o ponto alto representa o canto nordeste.

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

      • Se low = high, a janela de visualização consistirá nesse único ponto.
      • Se low.longitude > high.longitude, o intervalo de longitude é 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 incluirá todas as longitudes.
      • Se low.longitude = 180 graus e high.longitude = -180 graus, o intervalo de longitude fica 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 ficar vazia. Uma janela de visualização vazia resulta em erro.

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

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

  • Restrição de local

    Especifica uma área a ser pesquisada. 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 de Viés de local para informações sobre como definir a janela de visualização.

    Você pode 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 viés de local como a especificação da região a que os resultados precisam estar próximos, mas que podem estar fora da área.

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

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

  • Classificação mínima

    Restringe os resultados apenas àqueles com uma classificação média de usuários 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. Os valores são arredondados para a casa decimal mais próxima. 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 método setMinRating() ao criar o objeto SearchByTextRequest.

  • Aberto agora

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

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

  • 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 que os resultados incluam apenas locais em 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 método setPriceLevels() ao criar o objeto SearchByTextRequest.

  • Preferência de classificação

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

    • Para uma consulta categórica como "Restaurantes em Nova York", o padrão é SearchByTextRequest.RankPreference.RELEVANCE (classificar os resultados por relevância da pesquisa). Você pode definir a preferência de classificação como SearchByTextRequest.RankPreference.RELEVANCE ou SearchByTextRequest.RankPreference.DISTANCE (classificar os 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 sem definição.

    Para definir o parâmetro de preferência de classificação, chame o método setRankPreference() ao criar o objeto SearchByTextRequest.

  • 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. Esse parâmetro também pode influenciar os 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, esse código 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 "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 SearchByTextRequest.

  • Filtragem de tipo restrito

    Usado com o parâmetro de tipo de inclusão. Quando definido como true, apenas lugares que correspondem aos tipos especificados especificados pelo tipo de inclusão são retornados. Quando for false, o padrão, a resposta poderá conter locais que não correspondam aos tipos especificados.

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