Text Search (novo)

Selecione a plataforma: Android iOS JavaScript Web Service

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 de Ottawa" 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 é particularmente útil para fazer consultas de endereço ambíguas em um sistema automatizado, e componentes da string que não fazem parte do endereço podem corresponder a empresas e endereços. Exemplos de consultas de endereço ambíguas são endereços com formatação incorreta ou solicitações que incluem componentes que não fazem parte do endereço, como nomes de empresas. Solicitações como os dois primeiros exemplos podem retornar zero resultados, a menos que um local, como região, restrição de local ou viés 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, Reino Unido" ou "123 Main Street, EUA" Várias "High Street" no Reino Unido; várias "Main Street" nos EUA. A consulta não retorna resultados desejados, a menos que uma restrição de local seja definida.
"ChainRestaurant New York" Vários locais da "ChainRestaurant" em Nova York, sem endereço ou nome de rua.
"10 High Street, Escher, Reino Unido" ou "123 Main Street, Pleasanton, EUA" Há apenas uma "High Street" na cidade de Escher, no Reino Unido, e apenas uma "Main Street" na cidade de Pleasanton, na Califórnia, nos EUA.
"UniqueRestaurantName New York" Apenas um estabelecimento com esse nome em Nova York; nenhum endereço necessário para diferenciar.
"pizza restaurants in New York" Essa consulta contém a restrição de local, e "pizza restaurants" é um tipo de lugar bem definido. Ele retorna vários resultados.
"+1 514-670-8700"

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

Solicitações da Pesquisa de texto

Uma solicitação de pesquisa de texto 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ê:

  • Defina 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 objeto SearchByTextRequest que define a pesquisa.

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

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

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

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

Respostas da pesquisa de texto

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 e o nome do 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 acesso a dados em um objeto Place, consulte Acessar campos de dados de objetos do Place.

Parâmetros obrigatórios

Os parâmetros necessários para SearchByTextRequest são:

  • Lista de campos

    Especifique quais campos de dados de lugar serão retornados. Transmita uma lista de valores de Place.Field que especificam 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ários.

    Especifique um ou mais dos seguintes campos:

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

      Place.Field.DISPLAY_NAME, Place.Field.ID, Place.Field.RESOURCE_NAME

    • Os campos a seguir acionam a SKU Text Search (Basic):

      Place.Field.ACCESSIBILITY_OPTIONS, Place.Field.ADDRESS_COMPONENTS, Place.Field.ADR_FORMAT_ADDRESS, Place.Field.BUSINESS_STATUS, Place.Field.FORMATTED_ADDRESS, Place.Field.GOOGLE_MAPS_URI, Place.Field.ICON_BACKGROUND_COLOR, Place.Field.ICON_MASK_URL, Place.Field.LOCATION, 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

    • Os campos a seguir acionam o SKU Text Search (Advanced):

      Place.Field.CURRENT_OPENING_HOURS, Place.Field.CURRENT_SECONDARY_OPENING_HOURS Place.Field.INTERNATIONAL_PHONE_NUMBER, 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 Place.Field.WEBSITE_URI

    • Os campos a seguir acionam o SKU Text Search (Preferred):

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

  • 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 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 solicitação.

  • Tipo incluído

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

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

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

  • Viés de localização

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

    É possível especificar a restrição ou a limitação 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 vão estar ou perto dela. Lembre-se de que, 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 um círculo.

    • Um círculo é definido pelo ponto central e pelo raio em metros. O raio precisa estar entre 0,0 e 500.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-longitude, representada como dois pontos baixos e altos diagonalmente opostos. O ponto mais baixo marca o canto sudoeste do retângulo, e o ponto mais alto representa o canto nordeste do retângulo.

      Uma viewport é considerada uma região fechada, ou seja, ela inclui o limite. 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 viewport consiste nesse único ponto.
      • Se low.longitude for maior que 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 viewport inclui todas as longitudes.
      • Se low.longitude = 180 graus e high.longitude = -180 graus, o intervalo de longitude estará vazio.
      • Se low.latitude for maior que high.latitude, o intervalo de latitude vai estar vazio.

      Os valores mínimo e máximo precisam ser preenchidos, e a caixa representada não pode estar vazia. Uma viewport vazia resulta em um erro.

      Por exemplo, para uma viewport retangular, consulte Solicitações de pesquisa de texto.

      Para definir o parâmetro de viés de localização, chame o método setLocationBias() ao criar o objeto SearchByTextRequest.

  • 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 de Viés de localização para informações sobre como definir o viewport.

    É possível especificar a restrição ou a limitação 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 na inclinação 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 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), inclusive.

    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 para aqueles com uma classificação média do usuário 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, ... , 5. 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 método setMinRating() ao criar o objeto SearchByTextRequest.

  • Aberto agora

    Se true, retorna apenas os locais que estão abertos para funcionamento no momento em que a consulta é enviada. Se for false, retorne todas as empresas, independente do status de abertura. 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 "abrir agora", 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 restringir os resultados a apenas lugares com preços 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", 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 os resultados por distância).
    • Para uma consulta não categórica, como "Mountain View, CA", recomendamos que você não defina o parâmetro de preferência de classificaçã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 de região usado para formatar a resposta, especificado como um valor de código CLDR de dois caracteres. Esse parâmetro também pode ter um efeito enviesado 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 "Reino Unido da Grã-Bretanha e da 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 método setRegionCode() ao criar o objeto SearchByTextRequest.

  • Filtragem estrita de tipo

    Usado com o parâmetro de tipo de inclusão. Quando definido como true, apenas os lugares que correspondem aos tipos especificados por "include type" 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 estrito, chame o método setStrictTypeFiltering() ao criar o objeto SearchByTextRequest.