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

Além dos parâmetros obrigatórios, a Text Search (nova) permite refinar consultas usando parâmetros opcionais para melhorar os 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 para a pesquisa.

Observação: o Text Search (novo) está disponível no SDK do Places para Android versão 3.3.0 e mais recentes. Para mais informações, consulte Escolher a versão do SDK. Para mais informações sobre como usar as APIs Kotlin adicionadas na versão 4.0.0, consulte a Visão geral da referência.

Solicitações do Text Search

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

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

• 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 como inicializar PlacesClient, consulte Inicializar o cliente da API Places.

É possível usar um CancellationToken para tentar cancelar uma solicitação para qualquer uma das classes de solicitação (por exemplo, FetchPlaceRequest). O cancelamento é feito da melhor maneira possível. Depois que uma solicitação de cancelamento é emitida, 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á ser cobrado pela solicitação, mesmo que nenhuma resposta seja retornada.

Respostas da 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.

• 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, 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 de objetos Place.

Paginação

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

Use o método hasNextPage() do objeto Pagination 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, carregá-la.

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 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 (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 do lugar em formato de texto.

    Para ver uma lista completa de campos e as 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 ver uma lista completa de campos e as 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 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 foi descontinuado.
    Place.Field.WEBSITE_URI

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

  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.

  Observação : para melhores resultados ao pesquisar um número de telefone, inclua o código do país seguido por 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 diferentes formatos. Para números de telefone válidos, a API Places (nova) aceita o formato E.164. Os caracteres alfabéticos são convertidos com base no mapeamento do teclado E.161.

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. Somente um tipo pode ser especificado. Exemplo:

  • setIncludedType("bar")
  • setIncludedType("pharmacy")
  Observação : os valores na Tabela B são retornados apenas na resposta. Não é possível usar valores na Tabela B como 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 em torno do local especificado podem ser retornados, incluindo resultados fora da área especificada.

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

  Observação : se você omitir a polarização e a restrição de localização, a API vai usar a polarização de IP por padrão. Com o viés 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 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 pontos diagonalmente 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 limites de longitude precisam estar entre -180 e 180 graus:

    • 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 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 estar vazia. Uma janela de visualização vazia resulta em um erro.

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

    Para definir o parâmetro de polarização 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 de Viés de local para saber como definir a janela de visualização.

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

  Observação : se você omitir a polarização e a restrição de localização, a API vai usar a polarização de IP por padrão. Com a polarização de IP, a API usa o endereço IP do dispositivo para polarizar os resultados.

  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 lugares 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 com uma avaliaçã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 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 inferior a 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 for false, retornar todas as empresas, independentemente do status de abertura. Os lugares que não especificam o 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 de abertura, 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 e incluir apenas lugares em determinados níveis de preço, 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.
  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ç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 São Paulo", 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ê 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 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 de viés 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 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 de tipo estrita

  Usado com o parâmetro de tipo include. 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.