Place Details

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

O SDK do Places para iOS oferece ao app informações detalhadas sobre locais, incluindo nome e endereço, 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 de um local específico, você pode usar o ID de lugar, um identificador estável que identifica exclusivamente um local.

Detalhes do lugar

A classe GMSPlace fornece informações sobre um lugar específico. É possível conseguir 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, porque isso afetará o custo de cada solicitação.

Como os resultados de dados de lugar não podem estar vazios, apenas resultados de lugar com dados são retornados. Por exemplo, se um local 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.
  • editorialSummary: fornece uma descrição simples de um 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, em 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 (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 que sejam 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 têm alterações temporárias e 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 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 que o formattedAddress.
    • A matriz não inclui necessariamente todas as entidades políticas que contêm um endereço, exceto aquelas incluídas no formattedAddress.
    • Não há garantia de que o formato da resposta permanecerá o mesmo entre as solicitações. 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 ausente 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 determinado 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 conseguir horários e/ou datas de abertura, a solicitação original fetchPlaceFromPlaceID: ou findPlaceLikelihoodsFromUserLocationWithPlaceFields: precisa especificar 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 sua 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 o isOpen com o Place Details.

Receba horários excepcionais

Embora o horário de funcionamento normal seja informado por meio da openingHours, a currentOpeningHours e a secondaryOpeningHours são compatíveis com mudanças temporárias e programadas. Horários 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 ver um local por ID, chame GMSPlacesClient fetchPlaceFromPlaceID:, transmitindo os seguintes parâmetros:

  • Uma string contendo um ID de local.
  • 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 nil.
  • Um GMSPlaceResultCallback para gerenciar 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 seu app exibe informações fornecidas por GMSPlacesClient lookUpPlaceID:callback:, ele também precisa exibir 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 local pode referir-se 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 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 lugar na resposta (se o lugar ainda existir). No entanto, a resposta pode conter um ID de local diferente daquele na sua solicitação.

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