Text Search (novo)

Selecione a plataforma: Android iOS JavaScript Web Service

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

A Pesquisa de texto 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 que correspondem à string de texto e a qualquer direcionamento de localização definido.

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 direcionamento de local) seja definido.

"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.
"Restaurante de rede Nova York" Vários locais de "Restaurante de rede" 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.
"+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.

Receber uma lista de lugares por pesquisa de texto

Faça uma solicitação de pesquisa de texto chamando GMSPlacesClient searchByTextWithRequest:, transmitindo um objeto GMSPlaceSearchByTextRequest que define os parâmetros da solicitação e um método de callback, do tipo GMSPlaceSearchByTextResultCallback, para processar a resposta.

O objeto GMSPlaceSearchByTextRequest especifica todos os parâmetros obrigatórios e opcionais da solicitação. Os parâmetros obrigatórios incluem:

  • A lista de campos a serem retornados no objeto GMSPlace, também chamada de máscara de campo, conforme definido por GMSPlaceProperty. Se você não especificar pelo menos um campo na lista de campos ou omitir a lista, a chamada vai retornar um erro.
  • A consulta de texto.

Este exemplo de solicitação de pesquisa de texto especifica que os objetos GMSPlace da resposta contêm o nome e o ID de cada objeto GMSPlace nos resultados da pesquisa. Ele também filtra a resposta para retornar apenas lugares do tipo "restaurant".

SDK do Places para Swift

let restriction = RectangularLocationRestriction(
      northEast: CLLocationCoordinate2D(latitude: 20, longitude: 30),
      southWest: CLLocationCoordinate2D(latitude: 40, longitude: 50)
)
let searchByTextRequest = SearchByTextRequest(
        textQuery: "pizza in New York",
        placeProperties: [ .name, .placeID ],
        locationRestriction: restriction,
        includedType: .restaurant,
        maxResultCount: 5,
        minRating: 3.5,
        priceLevels: [ .moderate, .inexpensive ],
        isStrictTypeFiltering: true
)
switch await placesClient.searchByText(with: searchByTextRequest) {
case .success(let places):
  // Handle places
case .failure(let placesError):
  // Handle error
}

Swift

// Create the GMSPlaceSearchByTextRequest object.
let myProperties = [GMSPlaceProperty.name, GMSPlaceProperty.placeID].map {$0.rawValue}
let request = GMSPlaceSearchByTextRequest(textQuery:"pizza in New York", placeProperties:myProperties)
request.isOpenNow = true
request.includedType = "restaurant"
request.maxResultCount = 5
request.minRating = 3.5
request.rankPreference = .distance
request.isStrictTypeFiltering = true
request.locationBias =  GMSPlaceCircularLocationOption(CLLocationCoordinate2DMake(40.7, -74.0), 200.0)

// Array to hold the places in the response
var placeResults: [GMSPlace] = []

let callback: GMSPlaceSearchByTextResultCallback = { [weak self] results, error in
  guard let self, error == nil else {
    if let error {
      print(error.localizedDescription)
    }
    return
  }
  guard let results = results as? [GMSPlace] else {
    return
  }
  placeResults = results
}

GMSPlacesClient.shared().searchByText(with: request, callback: callback)

Objective-C

// Create the GMSPlaceSearchByTextRequest object.
GMSPlaceSearchByTextRequest *request =
    [[GMSPlaceSearchByTextRequest alloc] initWithTextQuery:@"pizza in New York" placeProperties:@[GMSPlacePropertyName, GMSPlacePropertyPlaceID]];
request.isOpenNow = YES;
request.includedType = @"restaurant";
request.maxResultCount = 5;
request.minRating = 3.5;
request.rankPreference = GMSPlaceSearchByTextRankPreferenceDistance;
request.isStrictTypeFiltering = YES;
request.priceLevels = @[ @(kGMSPlacesPriceLevelFree), @(kGMSPlacesPriceLevelCheap) ];
request.locationBias = GMSPlaceCircularLocationOption(CLLocationCoordinate2DMake(40.7, -74.0), 200.0);

// Array to hold the places in the response
_placeResults = [NSArray array];

// Create the GMSPlaceSearchByTextRequest object.
[_placesClient searchByTextWithRequest:request
    callback:^(NSArray<GMSPlace *> *_Nullable placeResults, NSError * _Nullable error) {
      if (error != nil) {
        NSLog(@"An error occurred %@", [error localizedDescription]);
        return;
      } else {
        if (placeResults.count > 0) {
          // Get list of places.
          _placeResults = placeResults;
      }
    }
  }
];

Respostas da Pesquisa de texto

A API Text Search retorna uma matriz de correspondências na forma de objetos GMSPlace, com um objeto GMSPlace por lugar correspondente.

Receber status de abertura

