Поиск поблизости (новая версия)

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

В запросе поиск поблизости (New) в качестве входных данных используется регион поиска, заданный в виде круга, определяемого координатами широты и долготы центральной точки круга и радиусом в метрах. Запрос возвращает список мест, соответствующих критериям поиска, в пределах указанной области. Каждое место представлено объектом GMSPlace.

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

запросы поиска поблизости (новая версия);

Чтобы сделать запрос поиска поблизости, вызовите метод GMSPlacesClient searchNearbyWithRequest:, передав объект GMSPlaceSearchNearbyRequest, который определяет параметры запроса, и метод обратного вызова типа GMSPlaceSearchNearbyResultCallback для обработки ответа.

Объект GMSPlaceSearchNearbyRequest содержит все обязательные и необязательные параметры запроса. Обязательные параметры:

  • Список полей, которые нужно вернуть в объекте GMSPlace (также называется маской поля), как определено в GMSPlaceProperty. Если вы не укажете хотя бы одно поле в списке полей или если опустите список полей, вызов вернет ошибку.
  • Ограничение местоположения, то есть круг, определяющий область поиска.

В этом примере запроса поиска поблизости указано, что объекты GMSPlace в ответе должны содержать название места (GMSPlacePropertyName) и координаты места (GMSPlacePropertyCoordinate) для каждого объекта GMSPlace в результатах поиска. Кроме того, он фильтрует ответ, чтобы возвращать только места типа "ресторан" и "кафе".

Places Swift SDK

let restriction = CircularCoordinateRegion(center: CLLocationCoordinate2DMake(37.7937, -122.3965), radius: 500)
let searchNearbyRequest = SearchNearbyRequest(
  locationRestriction: restriction,
  placeProperties: [ .name, .coordinate],
  includedTypes: [ .restaurant, .cafe ],
)
switch await placesClient.searchNearby(with: searchNearbyRequest) {
case .success(let places):
  // Handle places
case .failure(let placesError):
  // Handle error
}

Swift

// Array to hold the places in the response
var placeResults: [GMSPlace] = []

// Define the search area as a 500 meter diameter circle in San Francisco, CA.
let circularLocationRestriction = GMSPlaceCircularLocationOption(CLLocationCoordinate2DMake(37.7937, -122.3965), 500)

// Specify the fields to return in the GMSPlace object for each place in the response.
let placeProperties = [GMSPlaceProperty.name, GMSPlaceProperty.coordinate].map {$0.rawValue}

// Create the GMSPlaceSearchNearbyRequest, specifying the search area and GMSPlace fields to return.
var request = GMSPlaceSearchNearbyRequest(locationRestriction: circularLocationRestriction, placeProperties: placeProperties)
let includedTypes = ["restaurant", "cafe"]
request.includedTypes = includedTypes

let callback: GMSPlaceSearchNearbyResultCallback = { [weak self] results, error in
  guard let self, error == nil else {
    if let error {
      print(error.localizedDescription)
    }
    return
  }
  guard let results = results as? [GMSPlace] else {
    return
  }
  placeResults = results
}

GMSPlacesClient.shared().searchNearby(with: request, callback: callback)

Objective-C

// Array to hold the places in the response
_placeResults = [NSArray array];

// Define the search area as a 500 meter diameter circle in San Francisco, CA.
id<GMSPlaceLocationRestriction> circularLocation = GMSPlaceCircularLocationOption(CLLocationCoordinate2DMake(37.7937, -122.3965), 500);

// Create the GMSPlaceSearchNearbyRequest, specifying the search area and GMSPlace fields to return.
GMSPlaceSearchNearbyRequest *request = [[GMSPlaceSearchNearbyRequest alloc]
  initWithLocationRestriction:circularLocation
              placeProperties:@[ GMSPlacePropertyName, GMSPlacePropertyCoordinate ]];

// Set the place types to filter on.
NSArray<NSString *> *includedTypes = @[ @"restaurant", @"cafe" ];
request.includedTypes = [[NSMutableArray alloc] initWithArray:includedTypes];

[_placesClient searchNearbyWithRequest:request
  callback:^(NSArray<GMSPlace *> *_Nullable places, NSError *_Nullable error) {
    if (error != nil) {
      NSLog(@"An error occurred %@", [error localizedDescription]);
      return;
    } else {
        // Get list of places.
        _placeResults = places;
    }
  }
];

Ответы на запросы поиска поблизости

Nearby Search API возвращает массив совпадений в виде объектов 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
            }
          }];

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

