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

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

Об этом месте

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

• Позвонить GMSPlacesClient findPlaceLikelihoodsFromUserLocationWithPlaceFields:. Дополнительные сведения можно изучить в руководстве по получению информации о текущем месте.
• Вызовите метод GMSPlacesClient fetchPlaceFromPlaceID:, передав ему GMSPlaceField, идентификатор места и метод обратного вызова. Для запросов информации о местах, если вы не укажете хотя бы одно поле с запросом или если не включите параметр fields в запросе, возвращены будут все возможные поля, и за это будет начислена плата. Подробнее о том, как получить информацию о месте по его идентификатору…

Внимание! Если вы не укажете хотя бы одно поле с запросом или если не включите параметр fields в запросе, возвращены будут все возможные поля, и за это будет начислена плата. Это применяется только к запросам Place Details.

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

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

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

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

GMSPlaceFieldTakeout, GMSPlaceFieldDelivery, GMSPlaceFieldDineIn, GMSPlaceFieldCurbsidePickup, GMSPlaceFieldPhoneNumber, GMSPlaceFieldWebsite, GMSPlaceFieldOpeningHours и GMSPlaceFieldAddressComponents не поддерживаются для объектов мест GMSPlaceLikelihoodList.

Узнайте больше о полях с информацией о местах. Подробную информацию о том, как начисляется плата за запросы данных Places, можно найти в статье Статистика использования и оплата.

Класс 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 поддерживают изменения в праздничные дни и временные изменения. Если для этих дней задан измененный график, его можно отфильтровать и показать.

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

Получение информации о месте по его идентификатору

Идентификатор места – это уникальный текстовый идентификатор. В 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)")
  }
}

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

Указание авторства в приложении

Если в вашем приложении показывается информация, полученная с помощью вызова GMSPlacesClient lookUpPlaceID:callback:, в сведениях о месте также должно быть указано авторство. Подробнее об атрибуции…

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

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

Идентификатор может относиться только к одному месту, однако одному месту можно присвоить сразу несколько идентификаторов.

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

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

Подробную информацию можно найти в статье Общие сведения об идентификаторах мест.