Place Details (New)

Выберите платформу: Android iOS JavaScript Веб-сервисы
Разработчики из Европейской экономической зоны (ЕЭЗ)

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

Как получить сведения о месте

Класс GMSPlace содержит информацию об определенном месте, включая все поля данных, перечисленные в разделе Поля данных о месте (новая версия). Получите объект GMSPlace, вызвав метод GMSPlacesClient fetchPlaceWithRequest:, передав ему объект GMSFetchPlaceRequest и метод обратного вызова типа GMSPlaceResultCallback.

Объект GMSFetchPlaceRequest определяет:

  • (Обязательно.) Идентификатор места – уникальный идентификатор места в базе данных Google Places и на Google Картах.
  • (Обязательный параметр.) Список полей, которые должны возвращаться в объекте GMSPlace. Также называется маской полей и определяется параметром GMSPlaceProperty. Если вы не укажете хотя бы одно поле в списке полей или опустите список полей, вызов вернет ошибку.
  • Код региона, используемый для форматирования ответа (необязательно).
  • (Необязательно.) Токен сеанса, использованный для завершения сеанса Autocomplete (New).

Как создать запрос информации о местах

В этом примере место определяется по идентификатору с помощью следующих параметров:

  • Идентификатор места ChIJV4k8_9UodTERU5KXbkYpSYs.
  • Список полей, в котором указано, что нужно вернуть название места и URL сайта.
  • GMSPlaceResultCallback для обработки результата.

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

Places Swift SDK

// A hotel in Saigon with an attribution.
let placeID = "ChIJV4k8_9UodTERU5KXbkYpSYs"
let fetchPlaceRequest = FetchPlaceRequest(
  placeID: placeID,
  placeProperties: [.name, .website]
)
switch await placesClient.fetchPlace(with: fetchPlaceRequest) {
case .success(let place):
  // Handle place
case .failure(let placesError):
  // Handle error
}

Swift

// A hotel in Saigon with an attribution.
let placeID = "ChIJV4k8_9UodTERU5KXbkYpSYs"

// Specify the place data types to return.
let myProperties = [GMSPlaceProperty.name, GMSPlaceProperty.website].map {$0.rawValue}

// Create the GMSFetchPlaceRequest object.
let fetchPlaceRequest = GMSFetchPlaceRequest(placeID: placeID, placeProperties: myProperties, sessionToken: nil)

client.fetchPlace(with: fetchPlaceRequest, callback: {
  (place: GMSPlace?, error: Error?) in
  guard let place, error == nil else { return }
  print("Place found: \(String(describing: place.name))")
})

Objective-C

// A hotel in Saigon with an attribution.
NSString *placeID = @"ChIJV4k8_9UodTERU5KXbkYpSYs";

// Specify the place data types to return.
NSArray<NSString *> *myProperties = @[GMSPlacePropertyName, GMSPlacePropertyWebsite];

// Create the GMSFetchPlaceRequest object.
GMSFetchPlaceRequest *fetchPlaceRequest = [[GMSFetchPlaceRequest alloc] initWithPlaceID:placeID placeProperties: myProperties sessionToken:nil];

[placesClient fetchPlaceWithRequest: fetchPlaceRequest callback: ^(GMSPlace *_Nullable place, NSError *_Nullable error) {
    if (error != nil) {
      NSLog(@"An error occurred %@", [error localizedDescription]);
      return;
    } else {
    NSLog(@"Place Found: %@", place.name);
    NSLog(@"The place URL: %@", place.website);
  }
}];

Ответ на запрос информации о местах

В ответе на запрос Place Details возвращается объект GMSPlace, содержащий информацию о месте. В объекте GMSPlace будут заполнены только поля, указанные в списке полей.

Как узнать статус открытия

Объект GMSPlacesClient содержит функцию-член isOpenWithRequest (isOpenRequest в Swift и isPlaceOpenRequest в GooglePlacesSwift), которая возвращает ответ, указывающий, открыто ли место в настоящее время, на основе времени, указанного в вызове.

Этот метод принимает один аргумент типа GMSPlaceIsOpenWithRequest, который содержит:

  • Объект GMSPlace или строка, содержащая идентификатор места. Подробнее о том, как создать объект Place с необходимыми полями…
  • Необязательный объект NSDate (Obj-C) или Date (Swift), указывающий время, которое вы хотите проверить. Если время не указано, по умолчанию используется текущее время.
  • Метод GMSPlaceOpenStatusResponseCallback для обработки ответа.
    • >

Для метода GMSPlaceIsOpenWithRequest в объекте GMSPlace необходимо задать следующие поля:

  • GMSPlacePropertyUTCOffsetMinutes
  • GMSPlacePropertyBusinessStatus
  • GMSPlacePropertyOpeningHours
  • GMSPlacePropertyCurrentOpeningHours
  • GMSPlacePropertySecondaryOpeningHours

Если эти поля не указаны в объекте Place или вы передаете идентификатор места, метод использует GMSPlacesClient GMSFetchPlaceRequest: для их получения.

