Nearby Search (novo)

Uma solicitação de Nearby Search (novo) usa como entrada a região a ser pesquisada, especificada como um círculo definido pelas coordenadas de latitude e longitude do ponto central do círculo e o raio em metros. A solicitação retorna uma lista de lugares correspondentes, cada um representado por um objeto GMSPlace na área de pesquisa especificada.

Por padrão, a resposta contém lugares de todos os tipos na área de pesquisa. Você pode filtrar a resposta especificando uma lista de tipos de lugares para incluir ou excluir explicitamente da resposta. Por exemplo, é possível especificar que a resposta inclua apenas os lugares do tipo "restaurante", "padaria" e "café", ou excluir todos os lugares do tipo "escola".

Solicitações do Nearby Search (novo)

Faça uma solicitação de pesquisa nas proximidades chamando GMSPlacesClient searchNearbyWithRequest:, transmitindo um objeto GMSPlaceSearchNearbyRequest que define os parâmetros da solicitação e um método de callback, do tipo GMSPlaceSearchNearbyResultCallback, para processar a resposta.

O objeto GMSPlaceSearchNearbyRequest 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 restrição de local, ou seja, o círculo que define a área de pesquisa.

Este exemplo de solicitação de pesquisa por proximidade especifica que os objetos de resposta GMSPlace contêm o nome do lugar (GMSPlacePropertyName) e as coordenadas do lugar (GMSPlacePropertyCoordinate) para cada objeto GMSPlace nos resultados da pesquisa. Ele também filtra a resposta para retornar apenas lugares do tipo "restaurante" e "café".

let restriction = CircularCoordinateRegion(center: CLLocationCoordinate2DMake(37.7937, -122.3965), radius: 500)
let searchNearbyRequest = SearchNearbyRequest(
  locationRestriction: restriction,
  placeProperties: [ .name, .coordinate],
  includedTypes: [ .restaurant, .cafe ],
)
switch await placesClient.searchNearby(with: searchNearbyRequest) {
case .success(let places):
  // Handle places
case .failure(let placesError):
  // Handle error
}

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

// Define the search area as a 500 meter diameter circle in San Francisco, CA.
let circularLocationRestriction = GMSPlaceCircularLocationOption(CLLocationCoordinate2DMake(37.7937, -122.3965), 500)

// Specify the fields to return in the GMSPlace object for each place in the response.
let placeProperties = [GMSPlaceProperty.name, GMSPlaceProperty.coordinate].map {$0.rawValue}

// Create the GMSPlaceSearchNearbyRequest, specifying the search area and GMSPlace fields to return.
var request = GMSPlaceSearchNearbyRequest(locationRestriction: circularLocationRestriction, placeProperties: placeProperties)
let includedTypes = ["restaurant", "cafe"]
request.includedTypes = includedTypes

