Text Search (novo)

Selecione a plataforma: Android iOS JavaScript Serviço da Web

Esse recurso exige a ativação da API Places (nova), a próxima geração da API Places. Para mais informações, consulte Ativar APIs.

Uma Text Search retorna informações sobre um conjunto de locais 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 componentes da string que não são endereços 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 endereços, 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, UK" ou "123 Main Street, EUA"	Várias "High Street" no Reino Unido e várias "Main Street" nos EUA. A consulta não retorna os resultados desejáveis, a menos que uma restrição de local tenha sido definida.
"Restaurante de cadeia de Nova York"	Vários "restaurantes de rede" em Nova York, sem endereço ou nome de rua.
"10 High Street, Escher UK" ou "123 Main Street, Pleasanton US"	Somente uma "High Street" na cidade de Escher, no Reino Unido, e apenas uma "Main Street" na cidade de Pleasanton CA, nos EUA.
"UniqueRestaurantName New York"	Apenas um estabelecimento com esse nome em Nova York. Não é necessário diferenciar um endereço.
"pizzarias em São Paulo"	Essa consulta contém a restrição de local, e "pizzaria" é um tipo de lugar bem definido. Ela retorna vários resultados.
"[phone]"	Esta consulta contém um número de telefone. Ela retorna vários resultados para lugares associados a esse número de telefone. 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.

Acessar uma lista de lugares por pesquisa de texto

Faça uma solicitação do Text Search 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 ou omitir a lista, 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 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;
      }
    }
  }
];

GooglePlacesSwift

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 na forma de objetos GMSPlace, com um objeto GMSPlace por lugar correspondente.

Observação : os campos do objeto de resposta GMSPlace não podem ficar vazios. Por exemplo, se a lista de campos incluir GMSPlacePropertyPhotos para solicitar o campo photos em resposta e o campo photos na resposta estiver vazio, ele será omitido do objeto GMSPlace da resposta.

Além dos campos de dados, o objeto GMSPlace na resposta contém as seguintes funções de membro:

• isOpen calcula se um lugar está aberto no horário especificado.
• isOpenAtDate calcula se um lugar está aberto em uma determinada data.

Observação: essas funções só ficam disponíveis quando você ativa o SDK do Places para iOS. Eles não estão disponíveis quando você ativa o SDK do Places para iOS (novo). Para mais informações, consulte Escolher a versão do SDK.

Parâmetros obrigatórios

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

• Lista de campos

  Especifique quais propriedades dos dados de lugar serão 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 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. Isso ajuda a evitar cobranças desnecessárias no tempo de processamento e nas cobranças.

  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 e 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 e GMSPlacePropertyTakeout

• textQuery

  A string de texto a ser pesquisada, por exemplo: "restaurante", "Avenida 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:

  • request.includedType = "bar"
  • request.includedType = "pharmacy"
  Observação : os valores na Tabela B são retornados apenas na resposta. Não é possível usar os valores na Tabela B como um filtro.

• isOpenNow

  Se true, retorna apenas os lugares que estão abertos no momento em que a consulta é enviada. Se false, retorna todas as empresas, independentemente do status de abertura. Locais que não especificam horário de funcionamento no banco de dados do Google Places serão retornados se você definir esse parâmetro como false.

• isStrictTypeFiltering

  Usado com o parâmetro includeType. Quando definido como true, apenas lugares que correspondem aos tipos especificados especificados por includeType são retornados. Quando definido como falso, o padrão, a resposta pode conter locais que não correspondam aos tipos especificados.

• locationBias

  Especifica uma área a ser pesquisada. Essa localização serve como um direcionamento que significa que resultados ao redor 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 locationBias como a especificação da região a que os resultados precisam estar próximos, mas podem estar fora da área.

  Observação : se você omitir locationBias e locationRestriction, 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 direcionar os resultados.
  Observação : o parâmetro locationBias poderá ser substituído se 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. 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 pontos baixo e alto diagonalmente opostos. 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, o que significa que ela inclui seus limites. 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 janela de visualização consistirá nesse único ponto.
    • Se low.longitude > high.longitude, o intervalo de longitude é 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 incluirá 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.

• 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 da região em que os resultados precisam estar, e locationBias como a especificação da região a que os resultados precisam estar próximos, mas podem estar fora da área.

  Observação : se você omitir locationBias e locationRestriction, 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 direcionar os resultados.

• 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 com uma classificaçã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. Os valores são arredondados para a casa decimal mais próxima. 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 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.

  Observação : não é permitido usar PRICE_LEVEL_FREE em uma solicitação. Ele é usado apenas para preencher a resposta.

  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). Você pode definir rankPreference como .relevance ou .distance (classificar os resultados por distância).
  • Para uma consulta não categórica, como "Mountain View, CA", recomendamos deixar 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 influenciar os 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, esse código 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.

Exibir atribuições no seu aplicativo

Quando o app exibe informações coletadas em GMSPlacesClient, como fotos e avaliações, ele também precisa mostrar 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 app, também vai ser necessário mostrar qualquer atribuição ou atribuição de autor.

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