O objeto GMSPlacesClient contém uma função membro chamada isOpenWithRequest (isOpenRequest em Swift e isPlaceOpenRequest em GooglePlacesSwift) que retorna uma resposta indicando se o lugar está aberto no momento, com base no horário especificado na chamada.

Esse método usa um único argumento do tipo GMSPlaceIsOpenWithRequest que contém:

  • Um objeto GMSPlace ou uma string que especifica um ID de lugar. Para mais informações sobre como criar o objeto Place com os campos necessários, consulte Detalhes do lugar.
  • Um objeto NSDate (Obj-C) ou Date (Swift) opcional que especifica o horário que você quer verificar. Se nenhum horário for especificado, o padrão será "agora".
  • Um método GMSPlaceOpenStatusResponseCallback para processar a resposta.
    • >

O método GMSPlaceIsOpenWithRequest exige que os seguintes campos sejam definidos no objeto GMSPlace:

  • GMSPlacePropertyUTCOffsetMinutes
  • GMSPlacePropertyBusinessStatus
  • GMSPlacePropertyOpeningHours
  • GMSPlacePropertyCurrentOpeningHours
  • GMSPlacePropertySecondaryOpeningHours

Se esses campos não forem fornecidos no objeto Place ou se você transmitir um ID de lugar, o método usará GMSPlacesClient GMSFetchPlaceRequest: para buscá-los.

isOpenWithRequest resposta

isOpenWithRequest retorna um objeto GMSPlaceIsOpenResponse que contém um valor booleano chamado status. Ele indica se a empresa está aberta, fechada ou se o status é desconhecido.

Idioma Valor se aberto Valor se fechado Valor se o status for desconhecido
Swift do Google Maps true false nil
Swift .open .closed .unknown
Objective-C GMSPlaceOpenStatusOpen GMSPlaceOpenStatusClosed GMSPlaceOpenStatusUnknown

Faturamento de isOpenWithRequest

  • Os campos GMSPlacePropertyUTCOffsetMinutes e GMSPlacePropertyBusinessStatus são cobrados na SKU Basic Data. O restante do horário de funcionamento é cobrado na SKU empresarial do Place Details.
  • Se o objeto GMSPlace já tiver esses campos de uma solicitação anterior, você não vai receber uma nova cobrança.

Exemplo: fazer uma solicitação GMSPlaceIsOpenWithRequest

O exemplo a seguir mostra como inicializar um GMSPlaceIsOpenWithRequest em um objeto GMSPlace.