let callback: GMSPlaceSearchNearbyResultCallback = { [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().searchNearby(with: request, callback: callback)

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

// Define the search area as a 500 meter diameter circle in San Francisco, CA.
id<GMSPlaceLocationRestriction> circularLocation = GMSPlaceCircularLocationOption(CLLocationCoordinate2DMake(37.7937, -122.3965), 500);

// Create the GMSPlaceSearchNearbyRequest, specifying the search area and GMSPlace fields to return.
GMSPlaceSearchNearbyRequest *request = [[GMSPlaceSearchNearbyRequest alloc]
  initWithLocationRestriction:circularLocation
              placeProperties:@[ GMSPlacePropertyName, GMSPlacePropertyCoordinate ]];

// Set the place types to filter on.
NSArray<NSString *> *includedTypes = @[ @"restaurant", @"cafe" ];
request.includedTypes = [[NSMutableArray alloc] initWithArray:includedTypes];

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

Respostas da pesquisa nas proximidades

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.

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

        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
        }
        

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

          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 GMSPlaceSearchNearbyRequest para especificar os parâmetros necessários para a pesquisa.

• Lista de campos

  Ao solicitar detalhes de um lugar, você precisa especificar os dados a serem retornados no objeto GMSPlace do lugar como uma máscara de campo. Para definir a máscara de campo, transmita uma matriz de valores de GMSPlaceProperty para o objeto GMSPlaceSearchNearbyRequest. A máscara de campo é 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 Nearby Search Pro:

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

  • Os campos a seguir acionam a SKU do Nearby Search Enterprise:

    GMSPlacePropertyCurrentOpeningHours
GMSPlacePropertySecondaryOpeningHours
GMSPlacePropertyPhoneNumber
GMSPlacePropertyPriceLevel
GMSPlacePropertyRating
GMSPlacePropertyOpeningHours
GMSPlacePropertyUserRatingsTotal
GMSPlacePropertyWebsite

  • Os campos a seguir acionam a SKU do Nearby Search Enterprise Plus:

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

  O exemplo a seguir transmite uma lista de dois valores de campo para especificar que o objeto GMSPlace retornado por uma solicitação contém os campos name e placeID:

  SDK do Places para Swift

  // Specify the place data types to return.
  let fields: [PlaceProperty] = [.placeID, .displayName]
          

  Swift

  // Specify the place data types to return.
  let fields: [GMSPlaceProperty] = [.placeID, .name]
          

  Objective-C

  // Specify the place data types to return.
  NSArray<GMSPlaceProperty *> *fields = @[GMSPlacePropertyPlaceID, GMSPlacePropertyName];
          

• locationRestriction

  Um objeto GMSPlaceLocationRestriction que define a região a ser pesquisada especificada como um círculo, definido por ponto central e raio em metros. O raio precisa estar entre 0,0 e 50.000,0, incluindo esses dois valores. O raio padrão é 0,0. Defina na solicitação um valor maior que 0,0.

Parâmetros opcionais

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

• includedTypes/excludedTypes, includedPrimaryTypes/excludedPrimaryTypes

  Permite especificar uma lista de tipos da Tabela A usada para filtrar os resultados da pesquisa. É possível especificar até 50 tipos em cada categoria de restrição.

  Um lugar só pode ter um único tipo principal da Tabela A associado a ele. Por exemplo, o tipo principal pode ser "mexican_restaurant" ou "steak_house". Use includedPrimaryTypes e excludedPrimaryTypes para filtrar os resultados no tipo principal de um lugar.

  Um lugar também pode ter vários valores de tipo da Tabela A associados a ele. Por exemplo, um restaurante pode ter os seguintes tipos: "seafood_restaurant", "restaurant", "food", "point_of_interest", "establishment". Use includedTypes e excludedTypes para filtrar os resultados na lista de tipos associados a um lugar.

  Quando você especifica um tipo principal geral, como "restaurant" ou "hotel", a resposta pode conter lugares com um tipo principal mais específico do que o especificado. Por exemplo, você especifica incluir um tipo principal de "restaurant". A resposta pode conter lugares com um tipo principal de "restaurant", mas também pode incluir lugares com um tipo principal mais específico, como "chinese_restaurant" ou "seafood_restaurant".

  Se uma pesquisa for especificada com várias restrições de tipo, somente os lugares que atendem a todas as restrições serão retornados. Por exemplo, se você especificar {"includedTypes": ["restaurant"], "excludedPrimaryTypes": ["steak_house"]}, os lugares retornados vão oferecer serviços relacionados a "restaurant", mas não vão operar principalmente como um "steak_house".

  includedTypes

  Uma lista dos tipos de lugar da Tabela A para pesquisar. Se esse parâmetro for omitido, os lugares de todos os tipos serão retornados.

  excludedTypes

  Uma lista de tipos de lugar da Tabela A para excluir de uma pesquisa.

  Se você especificar includedTypes (como "school") e excludedTypes (como "primary_school") na solicitação, a resposta vai incluir lugares categorizados como "school", mas não como "primary_school". A resposta inclui lugares que correspondem a pelo menos um dos includedTypes e nenhum dos excludedTypes.

  Se houver tipos conflitantes, como um tipo que aparece em includedTypes e excludedTypes, um erro INVALID_REQUEST será retornado.

  includedPrimaryTypes

  Uma lista de tipos de lugar principais da Tabela A para incluir em uma pesquisa.

  excludedPrimaryTypes

  Uma lista de tipos de lugar principais da Tabela A para excluir de uma pesquisa.

  Se houver tipos principais conflitantes, como um tipo que aparece em includedPrimaryTypes e excludedPrimaryTypes, um erro INVALID_ARGUMENT será retornado.

• maxResultCount

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

• rankPreference

  O tipo de classificação a ser usado. Se esse parâmetro for omitido, os resultados serão classificados por popularidade. Pode ser um dos seguintes:

  • .popularity (padrão): classifica os resultados com base na popularidade.
  • .distance Classifica os resultados em ordem crescente de distância do local especificado.

• regionCode

  O código da região usado para formatar a resposta, especificado como um valor de código CLDR de dois caracteres. Não há valor padrão.

  Se o nome do país do campo formattedAddress na resposta corresponder ao regionCode, o código do país será omitido de formattedAddress. Esse parâmetro não tem efeito em adrFormatAddress, que sempre inclui o nome do país, ou em shortFormattedAddress, que nunca inclui.

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