Описания мест

Places SDK для iOS предоставляет вашему приложению подробную информацию о местах, включая название и адрес места, географическое положение, указанное в виде координат широты и долготы, тип места (например, ночной клуб, зоомагазин, музей) и многое другое. Чтобы получить доступ к этой информации о конкретном месте, вы можете использовать идентификатор места — стабильный уникальный идентификатор.

Подробности места

Класс GMSPlace предоставляет информацию о конкретном месте. Вы можете получить объект GMSPlace следующими способами:

При запросе местоположения необходимо указать, какие типы данных о месте нужно вернуть. Для этого передайте поле GMSPlaceField с указанием типов возвращаемых данных. Это важный фактор, поскольку он влияет на стоимость каждого запроса.

Поскольку результаты поиска данных о месте не могут быть пустыми, возвращаются только результаты поиска мест с данными (например, если у запрошенного места нет фотографий, поле photos не будет присутствовать в результате).

В следующем примере передается список из двух значений полей для указания данных, возвращаемых запросом:

Быстрый 

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

Подробнее о полях мест . Подробнее о выставлении счетов за запросы данных мест см. в разделе «Использование и выставление счетов» .

Класс GMSPlace может содержать следующие данные о месте:

  • name – Название места.
  • editorialSummary – Содержит описание места.
  • placeID – текстовый идентификатор места. Подробнее об идентификаторах мест читайте далее на этой странице.
  • coordinate – географическое положение места, указанное в виде координат широты и долготы.
  • phoneNumber – номер телефона места в международном формате.
  • formattedAddress – человекочитаемый адрес этого местоположения.

    Часто этот адрес совпадает с почтовым адресом. Обратите внимание, что в некоторых странах, например, в Великобритании, распространение настоящих почтовых адресов запрещено из-за лицензионных ограничений.

    Форматированный адрес логически состоит из одного или нескольких компонентов адреса . Например, адрес «111 8th Avenue, New York, NY» состоит из следующих компонентов: «111» (номер дома), «8th Avenue» (маршрут), «New York» (город) и «NY» (штат США).

    Не анализируйте отформатированный адрес программно. Вместо этого используйте отдельные компоненты адреса, которые API-ответ включает в себя в дополнение к полю отформатированного адреса.

  • openingHours – часы работы места (представленные GMSOpeningHours ). Вызовите GMSOpeningHours.weekdayText , чтобы получить список локализованных строк с часами работы на этой неделе. Вызовите GMSOpeningHours.Periods , чтобы вернуть список GMSPeriod с более подробной информацией, эквивалентной данным, предоставляемым weekdayText . Примечание: если место всегда открыто, временной период представляется как воскресенье, полночь, а closeEvent равен null.
  • currentOpeningHours и secondaryOpeningHours — поля, в которых учитываются праздничные и временные изменения в расписании работы места.

  • addressComponents – массив объектов GMSAddressComponent , представляющих компоненты адреса места. Эти компоненты предназначены для извлечения структурированной информации об адресе места, например, для определения города, в котором оно находится. Не используйте эти компоненты для форматирования адреса; вместо этого используйте свойство formattedAddress , которое предоставляет локализованный форматированный адрес.

    Обратите внимание на следующие факты о массиве addressComponents :

    • Массив компонентов адреса может содержать больше компонентов, чем formattedAddress .
    • Массив не обязательно включает все политические образования, содержащие адрес, за исключением тех, которые включены в formattedAddress .
    • Формат ответа не гарантирует неизменности между запросами. В частности, количество addressComponents зависит от запрошенного адреса и может меняться со временем для одного и того же адреса. Компонент может менять положение в массиве. Тип компонента может меняться. В последующем ответе может отсутствовать определённый компонент.
  • userRatingsTotal – показывает, сколько отзывов составляют рейтинг места.

