Text Search (novo)

Selecione a plataforma: Android iOS JavaScript Web Service

Uma 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 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 os componentes não relacionados a endereço da string 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.

"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.
"Rede de restaurantes em Nova York" Vários locais da "rede de restaurantes" em Nova York, sem endereço ou nome da 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 "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 para a 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 de campos, 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 do lugar de cada objeto GMSPlace nos resultados da pesquisa. Ele também filtra a resposta para retornar apenas lugares do tipo "restaurante".

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;
      }
    }
  }
];

SDK do Places Swift para iOS (pré-lançamento)

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
}

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 aberto

O objeto GMSPlacesClient contém uma função de membro chamada isOpenWithRequest (isOpenRequest no Swift e isPlaceOpenRequest no 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á o horário atual.
  • 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 vai usar GMSPlacesClient GMSFetchPlaceRequest: para buscá-los.

isOpenWithRequest resposta

isOpenWithRequest retorna um objeto GMSPlaceIsOpenResponse que contém um valor booleano chamado status, que 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 .open .closed .unknown
Objective-C GMSPlaceOpenStatusOpen GMSPlaceOpenStatusClosed GMSPlaceOpenStatusUnknown
GooglePlacesSwift (pré-lançamento) true false nil

Faturamento de isOpenWithRequest

  • Os campos GMSPlacePropertyUTCOffsetMinutes e GMSPlacePropertyBusinessStatus são cobrados na SKU Basic Data. O restante dos horários de funcionamento é cobrado na SKU Places Details (Advanced).
  • Se o objeto GMSPlace já tiver esses campos de uma solicitação anterior, não haverá cobrança novamente.

Exemplo: fazer uma solicitação GMSPlaceIsOpenWithRequest

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

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
            }
          }];

GooglePlacesSwift

          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
          }

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 do lugar serão retornadas. Transmita uma lista de propriedades GMSPlace que especificam 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ários.

    Especifique um ou mais dos seguintes campos:

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

      GMSPlacePropertyPlaceID, GMSPlacePropertyName

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

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

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

      GMSPlacePropertyCurrentOpeningHours, GMSPlacePropertySecondaryOpeningHours, GMSPlacePropertyPhoneNumber, GMSPlacePropertyPriceLevel, GMSPlacePropertyRating, GMSPlacePropertyOpeningHours, GMSPlacePropertyUserRatingsTotal, GMSPlacePropertyWebsite

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

      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 Paulo".

Parâmetros opcionais

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

  • includedType

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

    • request.includedType = "bar"
    • request.includedType = "pharmacy"

  • isOpenNow

    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 o 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, apenas os lugares que correspondem aos tipos especificados por includeType são retornados. Quando é falso, 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 em torno do local especificado podem ser retornados, incluindo resultados fora da área especificada.

    É possível especificar locationRestriction ou locationBias, mas não ambos. Pense em locationRestriction como a especificação da região em que os resultados precisam estar e em locationBias como a especificação da 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 pelo ponto central e pelo raio em metros. O raio precisa estar entre 0,0 e 500.000,0. O raio padrão é 0,0. Exemplo:

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

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

    É possível especificar locationRestriction ou locationBias, mas não ambos. Pense em locationRestriction como a especificação da região em que os resultados precisam estar e em locationBias como a especificação da 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 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.

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

    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 Nova York", .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 indefinido.

  • regionCode

    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.

Exibir atribuições no seu aplicativo

Quando o 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 autor. Se você mostrar a avaliação no seu app, também precisará mostrar qualquer atribuição ou atribuição do autor.

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