Новая версия текстового поиска

Выберите платформу: Android iOS JavaScript Веб-сервисы

Разработчики из Европейской экономической зоны (ЕЭЗ)

Новая версия текстового поиска возвращает информацию о местах на основе введенной фразы, например "кафе в Москве", "обувные магазины в Санкт-Петербурге" или "улица Центральная, 123". Ответ этого сервиса содержит список мест, соответствующих текстовой строке с учетом указанного предпочтительного местоположения.

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

Как получить список мест с помощью текстового поиска

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

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

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

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

Places Swift SDK

let restriction = GMSPlaceRectangularLocationOption(
      northEast: CLLocationCoordinate2D(latitude: 20, longitude: 30),
      southWest: CLLocationCoordinate2D(latitude: 40, longitude: 50)
)
let searchByTextRequest = SearchByTextRequest(
        textQuery: "pizza in New York",
        placeProperties: [ .name, .placeID ],
        locationRestriction: restriction,
        includedType: .restaurant,
        maxResultCount: 5,
        minRating: 3.5,
        priceLevels: [ .moderate, .inexpensive ],
        isStrictTypeFiltering: true
)
switch await placesClient.searchByText(with: searchByTextRequest) {
case .success(let places):
  // Handle places
case .failure(let placesError):
  // Handle error
}

Swift

// Create the GMSPlaceSearchByTextRequest object.
let myProperties = [GMSPlaceProperty.name, GMSPlaceProperty.placeID].map {$0.rawValue}
let request = GMSPlaceSearchByTextRequest(textQuery:"pizza in New York", placeProperties:myProperties)
request.isOpenNow = true
request.includedType = "restaurant"
request.maxResultCount = 5
request.minRating = 3.5
request.rankPreference = .distance
request.isStrictTypeFiltering = true
request.locationBias =  GMSPlaceCircularLocationOption(CLLocationCoordinate2DMake(40.7, -74.0), 200.0)

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