Ответ isOpenWithRequest

isOpenWithRequest возвращает объект GMSPlaceIsOpenResponse, содержащий логическое значение status, которое указывает, открыта ли компания, закрыта или ее статус неизвестен.

Язык Значение, если открыто Значение, если закрыто Значение, если статус неизвестен
Places Swift true false nil
Swift .open .closed .unknown
Objective-C GMSPlaceOpenStatusOpen GMSPlaceOpenStatusClosed GMSPlaceOpenStatusUnknown

Оплата за isOpenWithRequest

  • Поля GMSPlacePropertyUTCOffsetMinutes и GMSPlacePropertyBusinessStatus оплачиваются по коду Basic Data. Остальные часы работы оплачиваются по коду SKU Enterprise для информации о местах.
  • Если в объекте GMSPlace уже есть эти поля из предыдущего запроса, плата за них взиматься не будет.

Пример запроса GMSPlaceIsOpenWithRequest

В примере ниже показано, как инициализировать GMSPlaceIsOpenWithRequest в существующем объекте GMSPlace.

Places Swift SDK

        let isOpenRequest = IsPlaceOpenRequest(place: place)
        switch await placesClient.isPlaceOpen(with: isOpenRequest) {
          case .success(let isOpenResponse):
            switch isOpenResponse.status {
              case true:
                // Handle open
              case false:
                // Handle closed
              case nil:
                // Handle unknown
          case .failure(let placesError):
            // Handle error
        }

Swift

    let isOpenRequest = GMSPlaceIsOpenRequest(place: place, date: nil)
      GMSPlacesClient.shared().isOpen(with: isOpenRequest) { response, error in
        if let error = error {
          // Handle Error
        }
        switch response.status {
          case .open:
            // Handle open
          case .closed:
            // Handle closed
          case .unknown:
            // Handle unknown
        }
      }

Objective-C

          GMSPlaceIsOpenRequest *isOpenRequest = [[GMSPlaceIsOpenRequest alloc] initWithPlace:place date:nil];

          [[GMSPlacesClient sharedClient] isOpenWithRequest:isOpenRequest callback:^(GMSPlaceIsOpenResponse response, NSError *_Nullable error) {
            if (error) {
              // Handle error
            }

            switch (response.status) {
              case GMSPlaceOpenStatusOpen:
                // Handle open
              case GMSPlaceOpenStatusClosed:
                // Handle closed
              case GMSPlaceOpenStatusUnknown:
                // Handle unknown
            }
          }];

Обязательные параметры

Чтобы указать нужные параметры, используйте объект GMSFetchPlaceRequest.

Идентификатор места

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

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

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

Список полей

При запросе информации о месте необходимо указать данные, которые нужно вернуть в объекте GMSPlace, в виде маски поля. Чтобы определить маску поля, передайте массив значений из GMSPlaceProperty в объект GMSFetchPlaceRequest. Маски полей помогут вам не запрашивать ненужные данные и тем самым сократить время обработки и снизить расходы.

Укажите одно или несколько из следующих полей:

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

Places Swift SDK

// Specify the place data types to return.
let fields: [PlaceProperty] = [.placeID, .displayName]

Swift

// Specify the place data types to return.
let fields: [GMSPlaceProperty] = [.placeID, .name]

Objective-C

// Specify the place data types to return.
NSArray<GMSPlaceProperty *> *fields = @[GMSPlacePropertyPlaceID, GMSPlacePropertyName];

Необязательные параметры

Чтобы указать необязательные параметры, используйте объект GMSFetchPlaceRequest.

regionCode

Код региона, используемый для форматирования ответа, в виде двухсимвольного кода CLDR. Этот параметр также может влиять на результаты поиска. Значение по умолчанию не задано.

Если название страны в поле адреса в ответе совпадает с кодом региона, код страны не включается в адрес.

Большинство кодов CLDR совпадают с кодами ISO 3166-1, однако имеются некоторые исключения. Например, ccTLD Великобритании – uk (.co.uk), а код ISO 3166-1 – gb (технически для "Соединенного Королевства Великобритании и Северной Ирландии"). Параметр может влиять на результаты в соответствии с действующим законодательством.

sessionToken

Токены сеансов – это создаваемые пользователем строки, которые отслеживают вызовы Autocomplete (New) как "сеансы". Autocomplete (New) использует токены сеансов, чтобы сгруппировать этапы запроса и выбора места выполняемого пользователем поиска с функцией автозаполнения в отдельный сеанс для выставления счетов. Токены сеанса передаются в вызовы информации о местах (New), которые следуют за вызовами Autocomplete (New). Подробнее о токенах сеансов…

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

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

Например, свойство reviews объекта GMSPlacesClient содержит массив, в котором может быть до пяти объектов GMSPlaceReview. Каждый объект GMSPlaceReview может содержать атрибуцию и атрибуцию автора. Если вы показываете отзыв в приложении, то должны также указать авторство или источник отзыва.

Подробнее о том, как добавлять текст с указанием авторства…