Используйте объект GMSPlaceSearchNearbyRequest, чтобы указать необходимые параметры поиска.

  • Список полей

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

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

    • Следующие поля активируют код SKU для поиска поблизости Pro:

      GMSPlacePropertyAddressComponents
      GMSPlacePropertyBusinessStatus
      GMSPlacePropertyCoordinate
      GMSPlacePropertyFormattedAddress
      GMSPlacePropertyName
      GMSPlacePropertyIconBackgroundColor
      GMSPlacePropertyIconImageURL
      GMSPlacePropertyPhotos
      GMSPlacePropertyPlaceID
      GMSPlacePropertyPlusCode
      GMSPlacePropertyTypes
      GMSPlacePropertyUTCOffsetMinutes
      GMSPlacePropertyViewport
      GMSPlacePropertyWheelchairAccessibleEntrance

      Полный список полей и связанных с ними кодов приведен в разделе Поля данных о местах (новая версия).

    • Следующие поля активируют код SKU поиска поблизости Enterprise:

      GMSPlacePropertyCurrentOpeningHours
      GMSPlacePropertySecondaryOpeningHours
      GMSPlacePropertyPhoneNumber
      GMSPlacePropertyPriceLevel
      GMSPlacePropertyRating
      GMSPlacePropertyOpeningHours
      GMSPlacePropertyUserRatingsTotal
      GMSPlacePropertyWebsite

      Полный список полей и связанных с ними кодов приведен в разделе Поля данных о местах (новая версия).

    • Следующие поля активируют код SKU "Поиск поблизости" Enterprise Plus:

      GMSPlacePropertyCurbsidePickup
      GMSPlacePropertyDelivery
      GMSPlacePropertyDineIn
      GMSPlacePropertyEditorialSummary
      GMSPlacePropertyReservable
      GMSPlacePropertyReviews
      GMSPlacePropertyServesBeer
      GMSPlacePropertyServesBreakfast
      GMSPlacePropertyServesBrunch
      GMSPlacePropertyServesDinner
      GMSPlacePropertyServesLunch
      GMSPlacePropertyServesVegetarianFood
      GMSPlacePropertyServesWine
      GMSPlacePropertyTakeout

      Полный список полей и связанных с ними кодов приведен в разделе Поля данных о местах (новая версия).

    В примере ниже передается список из двух значений полей, чтобы указать, что объект 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];

  • locationRestriction

    Объект GMSPlaceLocationRestriction, определяющий область поиска в виде круга с центром и радиусом в метрах. Радиус должен быть в диапазоне от 0,0 до 50 000,0 включительно. Радиус по умолчанию – 0.0. В запросе необходимо указать значение больше 0.0.

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

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

  • includedTypes/excludedTypes, includedPrimaryTypes/excludedPrimaryTypes

    Позволяет указать список типов из таблицы А, которые будут использоваться для фильтрации результатов поиска. В каждой категории с ограничениями можно указать до 50 типов.

    У места может быть только один основной тип из таблицы А. Например, основным типом может быть "mexican_restaurant" или "steak_house". Используйте типы includedPrimaryTypes и excludedPrimaryTypes, чтобы фильтровать результаты по основному типу места.

    С местом также может быть связано несколько значений типа из таблицы А. Например, для ресторана могут быть указаны следующие типы: "seafood_restaurant", "restaurant", "food", "point_of_interest", "establishment". Используйте includedTypes и excludedTypes, чтобы отфильтровать результаты в списке типов, связанных с местом.

    Если вы укажете общий основной тип, например "restaurant" или "hotel", в ответе могут быть места с более конкретным основным типом, чем указанный. Например, вы можете указать, что нужно включить основной тип "restaurant". В ответе могут быть места с основным типом "restaurant", а также места с более конкретным основным типом, например "chinese_restaurant" или "seafood_restaurant".

    Если в поиске указано несколько ограничений по типу, возвращаются только места, соответствующие всем ограничениям. Например, если вы укажете {"includedTypes": ["restaurant"], "excludedPrimaryTypes": ["steak_house"]}, то в результатах поиска будут места, которые предоставляют услуги, связанные с "restaurant", но не являются "steak_house".

    includedTypes

    Список типов мест из таблицы А, которые нужно найти. Если этот параметр не указан, возвращаются места всех типов.

    excludedTypes

    Список типов мест из таблицы А, которые нужно исключить из поиска.

    Если в запросе указать и includedTypes (например, "school"), и excludedTypes (например, "primary_school"), то в ответе будут места, которые относятся к категории "school", но не к категории "primary_school". В ответе будут места, которые соответствуют хотя бы одному из объектов includedTypes и ни одному из объектов excludedTypes.

    Если есть конфликтующие типы, например тип, который появляется и в includedTypes, и в excludedTypes, возвращается ошибка INVALID_REQUEST.

    includedPrimaryTypes

    Список основных типов мест из таблицы А, которые нужно включить в поиск.

    excludedPrimaryTypes

    Список основных типов мест из таблицы А, которые нужно исключить из поиска.

    Если основные типы конфликтуют, например если тип указан и в includedPrimaryTypes, и в excludedPrimaryTypes, возвращается ошибка INVALID_ARGUMENT.

  • maxResultCount

    Указывает максимальное количество результатов поиска мест, которые нужно вернуть. Значение должно быть в диапазоне от 1 до 20 (по умолчанию) включительно.

  • rankPreference

    Тип ранжирования. Если этот параметр не указан, результаты сортируются по популярности. Может быть одним из следующих:

    • .popularity (по умолчанию). Результаты сортируются по популярности.
    • .distance. Результаты сортируются по возрастанию расстояния от указанного местоположения.

  • regionCode

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

    Если название страны в поле formattedAddress ответа совпадает с regionCode, код страны удаляется из formattedAddress. Этот параметр не влияет на adrFormatAddress, который всегда включает название страны, и на shortFormattedAddress, который никогда его не включает.

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

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

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

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

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