Place Details

O SDK Places para iOS 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.

Detalhes do lugar

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

• Chame GMSPlacesClient findPlaceLikelihoodsFromUserLocationWithPlaceFields:. Consulte o guia sobre como acessar o lugar atual.
• Chame GMSPlacesClient fetchPlaceFromPlaceID:, transmitindo um GMSPlaceField, 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âmetro fields de uma solicitação, TODOS os campos possíveis vão ser retornados, e uma cobrança será feita. Consulte o guia para acessar um lugar por ID.

Ao solicitar um lugar, você precisa especificar quais tipos de dados do lugar serão retornados. Para fazer isso, transmita um GMSPlaceField, especificando os tipos de dados a serem retornados. Essa é uma consideração importante, já que isso vai afetar o custo de cada solicitação.

Como os resultados de dados de lugar não podem ficar vazios, apenas os resultados de lugar com dados são retornados. Por exemplo, se um lugar solicitado não tiver fotos, o campo photos não vai 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:

      // 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))
  

      // 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.
• editorialSummary: fornece uma descrição de um lugar.
• placeID: o identificador textual do lugar. Leia mais sobre os 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 local no formato internacional.
• formattedAddress: o endereço legível por humanos desse lugar.

  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: os horários de funcionamento do lugar (conforme representado por GMSOpeningHours). Chame GMSOpeningHours.weekdayText para conferir 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 equivalentes aos dados fornecidos por weekdayText. Observação:se um lugar estiver sempre aberto, o período será representado como domingo à meia-noite, e o closeEvent será nulo.
• currentOpeningHours e secondaryOpeningHours: campos que consideram 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 para 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 endereços. Use a propriedade formattedAddress, que fornece um endereço formatado localizado.

  Observe os seguintes fatos sobre a matriz addressComponents:

  • A matriz de componentes do endereço pode conter mais componentes do que o 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, e na data e hora atuais.
• isOpenAtDate calcula se um lugar está aberto em uma determinada data com base em openingHours e UTCOffsetMinutes, e na data e hora atuais.

Ao usar essas funções para receber horários de abertura e/ou datas, 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 ou datas de abertura, e a chamada vai 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á operacional.

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

Conferir horários excepcionais

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

- (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 extrair o ID de um lugar de um objeto GMSPlace. Armazene o ID de lugar e use-o para recuperar o objeto GMSPlace novamente mais tarde.

Para receber um lugar por ID, chame GMSPlacesClient fetchPlaceFromPlaceID:, transmitindo os seguintes parâmetros:

• Uma string que contém 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, transmita 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.

// 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)")
  }
})

// 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 mostra informações obtidas de GMSPlacesClient lookUpPlaceID:callback:, ele também precisa mostrar as atribuições. Consulte a documentação sobre atribuições.

Mais informações sobre IDs de local

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 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 solicitação.

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