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 que correspondam à string de texto e a qualquer polarização de local definida.

O serviço é particularmente útil para executar 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 mal formatados 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, US" 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.
"Restaurante de cadeia de Nova York" Vários "restaurantes de rede" em Nova York. nenhum endereço ou até mesmo o nome da rua.
"10 High Street, Escher Reino Unido" ou "123 Main Street, Pleasanton US" 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 este nome em Nova York; nenhum endereço necessário diferenciá-las.
"pizzarias em São Paulo" Essa consulta contém a restrição de local, e "pizzarias" é um tipo de lugar bem definido. Ela retorna vários resultados.
"+55 (51) 4670-8700"

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

Acessar uma lista de lugares por pesquisa de texto

Faça uma solicitação do Text Search chamando GMSPlacesClient searchByTextWithRequest:, transmitir um GMSPlaceSearchByTextRequest objeto que define os parâmetros de solicitação e um método de retorno de chamada, do tipo GMSPlaceSearchByTextResultCallback, para lidar com 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 pela GMSPlaceProperty Se você não especificar pelo menos um campo na lista ou se omitir na lista de campos, a chamada retornará um erro.
  • A consulta de texto.

Este exemplo de solicitação de pesquisa de texto especifica que os objetos GMSPlace de resposta contêm o nome e o ID do local de cada objeto GMSPlace na pesquisa resultados. 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 do Text Search

A API Text Search retorna uma matriz de correspondências no forma de GMSPlace objetos, 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 de lugar com os campos necessários, consulte Detalhes do lugar.
  • Um objeto NSDate (Obj-C) ou Date (Swift) opcional que especifica o horário da verificação. Se nenhum horário for especificado, o padrão será agora.
  • Um método GMSPlaceOpenStatusResponseCallback para gerenciar a resposta.
    • &gt;
.

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 contendo 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 de dados básicos. O restante do horário de funcionamento é cobrado com base na SKU do Place Details (Advanced).
  • Se o objeto GMSPlace já tiver esses campos de uma solicitação anterior, não vai haver outra cobrança.

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 parâmetros para a pesquisa.

  • Lista de campos

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

    As listas de campos são uma prática recomendada de design para garantir que você não solicite dados desnecessários, o que ajuda a evitar tempo de processamento desnecessário e cobranças de faturamento adicionais.

    Especifique um ou mais dos seguintes campos:

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

      GMSPlacePropertyPlaceID, GMSPlacePropertyName

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

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

    • Os campos a seguir acionam a SKU do Text Search (avançado):

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

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

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

  • textQuery

    A string de texto a ser pesquisada, por exemplo: "restaurante", "123 Main Street" 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 correspondem 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 locais 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, somente lugares que correspondem aos tipos especificados especificados por includeType são retornadas. Quando é falso, o padrão, a resposta pode conter lugares que não correspondem aos tipos especificados.

  • locationBias

    Especifica uma área a ser pesquisada. 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 os dois. 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 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. 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 e longitude, representada como dois em diagonal opostos a pontos baixo e alto. O ponto mais baixo marca o canto sudoeste do retângulo, e o ponto mais alto representa o canto nordeste do retângulo.

      Uma janela de visualização é considerada uma região fechada, ou seja, inclui seus limites. Os limites de latitude deve variar entre -90 e 90 graus, inclusive, e os limites de longitude deve variar entre -180 e 180 graus:

      • Se low = high, a janela de visualização consistirá em nesse único ponto.
      • Se low.longitude > high.longitude, os o intervalo de longitude é invertido (a janela de visualização cruza o intervalo de 180 graus (linha de longitude).
      • 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 > high.latitude, os o intervalo de latitude está vazio.

  • locationRestriction

    Especifica uma área a ser pesquisada. 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.

    É possível especificar locationRestriction ou locationBias, mas não ambos. Pense em locationRestriction como a especificação região onde os resultados devem estar, e locationBias como especificando a região a que os resultados precisam estar próximos, mas que podem estar fora na área.

  • maxResultCount

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

  • minRating

    Restringe os resultados apenas àqueles cuja avaliação média de usuários seja maior que ou iguais a esse limite. Os valores devem estar entre 0,0 e 5,0 (inclusive) incrementos de 0,5. Por exemplo: 0, 0,5, 1,0, ... , 5,0. Os valores são arredondado para a casa decimal mais próxima. Por exemplo, um valor de 0,6 elimina todas as resultados com uma classificação inferior a 1,0.

  • priceLevels

    Restringir a pesquisa a lugares marcados com 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", O padrão é .relevance (classificar os resultados por relevância da pesquisa). É 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 não for definida para rankPreference.

  • 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 regional, o código do país é 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 os "Reino Unido da Grã-Bretanha e 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 exibe informações recebidas de GMSPlacesClient, como fotos e avaliações, o app também precisará exibir as atribuições necessárias.

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

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