Detalhes do lugar (novo)

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

O SDK do Places para iOS (novo) fornece ao seu app informações detalhadas sobre os lugares, incluindo o nome e o endereço deles, a localização geográfica especificada como coordenadas de latitude/longitude, o tipo de lugar (como boate, pet shop, museu) e muito mais. Para acessar essas informações de um local específico, use o ID de lugar, um identificador estável que identifica um local 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 de lugares (novos). Consiga 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 local 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 ou omitir a lista, a chamada 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 Autocomplete (novo).

Fazer uma solicitação ao Place Details

Este exemplo obtém um local por ID, passando os seguintes parâmetros:

• ID de lugar de ChIJV4k8_9UodTERU5KXbkYpSYs.
• Uma lista de campos especificando 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, .website]

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

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

Objective-C

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

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

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

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

GooglePlacesSwift

// 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 contendo detalhes sobre o lugar. Somente os campos especificados na lista são preenchidos no objeto GMSPlace.

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 na resposta, e o campo photos na resposta estiver vazio, ele será omitido do objeto GMSPlace da resposta.

Junto com os 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 ficam 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 GMSFetchPlaceRequest para especificar os parâmetros obrigatórios.

ID do lugar

O ID do 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 só pode se referir a um local, mas um único local pode ter mais de um ID.

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

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

Lista de campos

Ao solicitar detalhes do lugar, é necessário especificar os dados a serem retornados no objeto GMSPlace para o local 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 cobranças de faturamento e tempo de processamento desnecessários.

Especifique um ou mais dos seguintes campos:

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

  GMSPlacePropertyPlaceID, GMSPlacePropertyName, GMSPlacePropertyPhotos

• Os campos a seguir acionam a SKU do Place Details (somente local):

  GMSPlacePropertyAddressComponents, GMSPlacePropertyFormattedAddress, GMSPlacePropertyCoordinate, GMSPlacePropertyPlusCode, GMSPlacePropertyTypes, GMSPlacePropertyViewport

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

  GMSPlacePropertyBusinessStatus, GMSPlacePropertyIconBackgroundColor, GMSPlacePropertyIconImageURL, GMSPlacePropertyUTCOffsetMinutes e GMSPlacePropertyWheelchairAccessibleEntrance

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

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

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

  GMSPlacePropertyCurbsidePickup, GMSPlacePropertyDelivery, GMSPlacePropertyDineIn, GMSPlacePropertyEditorialSummary, GMSPlacePropertyReservable, GMSPlacePropertyReviews, GMSPlacePropertyServesBeer, GMSPlacePropertyServesBreakfast, GMSPlacePropertyServesBrunch, GMSPlacePropertyServesDinner, GMSPlacePropertyServesLunch, GMSPlacePropertyServesVegetarianFood, GMSPlacePropertyServesWine e 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];
  

GooglePlacesSwift

// 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 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 viés sobre 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.

sessionToken

Os tokens de sessão são strings geradas pelo usuário que rastreiam chamadas de preenchimento automático (novas) como "sessões". O Autocomplete (novo) usa tokens de sessão para agrupar as fases de consulta e seleção de lugar 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 chamadas do Place Details (nova) que seguem chamadas do Autocomplete (nova). Para mais informações, consulte Tokens de sessão.

Exibir atribuições no seu aplicativo

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

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