SDK do Places para Swift

        let isOpenRequest = IsPlaceOpenRequest(place: place)
        switch await placesClient.isPlaceOpen(with: isOpenRequest) {
          case .success(let isOpenResponse):
            switch isOpenResponse.status {
              case true:
                // Handle open
              case false:
                // Handle closed
              case nil:
                // Handle unknown
          case .failure(let placesError):
            // Handle error
        }

Swift

    let isOpenRequest = GMSPlaceIsOpenRequest(place: place, date: nil)
      GMSPlacesClient.shared().isOpen(with: isOpenRequest) { response, error in
        if let error = error {
          // Handle Error
        }
        switch response.status {
          case .open:
            // Handle open
          case .closed:
            // Handle closed
          case .unknown:
            // Handle unknown
        }
      }

Objective-C

          GMSPlaceIsOpenRequest *isOpenRequest = [[GMSPlaceIsOpenRequest alloc] initWithPlace:place date:nil];

          [[GMSPlacesClient sharedClient] isOpenWithRequest:isOpenRequest callback:^(GMSPlaceIsOpenResponse response, NSError *_Nullable error) {
            if (error) {
              // Handle error
            }

            switch (response.status) {
              case GMSPlaceOpenStatusOpen:
                // Handle open
              case GMSPlaceOpenStatusClosed:
                // Handle closed
              case GMSPlaceOpenStatusUnknown:
                // Handle unknown
            }
          }];

Parâmetros obrigatórios

Use o objeto GMSPlaceSearchByTextRequest para especificar os parâmetros necessários para a pesquisa.

  • Lista de campos

    Especifique quais propriedades de dados de lugar precisam ser retornadas. Transmita uma lista de propriedades GMSPlace especificando os campos de dados a serem retornados. Se você omitir a máscara de campo, a solicitação vai retornar um erro.

    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:

      GMSPlacePropertyPlaceID

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

      GMSPlacePropertyAddressComponents
      GMSPlacePropertyBusinessStatus
      GMSPlacePropertyCoordinate
      GMSPlacePropertyFormattedAddress
      GMSPlacePropertyIconBackgroundColor
      GMSPlacePropertyIconImageURL
      GMSPlacePropertyName
      GMSPlacePropertyPhotos
      GMSPlacePropertyPlusCode
      GMSPlacePropertyTypes
      GMSPlacePropertyUTCOffsetMinutes
      GMSPlacePropertyViewport
      GMSPlacePropertyWheelchairAccessibleEntrance

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

      GMSPlacePropertyCurrentOpeningHours
      GMSPlacePropertySecondaryOpeningHours
      GMSPlacePropertyPhoneNumber
      GMSPlacePropertyPriceLevel
      GMSPlacePropertyRating
      GMSPlacePropertyOpeningHours
      GMSPlacePropertyUserRatingsTotal
      GMSPlacePropertyWebsite

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

      GMSPlacePropertyCurbsidePickup
      GMSPlacePropertyDelivery
      GMSPlacePropertyDineIn
      GMSPlacePropertyEditorialSummary
      GMSPlacePropertyReservable
      GMSPlacePropertyReviews
      GMSPlacePropertyServesBeer
      GMSPlacePropertyServesBreakfast
      GMSPlacePropertyServesBrunch
      GMSPlacePropertyServesDinner
      GMSPlacePropertyServesLunch
      GMSPlacePropertyServesVegetarianFood
      GMSPlacePropertyServesWine
      GMSPlacePropertyTakeout

  • textQuery

    A string de texto em que pesquisar, por exemplo, "restaurante", "Rua Principal, 123" ou "melhor lugar para visitar em São Francisco".

Parâmetros opcionais

Use o objeto GMSPlaceSearchByTextRequest para especificar os parâmetros opcionais da pesquisa.

  • includedType

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

    • let request = SearchByTextRequest()
      request.includedType = "bar"
    • let request = SearchByTextRequest()
      request.includedType = "pharmacy"

  • isOpenNow

    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.

  • isStrictTypeFiltering

    Usado com o parâmetro includeType. Quando definido como true, somente os lugares que correspondem aos tipos especificados por includeType são retornados. Quando é "false" (o padrão), a resposta pode conter lugares que não correspondem aos tipos especificados.

  • locationBias

    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.

    Você pode especificar locationRestriction ou locationBias, mas não ambos. Pense em locationRestriction como a região em que os resultados precisam estar e em locationBias como a região em que os resultados precisam estar próximos, mas podem estar fora da área.

    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. O raio padrão é 0,0. Exemplo:

      let request = SearchByTextRequest()
request.locationBias =  GMSPlaceCircularLocationOption(CLLocationCoordinate2DMake(40.7, -74.0), 200.0)

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

  • locationRestriction

    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 locationBias para informações sobre como definir a janela de visualização.

    Você pode especificar locationRestriction ou locationBias, mas não ambos. Pense em locationRestriction como a região em que os resultados precisam estar e em locationBias como a região em que os resultados precisam estar próximos, mas podem estar fora da área.

  • maxResultCount

    Especifica o número máximo de resultados de lugar a serem retornados. Precisa estar entre 1 e 20 (padrão), inclusive.

  • minRating

    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.

  • priceLevels

    Restringir a pesquisa a lugares marcados em determinados níveis de preço. O padrão é selecionar todos os níveis de preço.

    Especifique uma matriz de um ou mais valores definidos por PriceLevel.

    Exemplo:

        let request = SearchByTextRequest()
    request.priceLevels = [GMSPlacesPriceLevel.moderate.rawValue, GMSPlacesPriceLevel.cheap.rawValue]

  • rankPreference

    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", .relevance (classificar resultados por relevância da pesquisa) é o padrão. É possível definir rankPreference como .relevance ou .distance (classificar os resultados por distância).
    • Para uma consulta não categórica, como "Mountain View, CA", recomendamos que você deixe rankPreference sem definição.

  • regionCode

    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.

  • shouldIncludePureServiceAreaBusinesses

    Se true, retornará empresas de área de serviço puras nos resultados da pesquisa. Uma empresa de serviço local faz visitas ou entregas, mas não atende clientes no endereço comercial dela.

    Exemplo:

    SDK do Places para Swift

    let request = SearchByTextRequest()
request.shouldIncludePureServiceAreaBusinesses = true

    Swift

    let request = SearchByTextRequest()
request.shouldIncludePureServiceAreaBusinesses: true

    Objective-C

    GMSPlaceSearchByTextRequest *request =
    [[GMSPlaceSearchByTextRequest alloc] initWithTextQuery:@"pizza in New York" placeProperties:@[GMSPlacePropertyAll]];
request.shouldIncludePureServiceAreaBusinesses = YES;

Exibir atribuições no seu aplicativo

Quando seu app mostra informações obtidas de GMSPlacesClient, como fotos e avaliações, ele também precisa exibir as atribuições necessárias.

Por exemplo, a propriedade reviews do objeto GMSPlacesClient contém uma matriz de até cinco objetos GMSPlaceReview. Cada objeto GMSPlaceReview pode conter atribuições e atribuições de autoria. Se você mostrar a avaliação no seu app, também precisa mostrar qualquer atribuição ou atribuição de autor.

Para mais informações, consulte a documentação sobre atribuições.