Place Details

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

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:

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 por GMSOpeningHours). Chame GMSOpeningHours.weekdayText para ver uma lista de strings localizadas dos horários de funcionamento diários da semana. Chame GMSOpeningHours.Periods para retornar uma lista de GMSPeriods com informações mais detalhadas que são equivalentes aos dados fornecidos por weekdayText. Observação:quando um lugar está sempre aberto, o período é representado como domingo à meia-noite, e closeEvent é nulo.
  • currentOpeningHours e secondaryOpeningHours: campos que incluem feriados e mudanças temporárias na programação de um lugar.
  • addressComponents: uma matriz de objetos GMSAddressComponent 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 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 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.
  • 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 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.

    Assista a este vídeo para saber como usar 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 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.
  • 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.