Text Search (novo)

Selecione a plataforma: Android iOS JavaScript Web Service

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

Se o endereço de faturamento estiver no Espaço Econômico Europeu, a partir de 8 de julho de 2025, os Termos de Serviço da Plataforma Google Maps para o EEE vão se aplicar ao uso dos Serviços. A funcionalidade varia de acordo com a região. Saiba mais.

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 lugares correspondentes à string de texto e a todos os direcionamentos de localização definidos.

O serviço é especialmente útil para fazer consultas de endereços ambíguos em um sistema automatizado, e os componentes não relacionados a endereços da string 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 de 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 ou viés) seja definido.

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

"Rua High, 10, Reino Unido" ou "Rua Principal, 123, EUA"	Várias "High Street" no Reino Unido e várias "Main Street" nos EUA. A consulta não retorna os resultados desejados, a menos que uma restrição de local seja definida.
"ChainRestaurant New York"	Vários locais de "ChainRestaurant" em Nova York; sem endereço ou nome de rua.
"Rua das Flores, 10, Escher, Reino Unido" ou "Rua Principal, 123, Pleasanton, EUA"	Apenas uma "High Street" na cidade de Esher, no Reino Unido, e uma "Main Street" na cidade de Pleasanton, na Califórnia (EUA).
"UniqueRestaurantName Nova York"	Apenas um estabelecimento com esse nome em Nova York. Não é necessário um endereço para diferenciar.
"pizzarias em Nova York"	Essa consulta contém a restrição de local, e "pizzarias" é um tipo de lugar bem definido. Ele retorna vários resultados.
"[phone]"	Esta consulta contém um número de telefone. Ele retorna vários resultados para lugares associados a esse número de telefone. Observação : para ter os melhores resultados ao pesquisar um número de telefone, inclua o código do país seguido de um espaço e defina o parâmetro regionCode para corresponder ao código do país. Os formatos de número de telefone variam de acordo com o país, e a API tenta retornar um resultado para esses formatos diferentes.

Observação: a pesquisa de texto (nova) está disponível no SDK do Places para Android versão 3.3.0 e mais recente. Para mais informações, consulte Escolher sua versão do SDK. Para mais informações sobre o uso das APIs Kotlin adicionadas na versão 4.0.0, consulte a Visão geral da referência.

Solicitações da Pesquisa de texto

Observação: a pesquisa de texto faz parte do SDK do Places para Android (novo) e não está disponível no SDK do Places para Android.

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 resultado como 10. O padrão e o máximo é 20.

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

Observação:para mais informações sobre a inicialização de PlacesClient, consulte Inicializar o cliente da API Places.

Você pode usar um CancellationToken para tentar cancelar uma solicitação a qualquer uma das classes de solicitação (por exemplo, FetchPlaceRequest). O cancelamento é feito da melhor maneira possível. Depois que um pedido de cancelamento é emitido, nenhuma resposta é retornada. A emissão de um token de cancelamento NÃO garante que uma solicitação específica será cancelada, e você ainda poderá receber uma cobrança por ela mesmo que nenhuma resposta seja retornada.

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 de cada 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 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 lugar precisam 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 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 (uso suspenso 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 do texto do lugar.

  • Os campos a seguir acionam o 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

  • 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 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 está suspenso.
    Place.Field.WEBSITE_URI

  • Os campos a seguir acionam o 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
  Observação:a versão 4.0 do SDK do Places para Android introduziu a descontinuação de vários campos de dados de lugar e a adição de novos campos. Para mais informações, consulte Migrar para os novos campos de dados de lugar no SDK do Places para Android 4.0 .

  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 de acordo com essa string e ordena os resultados com base na relevância.

  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")
  Observação : os valores na Tabela B são retornados apenas na resposta. Não é possível usar valores em Tabela B como um filtro.

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

• Viés de local

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

  É possível especificar restrição ou viés 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 tendência de local como a especificação da região em que os resultados provavelmente estarão ou perto dela. Ao usar a tendência de local, os resultados ainda podem estar fora da área especificada.

  Observação : se você omitir a restrição e a tendência de local, a API usará a tendência de IP por padrão. Com a inclusão de tendência de IP, a API usa o endereço IP do dispositivo para influenciar os resultados.
  Observação : o parâmetro locationBias pode ser substituído se o textQuery contiver um local explícito, como Market in Barcelona. Nesse caso, locationBias é ignorado.

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

  • Um círculo é definido por um ponto central e um raio em metros. O raio precisa estar entre 0,0 e 50.000,0, incluindo esses dois valores. 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 diagonais opostos, um baixo e um alto. 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, ou seja, inclui o limite. Os limites de latitude precisam estar entre -90 e 90 graus, e os de longitude 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 será invertido (a janela de visualização cruzará 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, para uma janela de visualização retangular, consulte Solicitações de pesquisa de texto.

    Para definir o parâmetro de tendência de local, 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 do vício de localização para informações sobre como definir a janela de visualização.

  É possível especificar restrição ou viés de local, mas não ambos. A restrição de local especifica a região em que os resultados precisam estar, e a tendência de local especifica a região em que os resultados precisam estar próximos, mas podem estar fora da área.

  Observação : se você omitir a restrição e a tendência de local, a API usará a tendência de IP por padrão. Com a inclusão de tendência de IP, a API usa o endereço IP do dispositivo para influenciar os resultados.

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

• Número máximo 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 àqueles cuja 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,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 método setMinRating() ao criar o objeto SearchByTextRequest.

• Aberto agora

  Se true, retorne apenas os lugares que estão abertos para negócios no momento em que a consulta é enviada. Se 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 "aberto 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 lugares com níveis de preço específicos, transmita uma lista de valores inteiros que correspondem 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.
  Observação : o valor inteiro de 0, que indica que o lugar oferece serviços sem custo financeiro, pode ser incluído em uma resposta, mas não pode ser usado como um valor de filtro em uma solicitação.

  Para definir o parâmetro de níveis de preços, 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 São Paulo", SearchByTextRequest.RankPreference.RELEVANCE (classificar resultados por relevância da pesquisa) é o padrão. Você pode 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 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 ter um efeito de viés nos resultados da pesquisa. Não há valor padrão.

  Se o nome do país no campo de endereço da 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 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 da região, chame o método setRegionCode() ao criar o objeto SearchByTextRequest.

• Filtragem de tipo estrita

  Usado com o parâmetro "tipo de inclusão". Quando definido como true, somente 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.