Text Search (novo)

Selecione a plataforma: Android iOS JavaScript Web Service

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

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, o Text Search (novo) oferece suporte ao refinamento de consultas usando parâmetros opcionais para melhores resultados.

Receber uma lista de lugares por pesquisa de texto

Faça uma solicitação de Text Search chamando GMSPlacesClient searchByTextWithRequest:, transmitindo um GMSPlaceSearchByTextRequest objeto 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 obrigatórios e opcionais parâmetros 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 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 contenham o nome e o ID do lugar para cada objeto GMSPlace nos resultados da pesquisa. Ele também filtra a resposta para retornar apenas lugares do tipo "restaurante".

SDK do Places para Swift

let restriction = GMSPlaceRectangularLocationOption(
      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 de Text Search

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

Receber o status de 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:

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.

Resposta isOpenWithRequest

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
Places Swift 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 Place Details Enterprise.
  • Se o objeto GMSPlace já tiver esses campos de uma solicitação anterior, você não será cobrado novamente.

Exemplo: fazer uma solicitação GMSPlaceIsOpenWithRequest

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

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

Paginação

O Text Search fornece um objeto de paginação, o hasNextPage booleano, que é retornado na primeira resposta a uma chamada de Text Search. Se uma próxima página estiver disponível, você poderá usar a função fetchNextPage() para carregá-la.

O exemplo a seguir mostra como verificar se uma próxima página está disponível e, em seguida, carregar a página.

Swift

public struct PlaceSearchPagination {
  public var pageSize: Int
  public var hasNextPage: Bool
  public func fetchNextPage() async -> SearchByTextResponse
}

public struct SearchByTextResponse {
  public var pagination: PlaceSearchPagination?
  public var places: [Place]?
  public var error: PlaceError?
}

PlacesClient.swift
public func searchByText(with request: SearchByTextRequest) async -> SearchByTextResponse

let searchByTextRequest = SearchByTextRequest(textQuery: "restaurants",
    placeProperties: [PlaceProperty.displayName],
    locationBias: CircularCoordinateRegion(center: CLLocationCoordinate2D(latitude: 0, longitude: 0), radius: 100))

searchByTextRequest.maxResultCount = 10

var searchByTextResponse = await PlacesClient.shared.searchByText(with: searchByTextRequest)
print("Found \(searchByTextResponse.places.count) places")

searchByTextResponse.pagination.pageSize = 20

// Continue making requests until no more results are found in pagination object
while searchByTextResponse.pagination.hasNextPage {
    searchByTextResponse = await searchByTextResponse.pagination.fetchNextPage()
    print("Found \(searchByTextResponse.places.count) places")
}

Objective-C

GMSPlaceSearchByTextRequest *searchByTextRequest = [[GMSPlaceSearchByTextRequest alloc]
    initWithTextQuery: @"restaurants"
    placeProperties: @[GMSPlacePropertyAll]];

searchByTextRequest.maxResultCount = 10;

__block void (^recursiveCallback)(GMSPlaceSearchByTextResponse *, NSError *);
recursiveCallback = ^(GMSPlaceSearchByTextResponse * response, NSError* error) {
    NSLog(@"Found %d places", response.places.count);
    if (response.pagination.hasNextPage) {
      [response.pagination fetchNextPageWithCompletion:recursiveCallback];
   }
};
[GMSPlacesClient.sharedClient searchByTextWithRequest:searchByTextRequest  
                                           completion:recursiveCallback];

Parâmetros obrigatórios

Use o objeto GMSPlaceSearchByTextRequest para especificar os parâmetros obrigatórios da pesquisa.

  • Lista de campos

    Especifique quais propriedades de dados de lugar precisam ser retornadas. Transmita uma lista de GMSPlace propriedades que especifiquem 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 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 a 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 a 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 Rua" 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 por Tabela A. Apenas um tipo pode ser especificado. Exemplo:

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

  • 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 aberto. 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, apenas os lugares que correspondem aos tipos especificados por includeType são retornados. Quando definido como 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 um direcionamento, o que significa que resultados em torno 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 especificação da região em que os resultados precisam estar e 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:

      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 diagonalmente opostos pontos baixos e altos. O ponto baixo marca o canto sudoeste do retângulo, e o ponto alto representa o canto nordeste do retângulo.

      Uma janela de visualização é considerada uma região fechada, o que significa que ela inclui o limite. Os limites de latitude precisam variar entre -90 e 90 graus, inclusive, e os limites de longitude precisam variar entre -180 e 180 graus, inclusive:

      • 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 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 especificação da região em que os resultados precisam estar e 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 lugares a serem retornados. Precisa estar entre 1 e 20 (padrão), inclusive.

  • minRating

    Restringe os resultados apenas àqueles cuja avaliação de usuários média seja 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

    Restringe 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 query:

    • Para uma consulta categórica, como "Restaurantes na cidade de Nova York", .relevance (classificar os resultados por relevância da pesquisa) é o padrão. 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 que você deixe rankPreference não definido.

  • regionCode

    O código regional 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 direcionamento 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 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 do "Reino Unido da Grã-Bretanha e Irlanda do Norte"). O parâmetro pode afetar os resultados com base na lei aplicável.

  • shouldIncludePureServiceAreaBusinesses

    Se true, retorna empresas de serviço local nos resultados da pesquisa. Uma empresa de serviço local é uma empresa que 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 o app mostra informações obtidas de 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 GMSPlaceReview objetos. 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 de autor.

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