Detalhes do lugar (novo)

Selecione a plataforma: Android iOS JavaScript Web Service

O SDK Places para iOS (novo) fornece ao seu app informações detalhadas sobre lugares, incluindo o nome e o endereço do lugar, a localização geográfica especificada como coordenadas de latitude/longitude, o tipo de lugar (por exemplo, boate, pet shop, museu) e muito mais. Para acessar essas informações em um lugar específico, use o ID do lugar, um identificador estável que identifica um lugar de forma exclusiva.

Conferir detalhes sobre o lugar

A classe GMSPlace contém informações sobre um lugar específico, incluindo todos os campos de dados mostrados em Campos de dados do lugar (novo). Receba um objeto GMSPlace chamando GMSPlacesClient fetchPlaceWithRequest:, transmitindo um objeto GMSFetchPlaceRequest e um método de callback do tipo GMSPlaceResultCallback.

O objeto GMSFetchPlaceRequest especifica:

  • (Obrigatório) O ID do lugar, um identificador exclusivo de um lugar no banco de dados do Google Places e no Google Maps.
  • (Obrigatório) 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.
  • (Opcional) O código da região usado para formatar a resposta.
  • (Opcional) O token de sessão usado para encerrar uma sessão de preenchimento automático (nova).

Fazer uma solicitação de detalhes do lugar

Este exemplo recebe um lugar por ID, transmitindo os seguintes parâmetros:

  • O ID do lugar de ChIJV4k8_9UodTERU5KXbkYpSYs.
  • Uma lista de campos que especifica o retorno do nome do lugar e do URL do site.
  • Um GMSPlaceResultCallback para processar o resultado.

A API invoca o método de callback especificado, transmitindo um objeto GMSPlace. Se o local não for encontrado, o objeto de local é nulo.

Swift

// A hotel in Saigon with an attribution.
let placeID = "ChIJV4k8_9UodTERU5KXbkYpSYs"

// Specify the place data types to return.
let myProperties = [GMSPlaceProperty.name, GMSPlaceProperty.website].map {$0.rawValue}

// Create the GMSFetchPlaceRequest object.
let fetchPlaceRequest = GMSFetchPlaceRequest(placeID: placeID, placeProperties: myProperties, sessionToken: nil)

client.fetchPlace(with: fetchPlaceRequest, callback: {
  (place: GMSPlace?, error: Error?) in
  guard let place, error == nil else { return }
  print("Place found: \(String(describing: place.name))")
})

Objective-C

// A hotel in Saigon with an attribution.
NSString *placeID = @"ChIJV4k8_9UodTERU5KXbkYpSYs";

// Specify the place data types to return.
NSArray<NSString *> *myProperties = @[GMSPlacePropertyName, GMSPlacePropertyWebsite];

// Create the GMSFetchPlaceRequest object.
GMSFetchPlaceRequest *fetchPlaceRequest = [[GMSFetchPlaceRequest alloc] initWithPlaceID:placeID placeProperties: myProperties sessionToken:nil];

[placesClient fetchPlaceWithRequest: fetchPlaceRequest callback: ^(GMSPlace *_Nullable place, NSError *_Nullable error) {
    if (error != nil) {
      NSLog(@"An error occurred %@", [error localizedDescription]);
      return;
    } else {
    NSLog(@"Place Found: %@", place.name);
    NSLog(@"The place URL: %@", place.website);
  }
}];

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

// A hotel in Saigon with an attribution.
let placeID = "ChIJV4k8_9UodTERU5KXbkYpSYs"
let fetchPlaceRequest = FetchPlaceRequest(
  placeID: placeID,
  placeProperties: [.name, .website]
)
switch await placesClient.fetchPlace(with: fetchPlaceRequest) {
case .success(let place):
  // Handle place
case .failure(let placesError):
  // Handle error
}

Resposta do Place Details

O Place Details retorna um objeto GMSPlace que contém detalhes sobre o lugar. Somente os campos especificados na lista de campos são preenchidos no objeto GMSPlace.

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 Place Details (Advanced).
  • Se o objeto GMSPlace já tiver esses campos de uma solicitação anterior, você não vai receber cobranças 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 GMSFetchPlaceRequest para especificar os parâmetros necessários.

ID do lugar

O ID de lugar usado no SDK do Places para iOS é o mesmo identificador usado na API Places, no SDK do Places para Android e em outras APIs do Google. Cada ID de lugar pode se referir a apenas um lugar, mas um único lugar pode ter mais de um ID.

Há circunstâncias que podem fazer com que um lugar receba um novo ID. Por exemplo, isso pode acontecer se uma empresa se mudar para outra localidade.

Ao solicitar um lugar especificando um ID, você pode ter certeza de que sempre vai receber o mesmo lugar na resposta (se ele ainda existir). No entanto, a resposta pode conter um ID de lugar diferente do que está na sua solicitação.

Lista de campos

Ao solicitar detalhes do lugar, é necessário 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 GMSFetchPlaceRequest. O mascaramento 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ários.

Especifique um ou mais dos seguintes campos:

  • Os campos a seguir acionam a SKU Place Details (Only ID):

    GMSPlacePropertyPlaceID, GMSPlacePropertyName, GMSPlacePropertyPhotos

  • Os campos a seguir acionam a SKU Place Details (Only Location):

    GMSPlacePropertyAddressComponents, GMSPlacePropertyFormattedAddress, GMSPlacePropertyCoordinate, GMSPlacePropertyPlusCode, GMSPlacePropertyTypes, GMSPlacePropertyViewport

  • Os campos a seguir acionam a SKU Place Details (Basic):

    GMSPlacePropertyBusinessStatus, GMSPlacePropertyIconBackgroundColor, GMSPlacePropertyIconImageURL, GMSPlacePropertyUTCOffsetMinutes, GMSPlacePropertyWheelchairAccessibleEntrance

  • Os campos a seguir acionam a SKU Place Details (Advanced):

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

  • Os campos a seguir acionam a SKU Place Details (Preferred):

    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:

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

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

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

Parâmetros opcionais

Use o objeto GMSFetchPlaceRequest para especificar os parâmetros opcionais.

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 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), e 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.

sessionToken

Os tokens de sessão são strings geradas pelo usuário que rastreiam chamadas de preenchimento automático (Novo) como "sessões". O preenchimento automático (novo) usa tokens de sessão para agrupar as fases de consulta e seleção de local de uma pesquisa de preenchimento automático do usuário em uma sessão discreta para fins de faturamento. Os tokens de sessão são transmitidos para as chamadas do Place Details (novo) que seguem as chamadas do Autocomplete (novo). Para mais informações, consulte Tokens de sessão.

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