let callback: GMSPlaceSearchByTextResultCallback = { [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().searchByText(with: request, callback: callback)

Objective-C

// Create the GMSPlaceSearchByTextRequest object.
GMSPlaceSearchByTextRequest *request =
    [[GMSPlaceSearchByTextRequest alloc] initWithTextQuery:@"pizza in New York" placeProperties:@[GMSPlacePropertyName, GMSPlacePropertyPlaceID]];
request.isOpenNow = YES;
request.includedType = @"restaurant";
request.maxResultCount = 5;
request.minRating = 3.5;
request.rankPreference = GMSPlaceSearchByTextRankPreferenceDistance;
request.isStrictTypeFiltering = YES;
request.priceLevels = @[ @(kGMSPlacesPriceLevelFree), @(kGMSPlacesPriceLevelCheap) ];
request.locationBias = GMSPlaceCircularLocationOption(CLLocationCoordinate2DMake(40.7, -74.0), 200.0);

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

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

Ответы текстового поиска

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

Разбивка на страницы

Текстовый поиск предоставляет объект разбиения на страницы – логическое значение hasNextPage, которое возвращается в первом ответе на вызов текстового поиска. Если следующая страница доступна, вы можете загрузить ее с помощью функции fetchNextPage().

В примере ниже показано, как проверить, доступна ли следующая страница, и загрузить ее.

Swift

public struct PlaceSearchPagination {
  public var pageSize: Int
  public var hasNextPage: Bool
  public func fetchNextPage() async -> SearchByTextResponse
}

public struct SearchByTextResponse {
  public var pagination: PlaceSearchPagination?
  public var places: [Place]?
  public var error: PlaceError?
}

PlacesClient.swift
public func searchByText(with request: SearchByTextRequest) async -> SearchByTextResponse

let searchByTextRequest = SearchByTextRequest(textQuery: "restaurants",
    placeProperties: [PlaceProperty.displayName],
    locationBias: CircularCoordinateRegion(center: CLLocationCoordinate2D(latitude: 0, longitude: 0), radius: 100))

searchByTextRequest.maxResultCount = 10

var searchByTextResponse = await PlacesClient.shared.searchByText(with: searchByTextRequest)
print("Found \(searchByTextResponse.places.count) places")

searchByTextResponse.pagination.pageSize = 20

// Continue making requests until no more results are found in pagination object
while searchByTextResponse.pagination.hasNextPage {
    searchByTextResponse = await searchByTextResponse.pagination.fetchNextPage()
    print("Found \(searchByTextResponse.places.count) places")
}

Objective-C

GMSPlaceSearchByTextRequest *searchByTextRequest = [[GMSPlaceSearchByTextRequest alloc]
    initWithTextQuery: @"restaurants"
    placeProperties: @[GMSPlacePropertyAll]];

searchByTextRequest.maxResultCount = 10;

__block void (^recursiveCallback)(GMSPlaceSearchByTextResponse *, NSError *);
recursiveCallback = ^(GMSPlaceSearchByTextResponse * response, NSError* error) {
    NSLog(@"Found %d places", response.places.count);
    if (response.pagination.hasNextPage) {
      [response.pagination fetchNextPageWithCompletion:recursiveCallback];
   }
};
[GMSPlacesClient.sharedClient searchByTextWithRequest:searchByTextRequest  
                                           completion:recursiveCallback];

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

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

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

    Укажите, какие свойства данных о месте нужно вернуть. Передайте список свойств GMSPlace, указывающих, какие поля данных нужно вернуть. Если вы не укажете маску поля, запрос вернет ошибку.

    Списки полей помогут вам не запрашивать ненужные данные и тем самым сократить время обработки и снизить расходы.

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

    • Следующие поля активируют Text Search Essentials ID Only SKU:

      GMSPlacePropertyPlaceID

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

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

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

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

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

      GMSPlacePropertyCurrentOpeningHours
      GMSPlacePropertySecondaryOpeningHours
      GMSPlacePropertyPhoneNumber
      GMSPlacePropertyPriceLevel
      GMSPlacePropertyRating
      GMSPlacePropertyOpeningHours
      GMSPlacePropertyUserRatingsTotal
      GMSPlacePropertyWebsite

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

    • Код Text Search Enterprise Plus применяется, если вы запрашиваете следующие поля:

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

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

  • textQuery

    Строка для текстового поиска, например "ресторан", "улица Центральная, 123" или "лучшие места в Сан-Франциско".

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

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

  • includedType

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

    • let request = SearchByTextRequest()
      request.includedType = "bar"
    • let request = SearchByTextRequest()
      request.includedType = "pharmacy"

  • isOpenNow

    Если задано значение true, возвращаются только те места, которые открыты в момент отправки запроса. Если false, возвращаются все компании независимо от статуса. Если в запросе указан этот параметр, то все места, для которых в базе данных Google Places не указаны часы работы, игнорируются.false

  • isStrictTypeFiltering

    Используется с параметром includeType. Если задано значение true, возвращаются только места, соответствующие типам, указанным в параметре includeType. Если задано значение false (по умолчанию), ответ может содержать места, не соответствующие указанным типам.

  • locationBias

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

    Вы можете указать locationRestriction или locationBias, но не оба значения. Параметр locationRestriction указывает регион, в котором должны находиться результаты, а параметр locationBias – регион, рядом с которым должны находиться результаты (но они могут быть и за его пределами).

    Укажите регион в виде прямоугольной области просмотра или круга.

    • Круг определяется центральной точкой и радиусом в метрах. Радиус должен быть в диапазоне от 0,0 до 50 000,0 включительно. Радиус по умолчанию – 0,0. Пример:

      let request = SearchByTextRequest()
request.locationBias =  GMSPlaceCircularLocationOption(CLLocationCoordinate2DMake(40.7, -74.0), 200.0)

    • Прямоугольник – это область просмотра, заданная координатами широты и долготы и представленная двумя диагонально противоположными точками (нижней и верхней). Нижняя точка обозначает юго-западный угол прямоугольника, а верхняя – северо-восточный.

      Область просмотра считается замкнутым регионом, то есть включает в себя свои границы. Широта должна находиться в диапазоне от -90 до 90 градусов включительно, а долгота – от -180 до 180 градусов включительно.

      • Если low = high, область просмотра состоит из одной точки.
      • Если low.longitude > high.longitude, диапазон долготы инвертируется (область просмотра пересекает линию долготы 180 градусов).
      • Если low.longitude = -180 градусов, а high.longitude = 180 градусов, область просмотра включает все долготы.
      • Если low.longitude = 180 градусов, а high.longitude = -180 градусов, то диапазон долготы пуст.
      • Если low.latitude > high.latitude, диапазон широт пуст.

  • locationRestriction

    Определяет область поиска. Результаты за пределами указанной области не возвращаются. Укажите регион в виде прямоугольной области просмотра. Информацию о том, как задать область просмотра, можно найти в описании locationBias.

    Вы можете указать locationRestriction или locationBias, но не оба значения. Параметр locationRestriction указывает регион, в котором должны находиться результаты, а параметр locationBias – регион, рядом с которым должны находиться результаты (но они могут быть и за его пределами).

  • maxResultCount

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

  • minRating

    Ограничивает результаты только теми, у которых средняя оценка пользователей больше или равна этому пределу. Значения должны быть в диапазоне от 0,0 до 5,0 (включительно) с шагом 0,5. Например: 0; 0,5; 1,0; …; 5,0 включительно. Значения округляются до ближайшего числа, кратного 0,5. Например, значение 0,6 исключает все результаты с рейтингом менее 1,0.

  • priceLevels

    Ограничить поиск местами, которые отмечены определенными уровнями цен. По умолчанию выбраны все уровни цен.

    Укажите массив из одного или нескольких значений, определенных в PriceLevel.

    Пример:

        let request = SearchByTextRequest()
    request.priceLevels = [GMSPlacesPriceLevel.moderate.rawValue, GMSPlacesPriceLevel.cheap.rawValue]

  • rankPreference

    Определяет, как результаты ранжируются в ответе в зависимости от типа запроса:

    • Для запросов по категориям, например "рестораны в Москве", по умолчанию используется значение .relevance (результаты ранжируются по релевантности). Для параметра rankPreference можно задать значение .relevance или .distance (результаты будут упорядочены по расстоянию).
    • Для запросов, не относящихся к категориям, например "Москва", рекомендуем не задавать параметр rankPreference.

  • regionCode

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

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

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

  • shouldIncludePureServiceAreaBusinesses

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

    Пример:

    Places Swift SDK

    let request = SearchByTextRequest()
request.shouldIncludePureServiceAreaBusinesses = true

    Swift

    let request = SearchByTextRequest()
request.shouldIncludePureServiceAreaBusinesses: true

    Objective-C

    GMSPlaceSearchByTextRequest *request =
    [[GMSPlaceSearchByTextRequest alloc] initWithTextQuery:@"pizza in New York" placeProperties:@[GMSPlacePropertyAll]];
request.shouldIncludePureServiceAreaBusinesses = YES;

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

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

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

Подробнее об указании авторства…