Класс GMSPlace содержит следующие функции-члены:

  • isOpen вычисляет, открыто ли место в указанное время, на основе openingHours и UTCOffsetMinutes , а также текущей даты и времени.
  • isOpenAtDate вычисляет, открыто ли место в указанную дату, на основе openingHours и UTCOffsetMinutes , а также текущей даты и времени.

    • При использовании этих функций для получения времени и/или дат открытия, исходный запрос fetchPlaceFromPlaceID: или findPlaceLikelihoodsFromUserLocationWithPlaceFields: должен содержать ОБА поля: GMSPlaceFieldOpeningHours и GMSPlaceFieldUTCOffsetMinutes . Если любое из этих полей отсутствует, результирующий объект GMSPlace не будет содержать времени и даты открытия, а вызов вернет GMSPlaceOpenStatusUnknown . Для получения точных результатов запросите поля GMSPlaceFieldBusinessStatus и GMSPlaceFieldUTCOffsetMinutes в исходном запросе места. Если поля не указаны, предполагается, что компания работает.

    Инструкции по использованию isOpen с данными о месте см. в видеоролике «Как узнать часы работы» .

Получите исключительные часы работы

В то время как обычные часы работы определяются через openingHours , currentOpeningHours и secondaryOpeningHours поддерживают праздничные и временные изменения в расписании. Исключительные часы работы для таких особых дней можно отфильтровать и отобразить, если они доступны.

Быстрый 

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

Получить место по ID

Идентификатор места — это текстовый идентификатор, однозначно определяющий место. В Places SDK для iOS идентификатор места можно получить из объекта GMSPlace . Вы можете сохранить идентификатор места и использовать его для последующего получения объекта GMSPlace .

Чтобы получить место по идентификатору, вызовите GMSPlacesClient fetchPlaceFromPlaceID: , передав следующие параметры:

  • Строка, содержащая идентификатор места.
  • Один или несколько полей GMSPlaceField , указывающих типы данных, которые необходимо вернуть.
  • Токен сеанса, если вызов выполняется для завершения запроса автодополнения. В противном случае передайте nil.
  • GMSPlaceResultCallback для обработки результата.

API вызывает указанный метод обратного вызова, передавая объект GMSPlace . Если место не найдено, объект места равен нулю.

Places Swift SDK для iOS 

// Initialize Places Swift Client.
let placesClient = PlacesClient.shared

// A hotel in Saigon with an attribution
let placeID = "ChIJV4k8_9UodTERU5KXbkYpSYs"
    
// Fetch Place Request.
let fetchPlaceRequest = FetchPlaceRequest(
  placeID: placeID,
  placeProperties: [.displayName]
)
    
Task {
  switch await placesClient.fetchPlace(with: fetchPlaceRequest) {
  case .success(let place):
    print("The selected place is: \(place.displayName): \(String(describing: place.description))")
  case .failure(let placesError):
    print("Place not found: \(placeID); \(placesError)")
  }
}

Быстрый 

// 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]);
  }
}];

Отображение атрибуции в вашем приложении

Когда ваше приложение отображает информацию, полученную от GMSPlacesClient lookUpPlaceID:callback: , оно также должно отображать данные об атрибуции. См. документацию по атрибуции .

Подробнее об идентификаторах мест

Идентификатор места, используемый в Places SDK для iOS, — это тот же идентификатор, который используется в Places API, Places SDK для Android и других API Google .

Каждый идентификатор места может относиться только к одному месту, но одно место может иметь более одного идентификатора места.

Существуют обстоятельства, при которых место может получить новый идентификатор. Например, это может произойти, если компания переезжает на новое место.

Запрашивая место, указывая его идентификатор, вы можете быть уверены, что в ответе всегда будет указано одно и то же место (если оно всё ещё существует). Однако обратите внимание, что в ответе может содержаться идентификатор места, отличный от указанного в вашем запросе.

Более подробную информацию см. в обзоре идентификаторов мест .