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

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

Детали места

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

• Вызов GMSPlacesClient findPlaceLikelihoodsFromUserLocationWithPlaceFields: . См. руководство по получению текущего места .
• Вызовите GMSPlacesClient fetchPlaceFromPlaceID: , передав GMSPlaceField , идентификатор места и метод обратного вызова. Для запросов сведений о месте, если вы не укажете хотя бы одно поле в запросе или опустите параметр 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 имеет значение 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 с подробностями о месте.

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

    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 , определяющие типы возвращаемых данных.
• Токен сеанса, если выполняется вызов для завершения запроса автозаполнения. В противном случае передайте ноль.
• GMSPlaceResultCallback для обработки результата.

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

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

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

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

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

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