O SDK do Places para iOS fornece ao seu app informações valiosas sobre lugares, incluindo o nome e o endereço do local, a localização geográfica especificada por 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 exclusivamente um local.
Detalhes do lugar
A classe GMSPlace
apresenta informações sobre um lugar específico. Você pode conseguir um objeto GMSPlace
das seguintes maneiras:
- Chame
GMSPlacesClient findPlaceLikelihoodsFromUserLocationWithPlaceFields:
. Consulte o guia para acessar o lugar atual. - Chame
GMSPlacesClient fetchPlaceFromPlaceID:
, transmitindo umGMSPlaceField
, um ID de lugar e um método de callback. Para solicitações do Place Details, se você não especificar pelo menos um campo com uma solicitação ou omitir o parâmetrofields
de uma solicitação, TODOS os campos possíveis serão retornados, e você será cobrado de acordo. Consulte o guia sobre como ver um local por ID.
Ao solicitar um lugar, é necessário especificar quais tipos de dados retornar. Para fazer isso, transmita um GMSPlaceField
, especificando os tipos de dados a serem retornados. Essa é uma consideração importante, já que afeta o custo de cada solicitação.
Como os resultados de dados de lugar não podem estar vazios, somente aqueles com dados são retornados (por exemplo, se um lugar solicitado não tiver fotos, o campo photos
não estará presente no resultado).
O exemplo a seguir transmite uma lista de dois valores de campo para especificar os dados retornados por uma solicitação:
Swift
// A hotel in Saigon with an attribution. let placeID = "ChIJV4k8_9UodTERU5KXbkYpSYs" // Specify the place data types to return. let fields: GMSPlaceField = GMSPlaceField(rawValue: UInt(GMSPlaceField.name.rawValue) | UInt(GMSPlaceField.placeID.rawValue))
Objective-C
// A hotel in Saigon with an attribution. NSString *placeID = @"ChIJV4k8_9UodTERU5KXbkYpSYs"; // Specify the place data types to return. GMSPlaceField fields = (GMSPlaceFieldName | GMSPlaceFieldPlaceID);
Saiba mais sobre os campos de local. Para mais informações sobre como as solicitações de dados de lugar são faturadas, consulte Uso e faturamento.
A classe GMSPlace
pode conter os seguintes dados de lugar:
name
: o nome do local.editorialSummary
: fornece uma descrição simples de um lugar.placeID
: identificador textual do local. Leia mais sobre IDs de local no restante desta página.coordinate
: a localização geográfica do lugar, especificada por coordenadas de latitude e longitude.phoneNumber
: o número de telefone do local, no formato internacional.formattedAddress
: o endereço legível do local.Esse endereço costuma ser equivalente ao endereço postal. Alguns países, como o Reino Unido, não permitem a distribuição de endereços postais verdadeiros devido a restrições de licenciamento.
O endereço formatado é composto de maneira lógica por um ou mais componentes de endereço. Por exemplo, o endereço "Avenida Paulista, 111, São Paulo, SP" consiste nos seguintes componentes: "Avenida Paulista" (o trajeto), "111" (o número), "São Paulo" (a cidade) e "SP" (o estado brasileiro).
Não analise o endereço formatado de maneira programática. Em vez disso, use os componentes de endereço individuais, que a resposta da API inclui, além do campo de endereço formatado.
openingHours
: o horário de funcionamento do lugar (como representado porGMSOpeningHours
). ChameGMSOpeningHours.weekdayText
para ver uma lista de strings localizadas dos horários de funcionamento diários da semana. ChameGMSOpeningHours.Periods
para retornar uma lista deGMSPeriod
s com informações mais detalhadas que são equivalentes aos dados fornecidos porweekdayText
. Observação:quando um lugar está sempre aberto, o período é representado como domingo à meia-noite, ecloseEvent
é nulo.currentOpeningHours
esecondaryOpeningHours
: campos que incluem feriados e mudanças temporárias na programação de um lugar.addressComponents
: uma matriz de objetosGMSAddressComponent
que representam componentes do endereço de um lugar. Esses componentes são fornecidos com o objetivo de extrair informações estruturadas sobre o endereço de um local, por exemplo, encontrar a cidade em que um lugar está localizado. Não use esses componentes para formatar o endereço. Em vez disso, use a propriedadeformattedAddress
, que fornece um endereço formatado localizado.Observe os seguintes fatos sobre a matriz
addressComponents
:- A matriz de componentes de endereço pode conter mais componentes do que
formattedAddress
. - A matriz não inclui necessariamente todas as entidades políticas que contêm um endereço, além daquelas incluídas em
formattedAddress
. - Não há garantia de que o formato da resposta vai permanecer o mesmo entre as solicitações. Especificamente, o número de
addressComponents
varia de acordo com o endereço solicitado e pode mudar para o mesmo endereço. Um componente pode mudar a posição na matriz. O tipo do componente pode mudar. Pode faltar um componente específico em uma resposta posterior.
- A matriz de componentes de endereço pode conter mais componentes do que
userRatingsTotal
: representa quantas avaliações compõem a classificação do lugar.
A classe GMSPlace
contém as seguintes funções de membro:
-
isOpen
calcula se um lugar está aberto no horário especificado, com base emopeningHours
eUTCOffsetMinutes
, além da data e hora atuais. isOpenAtDate
calcula se um lugar está aberto em uma determinada data, com base emopeningHours
eUTCOffsetMinutes
, além da data e hora atuais.
Ao usar essas funções para obter horários e/ou datas de abertura, a solicitação fetchPlaceFromPlaceID:
ou findPlaceLikelihoodsFromUserLocationWithPlaceFields:
original precisa especificar os campos GMSPlaceFieldOpeningHours
e GMSPlaceFieldUTCOffsetMinutes
. Se um desses campos estiver ausente, o objeto GMSPlace
resultante não vai conter horários nem datas de abertura, e a chamada vai retornar
GMSPlaceOpenStatusUnknown
. Para garantir resultados precisos, inclua os campos GMSPlaceFieldBusinessStatus
e GMSPlaceFieldUTCOffsetMinutes
na sua solicitação de lugar original. Quando ele não é solicitado, presume-se que
a empresa está funcionando.
isOpen
com o Place Details.
Horários de funcionamento excepcionais
Embora o horário de funcionamento normal seja informado atéopeningHours
, as currentOpeningHours
e a secondaryOpeningHours
aceitam mudanças temporárias e em feriados.
Os horários de funcionamento excepcionais para esses dias especiais podem ser filtrados e apresentados, se disponíveis.
Swift
func examineOpeningHours(place: GMSPlace) { // Check if the current opening hours contains a special day that has exceptional hours guard let currentOpeningHours = place.currentOpeningHours else { return } if let specialDays = currentOpeningHours.specialDays { guard !specialDays.isEmpty else { return } if let specialDay = specialDays.filter { $0.isExceptional }.first { // Indicate exceptional hours } } // Check if current opening hours contains a truncated time period let periods = currentOpeningHours.periods if !periods.isEmpty { for period in periods { let open = period.open let close = period.close if let open = open { let date = open.date if open.isTruncated { // Indicate truncated time period } } } } // Check if the place's secondary opening hours indicate when delivery is available let secondaryOpeningHours = place.secondaryOpeningHours guard let hoursType = secondaryOpeningHours.first?.hoursType else { return } if (hoursType == GMSPlaceHoursTypeDelivery) { // Indicate hours where delivery is available } }
Objective-C
- (void)examineOpeningHours:(GMSPlace *) place { // Check if the current opening hours contains a special day that has exceptional hours GMSOpeningHours *currentOpeningHours = place.currentOpeningHours; if (currentOpeningHours != nil) { NSArray<GMSPlaceSpecialDay *> *specialDays = currentOpeningHours.specialDays; if ([specialDays count] != 0) { for (GMSPlaceSpecialDay *specialDay in specialDays) { NSDate *date = specialDay.date; if ([specialDay isExceptional]) { // Indicate exceptional hours } } } } // Check if current opening hours contains a truncated time period NSArray <GMSPeriod *> * periods = currentOpeningHours.periods; if ([periods count] != 0) { for (GMSPeriod * period in periods) { GMSTimeOfWeek *open = period.open; GMSTimeOfWeek *close = period.close; if (open) { if ([open isTruncated]) { // Indicate truncated time period } } } } // Check if the place's secondary opening hours indicate when delivery is available GMSOpeningHours *secondaryOpeningHours = place.secondaryOpeningHours; GMSPlaceHoursType hoursType = secondaryOpeningHours.getHoursType; if (hoursType == GMSPlaceHoursTypeDelivery) { // Indicate hours where delivery is available } }
Obter local por ID
O ID de lugar é um indicador textual que identifica um local de forma exclusiva. No SDK do Places para iOS, é possível recuperar o ID de um lugar usando um objeto GMSPlace
. Você pode armazenar o ID de lugar e usá-lo para recuperar o objeto GMSPlace
novamente mais tarde.
Para acessar um local por ID, chame GMSPlacesClient
fetchPlaceFromPlaceID:
, transmitindo os seguintes parâmetros:
- String com um ID de lugar.
- Um ou mais
GMSPlaceField
s, especificando os tipos de dados a serem retornados. - Um token de sessão se a chamada for feita para concluir uma consulta de preenchimento automático. Caso contrário, passe nulo.
- Uma
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 fields: GMSPlaceField = GMSPlaceField(rawValue: UInt(GMSPlaceField.name.rawValue) | UInt(GMSPlaceField.placeID.rawValue))! placesClient?.fetchPlace(fromPlaceID: placeID, placeFields: fields, sessionToken: nil, callback: { (place: GMSPlace?, error: Error?) in if let error = error { print("An error occurred: \(error.localizedDescription)") return } if let place = place { self.lblName?.text = place.name print("The selected place is: \(place.name)") } })
Objective-C
// A hotel in Saigon with an attribution. NSString *placeID = @"ChIJV4k8_9UodTERU5KXbkYpSYs"; // Specify the place data types to return. GMSPlaceField fields = (GMSPlaceFieldName | GMSPlaceFieldPlaceID); [_placesClient fetchPlaceFromPlaceID:placeID placeFields:fields sessionToken:nil callback:^(GMSPlace * _Nullable place, NSError * _Nullable error) { if (error != nil) { NSLog(@"An error occurred %@", [error localizedDescription]); return; } if (place != nil) { NSLog(@"The selected place is: %@", [place name]); } }];
Exibir atribuições no seu aplicativo
Quando o app exibe informações recebidas de
GMSPlacesClient
lookUpPlaceID:callback:
, ele também precisa mostrar atribuições.
Consulte a documentação sobre atribuições.
Mais informações sobre IDs de local
O ID de lugar usado no SDK do Places para iOS é o mesmo identificador usado nas APIs Places, no SDK do Places para Android e em outras APIs do Google.
Cada ID de local só pode se referir a um local, mas um único local pode ter mais de um.
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 local, 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 daquele na sua solicitação.
Para mais informações, consulte a visão geral dos IDs de lugar.