Place Details

Selecione a plataforma: Android iOS JavaScript Serviço da Web

O SDK do Places para iOS oferece ao seu app informações detalhadas sobre lugares, incluindo nome e endereço do lugar, localização geográfica especificada como coordenadas de latitude/longitude, tipo de lugar (como casa noturna, 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 local de forma exclusiva.

Detalhes do lugar

A classe GMSPlace fornece informações sobre um lugar específico. É possível receber um objeto GMSPlace das seguintes maneiras:

Ao solicitar um lugar, você precisa 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 isso afetará o custo de cada solicitação.

Como os resultados de dados de lugar não podem estar vazios, apenas resultados 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 lugar.
  • placeID: o identificador textual do lugar. Leia mais sobre IDs de lugar no restante desta página.
  • coordinate: a localização geográfica do lugar, especificada como coordenadas de latitude e longitude.
  • phoneNumber: o número de telefone do lugar, no formato internacional.
  • formattedAddress: o endereço legível deste 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 (conforme representado por GMSOpeningHours). Chame GMSOpeningHours.weekdayText para ver uma lista de strings localizadas do horário de funcionamento diário da semana. Chame GMSOpeningHours.Periods para retornar uma lista de GMSPeriods com informações mais detalhadas equivalentes aos dados fornecidos por weekdayText. Observação: se um lugar estiver sempre aberto, o período será representado como domingo à meia-noite, e closeEvent será nulo.

  • addressComponents: uma matriz de objetos GMSAddressComponent que representam os componentes do endereço de um lugar. Esses componentes são usados com a finalidade de extrair informações estruturadas sobre o endereço de um lugar, 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 propriedade formattedAddress, 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 o formattedAddress.
    • A matriz não inclui necessariamente todas as entidades políticas que contenham um endereço, exceto as incluídas no formattedAddress.
    • Não há garantia de que o formato da resposta permanecerá o mesmo entre as solicitações. Especificamente, o número de addressComponents varia de acordo com o endereço solicitado e pode mudar com o tempo para o mesmo endereço. Um componente pode mudar a posição na matriz. O tipo do componente pode mudar. Um componente específico pode estar faltando em uma resposta posterior.
  • 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 em openingHours e UTCOffsetMinutes, além da data e hora atuais.
  • isOpenAtDate calcula se um lugar está aberto em uma determinada data com base em openingHours e UTCOffsetMinutes, além da data e hora atuais.

    • Ao usar essas funções para ver os horários e/ou datas de abertura, a solicitação original fetchPlaceFromPlaceID: ou findPlaceLikelihoodsFromUserLocationWithPlaceFields: precisa especificar AMBOS os campos GMSPlaceFieldOpeningHours e GMSPlaceFieldUTCOffsetMinutes. Se um desses campos estiver ausente, o objeto GMSPlace resultante não conterá horários ou datas de abertura e a chamada retornará GMSPlaceOpenStatusUnknown. Para garantir resultados precisos, solicite os campos GMSPlaceFieldBusinessStatus e GMSPlaceFieldUTCOffsetMinutes na solicitação de lugar original. Se não for solicitado, presume-se que a empresa está funcionando.

    Veja este vídeo para saber como usar isOpen com o Place Details.

Obter local por ID

O ID de lugar é um indicador textual que identifica um local de forma exclusiva. No SDK do Places para iOS, você pode 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 encontrar um lugar por ID, chame GMSPlacesClient fetchPlaceFromPlaceID:, transmitindo os seguintes parâmetros:

  • Uma string que contém um ID de lugar.
  • Uma ou mais GMSPlaceFields, 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.
  • 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 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 coletadas 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 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 local, mas um único local pode ter mais de um ID de local.

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

Ao solicitar um lugar 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 local diferente daquele da sua solicitação.

Para mais informações, consulte a visão geral do ID do lugar.