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

Оптимизируйте свои подборки Сохраняйте и классифицируйте контент в соответствии со своими настройками.

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

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

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

• Вызовите GMSPlacesClient findPlaceLikelihoodsFromUserLocationWithPlaceFields: . См. руководство по получению текущего места .
• Вызовите GMSPlacesClient fetchPlaceFromPlaceID: , передав GMSPlaceField , идентификатор места и метод обратного вызова. Для запросов Place Details, если вы не указали хотя бы одно поле в запросе или если вы пропустили параметр fields из запроса, будут возвращены ВСЕ возможные поля, и вам будет выставлен соответствующий счет. См. руководство по получению места по идентификатору .

При запросе места необходимо указать, какие типы данных о месте следует вернуть. Для этого передайте 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))
  

      // 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 равен нулю.
• 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 с данными о месте.

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

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

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

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

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

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

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

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

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

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

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

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

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