Присоединяйтесь к нам на следующем Дне сообщества разработчиков платформы Google Карт в Сан-Франциско в декабре. Чтобы принять участие, подайте заявку.

Чтобы переводить контент на ваш предпочитаемый язык, Google использует технологии на основе искусственного интеллекта. Переводы от ИИ могут содержать ошибки.

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

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

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

Введение

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

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

API Explorer позволяет отправлять запросы в реальном времени, чтобы вы могли ознакомиться с API и его возможностями.

Попробовать

Запросы к текстовому поиску (New)

Запрос нового текстового поиска – это HTTP-запрос POST следующего вида:

https://places.googleapis.com/v1/places:searchText

Передайте все параметры в теле запроса JSON или в заголовках в составе запроса POST. Пример:

curl -X POST -d '{
  "textQuery" : "Spicy Vegetarian Food in Sydney, Australia"
}' \
-H 'Content-Type: application/json' -H 'X-Goog-Api-Key: API_KEY' \
-H 'X-Goog-FieldMask: places.displayName,places.formattedAddress,places.priceLevel' \
'https://places.googleapis.com/v1/places:searchText'

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

Текстовый поиск (новый) возвращает объект JSON в качестве ответа. В ответе:

Массив places содержит все подходящие места.
Каждое место в массиве представлено объектом Place. Объект Place содержит подробную информацию об одном месте.
Маска FieldMask, переданная в запросе, определяет список полей, возвращаемых в объекте Place.
Список мест, возвращаемый для идентичных запросов, может различаться.

Полный объект JSON имеет следующий вид:

{
  "places": [
    {
      object (Place)
    }
  ]
}

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

FieldMask

Укажите список полей, которые должны возвращаться в ответе, создав маску полей ответа. Передайте маску поля ответа методу, используя параметр URL $fields или fields либо заголовок HTTP X-Goog-FieldMask. В ответе нет списка возвращаемых полей по умолчанию. Если вы не укажете маску поля, метод вернет ошибку.

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

Укажите типы данных о местах, которые нужно возвращать, в виде списка, разделенного запятыми. Например, чтобы получить отображаемое название и адрес места.
```
X-Goog-FieldMask: places.displayName,places.formattedAddress
```
Примечание. В списке полей не должно быть пробелов.

Чтобы получить все поля, используйте *.
```
X-Goog-FieldMask: *
```
Подстановочный знак (*) можно использовать при разработке, но Google не рекомендует использовать его в маске поля ответа в рабочей среде, поскольку в этом случае может возвращаться большой объем данных.

Дополнительные рекомендации по использованию places.iconMaskBaseUri и places.iconBackgroundColor можно найти в разделе Значки мест.

Укажите одно или несколько из следующих полей:
- Следующие поля активируют Text Search Essentials ID Only SKU:
  places.attributions
  places.id
  places.consumerAlert
  places.name^*
  nextPageToken
  places.movedPlace
  places.movedPlaceId
  ^* Поле places.name содержит название ресурса места в виде places/PLACE_ID. Чтобы получить текстовое название места, используйте places.displayName в Pro SKU.
  
  Полный список полей и связанных с ними кодов SKU приведен в разделе Поля данных о местах (новые).
- Следующие поля активируют SKU текстового поиска Pro:
  places.accessibilityOptions
  places.addressComponents
  places.addressDescriptor^*
  places.adrFormatAddress
  places.businessStatus
  places.containingPlaces
  places.displayName
  places.formattedAddress
  places.googleMapsLinks
  places.googleMapsTypeLabel
  places.googleMapsUri
  places.iconBackgroundColor
  places.iconMaskBaseUri
  places.location
  places.openingDate
  places.photos
  places.plusCode
  places.postalAddress
  places.primaryType
  places.primaryTypeDisplayName
  places.pureServiceAreaBusiness
  places.shortFormattedAddress
  places.searchUri
  places.subDestinations
  places.timeZone
  places.types
  places.utcOffsetMinutes
  places.viewport
  
  ^* Описания адресов доступны для клиентов в Индии и являются экспериментальными в других странах.
  Полный список полей и связанных с ними кодов SKU приведен в разделе Поля данных о местах (новые).
- Следующие поля активируют SKU текстового поиска Enterprise:
  places.currentOpeningHours
  places.currentSecondaryOpeningHours
  places.internationalPhoneNumber
  places.nationalPhoneNumber
  places.priceLevel
  places.priceRange
  places.rating
  places.regularOpeningHours
  places.regularSecondaryOpeningHours
  places.transitStation
  places.userRatingCount
  places.websiteUri
  Полный список полей и связанных с ними кодов SKU приведен в разделе Поля данных о местах (новые).
- Код Text Search Enterprise + Atmosphere применяется при запросе любого из следующих полей:
  places.allowsDogs
  places.curbsidePickup
  places.delivery
  places.dineIn
  places.editorialSummary
  places.evChargeAmenitySummary
  places.evChargeOptions
  places.fuelOptions
  places.generativeSummary
  places.goodForChildren
  places.goodForGroups
  places.goodForWatchingSports
  places.liveMusic
  places.menuForChildren
  places.neighborhoodSummary
  places.parkingOptions
  places.paymentOptions
  places.outdoorSeating
  places.reservable
  places.restroom
  places.reviews
  places.reviewSummary
  routingSummaries^*
  places.servesBeer
  places.servesBreakfast
  places.servesBrunch
  places.servesCocktails
  places.servesCoffee
  places.servesDessert
  places.servesDinner
  places.servesLunch
  places.servesVegetarianFood
  places.servesWine
  places.takeout
  
  ^* Только текстовый поиск и поиск поблизости.
  Полный список полей и связанных с ними кодов SKU приведен в разделе Поля данных о местах (новые).

textQuery

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

Новая версия текстового поиска не предназначена для неоднозначных запросов, в том числе следующих:

Тип запроса	Пример
Слишком много понятий или ограничений, например названия нескольких мест, дорог или городов в одном запросе.	"Маркет-стрит Сан-Франциско аэропорт Сан-Хосе"
Элементы почтового адреса, не представленные на Google Картах	"C/O John Smith 123 Main Street" "P.O. Box 13 San Francisco"
Названия компаний, сетей или категорий в сочетании с местоположениями, где эти объекты недоступны.	"Tesco рядом с Далласом, Техас"
Неоднозначные запросы, которые можно интерпретировать по-разному.	"Charger drop-off"
Исторические названия, которые больше не используются.	"Middlesex United Kingdom"
Негеопространственные элементы или намерения	"Сколько лодок в гавани Вентура?"
Неофициальные или рекламные названия.	"Дженга" "Хелтер-скелтер"
Координаты широты и долготы	"37.422131,-122.084801"

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

includeFutureOpeningBusinesses

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

Чтобы получить статус компании, включите places.businessStatus в маску поля запроса. Чтобы получить ожидаемую дату открытия компании, включите в маску поля запроса places.openingDate.
includedType

В результатах поиска предпочтение отдается местам указанного типа, определенного в таблице А. Можно указать только один тип. Пример:
- "includedType":"bar"
- "includedType":"pharmacy"
Примечание. Значения в таблице Б возвращаются только в ответе. Значения из Таблицы Б нельзя использовать в качестве фильтра.

Text Search (New) применяет фильтрацию по типу для определенных запросов в зависимости от применимости. Например, фильтрация по типу может не применяться к запросам с конкретными адресами ("ул. Ленина, д. 123"), но почти всегда применяется к запросам по категориям ("магазины поблизости" или "торговые центры").

Чтобы применить фильтрацию по типу ко всем запросам, задайте для параметра strictTypeFiltering значение true.

Этот параметр не применяется к запросам, связанным с гостиницами или геополитическими объектами (например, административными районами, населенными пунктами, почтовыми индексами, школьными округами или странами).
includePureServiceAreaBusinesses

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

Язык, на котором будут возвращены результаты.
- Вы можете ознакомиться со списком поддерживаемых языков. Google часто обновляет список поддерживаемых языков, поэтому он может быть неполным.
- Если параметр languageCode не указан, API по умолчанию использует en. Если вы укажете недопустимый код языка, API вернет ошибку INVALID_ARGUMENT.
- API пытается предоставить почтовый адрес, понятный как пользователю, так и местным жителям. Для этого он возвращает почтовые адреса на местном языке, при необходимости транслитерируя их в систему письма, понятную пользователю, с учетом предпочитаемого языка. Все остальные адреса возвращаются на предпочитаемом языке. Все компоненты адреса возвращаются на одном языке, который выбирается по первому компоненту.
- Если название на выбранном языке недоступно, API использует наиболее близкое соответствие.
- Предпочтительный язык немного влияет на набор результатов, возвращаемых API, и на порядок их возврата. Геокодер интерпретирует сокращения по-разному в зависимости от языка. Это касается, например, сокращений для типов улиц или синонимов, которые могут быть допустимы в одном языке, но не в другом.
locationBias

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

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

Примечание. Если вы не укажете ни locationBias, ни locationRestriction, то API будет по умолчанию использовать смещение по IP-адресу. В этом случае API использует IP-адрес устройства для уточнения результатов.

Примечание. Параметр locationBias может быть переопределен, если textQuery содержит явное указание местоположения, например Market in Barcelona. В этом случае locationBias игнорируется.

Укажите регион в виде прямоугольной области просмотра или круга.
- Круг определяется центральной точкой и радиусом в метрах. Радиус должен быть в диапазоне от 0,0 до 50 000,0 включительно. Радиус по умолчанию – 0,0. Пример:
```
"locationBias": {
  "circle": {
    "center": {
      "latitude": 37.7937,
      "longitude": -122.3965
    },
    "radius": 500.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, диапазон широт пуст.
  Необходимо указать оба значения, и представленная область не может быть пустой. Если область просмотра пуста, возникает ошибка.
  
  Например, эта область просмотра полностью охватывает Нью-Йорк:
```
"locationBias": {
  "rectangle": {
    "low": {
      "latitude": 40.477398,
      "longitude": -74.259087
    },
    "high": {
      "latitude": 40.91618,
      "longitude": -73.70018
    }
  }
}
```
locationRestriction

Указывает область поиска только для категориальных запросов, которые могут возвращать несколько мест (например, "Рестораны в Москве" или "Торговые центры"). Результаты за пределами указанной области не возвращаются.

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

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

Примечание. Если вы не укажете ни locationBias, ни locationRestriction, то API будет по умолчанию использовать смещение по IP-адресу. В этом случае API использует IP-адрес устройства для смещения результатов.
evOptions

Задает параметры для определения доступных зарядных коннекторов для электромобилей и скорости зарядки.
- connectorTypes
  
  Фильтрует места по типу доступного коннектора для зарядки электромобилей. Места, которые не поддерживают ни один из типов коннекторов, будут отфильтрованы. Поддерживаются следующие типы разъемов: комбинированные (переменного и постоянного тока), Tesla, GB/T (для быстрой зарядки в Китае) и розетки. Подробную информацию вы можете найти в справочной документации.
  - Чтобы отфильтровать результаты для определенного поддерживаемого коннектора, задайте для connectorTypes соответствующее значение. Например, чтобы найти коннекторы J1772 типа 1, задайте для параметра connectorTypes значение EV_CONNECTOR_TYPE_J1772.
  - Чтобы отфильтровать результаты по неподдерживаемым коннекторам, задайте для параметра connectorTypes значение EV_CONNECTOR_TYPE_OTHER.
  - Чтобы отфильтровать результаты по любому типу коннектора, который является розеткой, задайте для параметра connectorTypes значение EV_CONNECTOR_TYPE_UNSPECIFIED_WALL_OUTLET.
  - Чтобы отфильтровать результаты для любого типа коннектора, задайте для connectorTypes значение EV_CONNECTOR_TYPE_UNSPECIFIED или не указывайте значение для connectorTypes.
- minimumChargingRateKw
  
  Фильтрует места по минимальной мощности зарядки ЭМ в киловаттах (кВт). Места, где скорость зарядки ниже минимальной, будут отфильтрованы. Например, чтобы найти зарядные устройства для электромобилей с мощностью зарядки не менее 10 кВт, можно задать для этого параметра значение "10".
minRating

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

Этот параметр не применяется к запросам, связанным с гостиницами или геополитическими объектами (например, административными районами, населенными пунктами, почтовыми индексами, школьными округами или странами).
openNow

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

Этот параметр не применяется к запросам, связанным с гостиницами или геополитическими объектами (например, административными районами, населенными пунктами, почтовыми индексами, школьными округами или странами).
pageSize

Указывает количество результатов (от 1 до 20), которые будут показаны на каждой странице. Например, если задать для параметра pageSize значение 5, то на первой странице будет показано не более пяти результатов. Если запрос может вернуть больше результатов, ответ включает nextPageToken, который можно передать в последующем запросе для доступа к следующей странице.

Это поле заменяет устаревшее поле maxResultCount. Если вы укажете и pageSize, и maxResultCount, API будет использовать pageSize, а maxResultCount проигнорирует.

Примечание. Если параметр pageSize равен 0 или не указан, API по умолчанию возвращает 20 результатов на каждой странице. Если значение pageSize больше 20, API возвращает не более 20 результатов на каждой странице.
pageToken

Указывает значение nextPageToken из тела ответа предыдущей страницы.
priceLevels

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

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

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

Пример:
```
"priceLevels":["PRICE_LEVEL_INEXPENSIVE", "PRICE_LEVEL_MODERATE"]
```
Примечание. В запросе не допускается использование PRICE_LEVEL_FREE. Она используется только для составления ответа.

Этот параметр не применяется к запросам, связанным с гостиницами или геополитическими объектами (например, административными районами, населенными пунктами, почтовыми индексами, школьными округами или странами).
rankPreference

Определяет, как результаты ранжируются в ответе в зависимости от типа запроса:
- Для запросов по категориям, например "рестораны в Москве", по умолчанию используется значение RELEVANCE (результаты ранжируются по релевантности). Для параметра rankPreference можно задать значение RELEVANCE или DISTANCE (результаты будут упорядочены по расстоянию).
- Для запросов, не относящихся к категориям, например "Москва", рекомендуем не задавать параметр rankPreference.
Этот параметр не применяется к запросам, связанным с гостиницами или геополитическими объектами (например, административными районами, населенными пунктами, почтовыми индексами, школьными округами или странами).
regionCode

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

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

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

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

Примеры использования новой версии текстового поиска

Как настроить поиск мест по строке запроса

В примере ниже показан запрос текстового поиска (новый) для фразы "Spicy Vegetarian Food in Sydney, Australia".

curl -X POST -d '{
  "textQuery" : "Spicy Vegetarian Food in Sydney, Australia"
}' \
-H 'Content-Type: application/json' -H 'X-Goog-Api-Key: API_KEY' \
-H 'X-Goog-FieldMask: places.displayName,places.formattedAddress' \
'https://places.googleapis.com/v1/places:searchText'

Обратите внимание, что заголовок X-Goog-FieldMask указывает, что ответ содержит следующие поля данных: places.displayName,places.formattedAddress. Ответ будет иметь следующий вид:

{
  "places": [
    {
      "formattedAddress": "367 Pitt St, Sydney NSW 2000, Australia",
      "displayName": {
        "text": "Mother Chu's Vegetarian Kitchen",
        "languageCode": "en"
      }
    },
    {
      "formattedAddress": "175 First Ave, Five Dock NSW 2046, Australia",
      "displayName": {
        "text": "Veggo Sizzle - Vegan & Vegetarian Restaurant, Five Dock, Sydney",
        "languageCode": "en"
      }
    },
    ...
  ]
}

Чтобы получить дополнительную информацию, добавьте в маску поля больше типов данных. Например, добавьте places.types,places.websiteUri, чтобы включить тип ресторана и веб-адрес в ответ:

curl -X POST -d '{
  "textQuery" : "Spicy Vegetarian Food in Sydney, Australia"
}' \
-H 'Content-Type: application/json' -H 'X-Goog-Api-Key: API_KEY' \
-H 'X-Goog-FieldMask: places.displayName,places.formattedAddress,places.types,places.websiteUri' \
'https://places.googleapis.com/v1/places:searchText'

Теперь ответ выглядит так:

{
  "places": [
    {
      "types": [
        "vegetarian_restaurant",
        "vegan_restaurant",
        "chinese_restaurant",
        "restaurant",
        "food",
        "point_of_interest",
        "establishment"
      ],
      "formattedAddress": "367 Pitt St, Sydney NSW 2000, Australia",
      "websiteUri": "http://www.motherchusvegetarian.com.au/",
      "displayName": {
        "text": "Mother Chu's Vegetarian Kitchen",
        "languageCode": "en"
      }
    },
    {
      "types": [
        "vegan_restaurant",
        "thai_restaurant",
        "vegetarian_restaurant",
        "indian_restaurant",
        "italian_restaurant",
        "american_restaurant",
        "restaurant",
        "food",
        "point_of_interest",
        "establishment"
      ],
      "formattedAddress": "175 First Ave, Five Dock NSW 2046, Australia",
      "websiteUri": "http://www.veggosizzle.com.au/",
      "displayName": {
        "text": "Veggo Sizzle - Vegan & Vegetarian Restaurant, Five Dock, Sydney",
        "languageCode": "en"
      }
    },
    ...
  ]
}

Фильтровать места по уровню цен

Используйте параметр priceLevel, чтобы отфильтровать результаты и оставить только рестораны, которые определены как недорогие или умеренно дорогие:

curl -X POST -d '{
  "textQuery" : "Spicy Vegetarian Food in Sydney, Australia",
  "priceLevels":["PRICE_LEVEL_INEXPENSIVE", "PRICE_LEVEL_MODERATE"]
}' \
-H 'Content-Type: application/json' -H 'X-Goog-Api-Key: API_KEY' \
-H 'X-Goog-FieldMask: places.displayName,places.formattedAddress,places.priceLevel' \
'https://places.googleapis.com/v1/places:searchText'

В этом примере также используется заголовок X-Goog-FieldMask, чтобы добавить поле данных places.priceLevel в ответ. В результате ответ будет иметь следующий вид:

{
  "places": [
    {
      "formattedAddress": "367 Pitt St, Sydney NSW 2000, Australia",
      "priceLevel": "PRICE_LEVEL_MODERATE",
      "displayName": {
        "text": "Mother Chu's Vegetarian Kitchen",
        "languageCode": "en"
      }
    },
    {
      "formattedAddress": "115 King St, Newtown NSW 2042, Australia",
      "priceLevel": "PRICE_LEVEL_MODERATE",
      "displayName": {
        "text": "Green Mushroom",
        "languageCode": "en"
      }
    },
    ...
  ]
}

Добавьте дополнительные параметры, чтобы уточнить поиск, например includedType, minRating, rankPreference, openNow и другие параметры, описанные в разделе Необязательные параметры.

Как ограничить поиск определенной областью

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

Примечание. При использовании locationRestriction регион можно указать только как прямоугольную область просмотра. При использовании locationBias вы можете указать регион в виде прямоугольной области просмотра или круга.

Ограничение области с помощью locationRestriction

Используйте параметр locationRestriction, чтобы ограничить результаты запроса определенным регионом. В теле запроса укажите значения широты и долготы для low и high, которые определяют границы региона.

В примере ниже показан запрос текстового поиска (новый) для вегетарианской еды в Нью-Йорке. Этот запрос возвращает только первые 10 результатов для открытых мест.

curl -X POST -d '{
  "textQuery" : "vegetarian food",
  "pageSize" : "10",
  "locationRestriction": {
    "rectangle": {
      "low": {
        "latitude": 40.477398,
        "longitude": -74.259087
      },
      "high": {
        "latitude": 40.91618,
        "longitude": -73.70018
      }
    }
  }
}' \
  -H 'Content-Type: application/json' \
  -H 'X-Goog-Api-Key: API_KEY' \
  -H 'X-Goog-FieldMask: places.id,places.formattedAddress' \
  'https://places.googleapis.com/v1/places:searchText'

Как задать смещение к области с помощью locationBias

В примере ниже показан запрос текстового поиска (новый) для "вегетарианской еды" с приоритетом местоположения в пределах 500 метров от точки в центре Сан-Франциско. Этот запрос возвращает только первые 10 результатов для открытых мест.

curl -X POST -d '{
  "textQuery" : "vegetarian food",
  "openNow": true,
  "pageSize": 10,
  "locationBias": {
    "circle": {
      "center": {"latitude": 37.7937, "longitude": -122.3965},
      "radius": 500.0
    }
  },
}' \
-H 'Content-Type: application/json' -H 'X-Goog-Api-Key: API_KEY' \
-H 'X-Goog-FieldMask: places.displayName,places.formattedAddress' \
'https://places.googleapis.com/v1/places:searchText'

Как искать зарядные устройства для ЭМ с минимальной скоростью зарядки

Используйте minimumChargingRateKw и connectorTypes, чтобы искать места с доступными зарядными устройствами, совместимыми с вашим электромобилем.

В примере ниже показан запрос на поиск зарядных станций для электромобилей с разъемами Tesla и J1772 типа 1 и минимальной мощностью зарядки 10 кВт в Маунтин-Вью (Калифорния). Возвращаются только четыре результата.

curl -X POST -d '{
    "textQuery": "EV Charging Station Mountain View",
    "pageSize": 4,
    "evOptions": {
      "minimumChargingRateKw": 10,
      "connectorTypes": ["EV_CONNECTOR_TYPE_J1772","EV_CONNECTOR_TYPE_TESLA"]
    }
  }' \
-H 'Content-Type: application/json' -H 'X-Goog-Api-Key: API_KEY' \
-H "X-Goog-FieldMask: places.displayName,places.evChargeOptions" \
'https://places.googleapis.com/v1/places:searchText'

Запрос возвращает следующий ответ:

{
  "places": [
    {
      "displayName": {
        "text": "EVgo Charging Station",
        "languageCode": "en"
      },
      "evChargeOptions": {
        "connectorCount": 16,
        "connectorAggregation": [
          {
            "type": "EV_CONNECTOR_TYPE_CHADEMO",
            "maxChargeRateKw": 100,
            "count": 8,
            "availableCount": 5,
            "outOfServiceCount": 0,
            "availabilityLastUpdateTime": "2024-01-10T19:10:00Z"
          },
          {
            "type": "EV_CONNECTOR_TYPE_CCS_COMBO_1",
            "maxChargeRateKw": 100,
            "count": 2,
            "availableCount": 2,
            "outOfServiceCount": 0,
            "availabilityLastUpdateTime": "2024-01-10T19:10:00Z"
          },
          ...
        ]
      }
    },
    {
      "displayName": {
        "text": "EVgo Charging Station",
        "languageCode": "en"
      },
      "evChargeOptions": {
        "connectorCount": 6,
        "connectorAggregation": [
          {
            "type": "EV_CONNECTOR_TYPE_CCS_COMBO_1",
            "maxChargeRateKw": 100,
            "count": 4,
            "availableCount": 3,
            "outOfServiceCount": 0,
            "availabilityLastUpdateTime": "2024-01-10T19:10:00Z"
          },
          {
            "type": "EV_CONNECTOR_TYPE_CCS_COMBO_1",
            "maxChargeRateKw": 350,
            "count": 2,
            "availableCount": 0,
            "outOfServiceCount": 2,
            "availabilityLastUpdateTime": "2024-01-10T19:10:00Z"
          }
        ]
      }
    },
    ...
  ]
}

Поиск компаний, обслуживающих определенную территорию

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

Ниже приведен пример запроса для сантехников в Сан-Франциско.

curl -X POST -d '{
  "textQuery" : "plumber San Francisco",
  "includePureServiceAreaBusinesses": true
}' \
-H 'Content-Type: application/json' -H 'X-Goog-Api-Key: API_KEY' \
-H 'X-Goog-FieldMask: places.displayName,places.formattedAddress' \
'https://places.googleapis.com/v1/places:searchText'

В ответе для компаний без физического адреса обслуживания не будет поля formattedAddress:

{
  "places": [
    {
      "formattedAddress": "3450 Sacramento St #204, San Francisco, CA 94118, USA",
      "displayName": {
        "text": "Advanced Plumbing & Drain",
        "languageCode": "en"
      }
    },
    {
      "displayName": {
        "text": "Starboy Plumbing Inc.",
        "languageCode": "en"
      }
    },
    ...
  ]
}

Укажите количество результатов на странице

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

В следующем примере показан запрос "пицца в Нью-Йорке" с ограничением в 5 результатов на страницу:

 curl -X POST -d '{
  "textQuery": "pizza in New York",
  "pageSize": 5
  }' \
-H 'Content-Type: application/json' -H 'X-Goog-Api-Key: API_KEY' \
-H "X-Goog-FieldMask: places.id,nextPageToken" \
'https://places.googleapis.com/v1/places:searchText'

{
  "places": [
    {
      "id": "ChIJifIePKtZwokRVZ-UdRGkZzs"
    },
    {
      "id": "ChIJPxPd_P1YwokRfzLhSiACEoU"
    },
    ...
  ],
  "nextPageToken": "AeCrKXsZWzNVbPzO-MRWPu52jWO_Xx8aKwOQ69_Je3DxRpfdjClq8Ekwh3UcF2h2Jn75kL6PtWLGV4ecQri-GEUKN_OFpJkdVc-JL4Q"
}

Чтобы перейти к следующей странице результатов, используйте pageToken для передачи nextPageToken в теле запроса:

 curl -X POST -d '{
  "textQuery": "pizza in New York",
  "pageSize": 5,
  "pageToken": "AeCrKXsZWzNVbPzO-MRWPu52jWO_Xx8aKwOQ69_Je3DxRpfdjClq8Ekwh3UcF2h2Jn75kL6PtWLGV4ecQri-GEUKN_OFpJkdVc-JL4Q"
  }' \
-H 'Content-Type: application/json' -H 'X-Goog-Api-Key: API_KEY' \
-H "X-Goog-FieldMask: places.id,nextPageToken" \
'https://places.googleapis.com/v1/places:searchText'

{
  "places": [
    {
      "id": "ChIJL-LN1N1ZwokR8K2jACu6Ydw"
    },
    {
      "id": "ChIJjaD94kFZwokR-20CXqlpy_4"
    },
    ...
  ],
  "nextPageToken": "AeCrKXvPd6uUy-oj96W2OaqEe2pUD8QTxOM8-sKfUcFsC9t2Wey5qivrKGoGSxcZnyc7RPmaFfAktslrKbUh31ZDTkL0upRmaxA7c_c"
}

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

Описания адресов содержат информацию о местоположении места, включая близлежащие ориентиры и районы.

В примере ниже показан запрос нового текстового поиска мест рядом с торговым центром в Сан-Хосе. В этом примере в маску поля включено значение addressDescriptors:

curl -X POST -d '{
  "textQuery": "clothes",
  "maxResultCount": 5,
  "locationBias": {
    "circle": {
      "center": {
        "latitude": 37.321328,
        "longitude": -121.946275
      }
    }
  },
  "rankPreference":"RANK_PREFERENCE_UNSPECIFIED"
}' \
-H 'Content-Type: application/json' \
-H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: places.displayName,places.addressDescriptor" \
https://places.googleapis.com/v1/places:searchText

Ответ содержит место, указанное в запросе, список ближайших ориентиров и расстояние до них, а также список областей и их отношение к месту.

  {
  "places": [
    {
      "displayName": {
        "text": "Urban Outfitters",
        "languageCode": "en"
      },
      "addressDescriptor": {
        "landmarks": [
          {
            "name": "places/ChIJVVVVUB7Lj4ARXyb4HFVDV8s",
            "placeId": "ChIJVVVVUB7Lj4ARXyb4HFVDV8s",
            "displayName": {
              "text": "Westfield Valley Fair",
              "languageCode": "en"
            },
            "types": [
              "clothing_store",
              "department_store",
              "establishment",
              "food",
              "movie_theater",
              "point_of_interest",
              "restaurant",
              "shoe_store",
              "shopping_mall",
              "store"
            ],
            "spatialRelationship": "WITHIN",
            "straightLineDistanceMeters": 133.72855
          },
          {
            "name": "places/ChIJ62_oCR7Lj4AR_MGWkSPotD4",
            "placeId": "ChIJ62_oCR7Lj4AR_MGWkSPotD4",
            "displayName": {
              "text": "Nordstrom",
              "languageCode": "en"
            },
            "types": [
              "clothing_store",
              "department_store",
              "establishment",
              "point_of_interest",
              "shoe_store",
              "store"
            ],
            "straightLineDistanceMeters": 250.99161
          },
          ...
        ],
        "areas": [
          {
            "name": "places/ChIJb3F-EB7Lj4ARnHApQ_Hu1gI",
            "placeId": "ChIJb3F-EB7Lj4ARnHApQ_Hu1gI",
            "displayName": {
              "text": "Westfield Valley Fair",
              "languageCode": "en"
            },
            "containment": "WITHIN"
          },
          {
            "name": "places/ChIJXYuykB_Lj4AR1Ot8nU5q26Q",
            "placeId": "ChIJXYuykB_Lj4AR1Ot8nU5q26Q",
            "displayName": {
              "text": "Valley Fair",
              "languageCode": "en"
            },
            "containment": "WITHIN"
          },
          ...
        ]
      }
    },
    ...
  ]
}

Как найти компании, которые откроются в будущем

В примере ниже показан запрос Text Search (New) для компаний, которые откроются в будущем в Нью-Медоусе (штат Айдахо).

curl -X POST \
-H "Content-Type: application/json" \
-H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: places.id,places.displayName,places.businessStatus,places.openingDate" \
-d '{
  "textQuery": "Roberts Greenhouse and Tree Farm",
  "includeFutureOpeningBusinesses": true,
  "maxResultCount": 20,
  "locationBias": {
    "circle": {
      "center": {"latitude": 44.9755100, "longitude": -116.2842180},
      "radius": 20
    }
  }
}' \
"https://places.googleapis.com/v1/places:searchText"

В ответе будут указаны компании, которые откроются в будущем, а также их статус и ожидаемая дата открытия:

{
  "places": [
    {
      "id": "ChIJp1-VoKWJplQRMz8g-7Wa3Do",
      "businessStatus": "FUTURE_OPENING",
      "displayName": {
        "text": "Roberts Greenhouse and Tree Farm",
        "languageCode": "en"
      },
      "openingDate": {
        "year": 2026,
        "month": 4,
        "day": 15
      }
    }
  ]
}

Как получить информацию об остановке общественного транспорта

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

Ниже приведен пример запроса для Центрального вокзала Нью-Йорка.

curl -X POST \
-H "Content-Type: application/json" \
-H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: places.id,places.displayName,places.transitStation" \
-d '{
  "textQuery": "Grand Central Station"
}' \
"https://places.googleapis.com/v1/places:searchText"

Тело ответа содержит информацию о каждой станции в пределах радиуса, обслуживаемых ею линиях, оповещениях, выпущенных транспортными агентствами на этой остановке, и информацию об отправлении:

{
  "places": [
    {
      "id": "ChIJhRwB-yFawokRi0AhGH87UTc",
      "displayName": {
        "text": "Grand Central",
        "languageCode": "en"
      },
      "transitStation": {
        "displayName": {
          "text": "Grand Central",
          "languageCode": "en"
        },
        "agencies": [
          {
            "displayName": {
              "text": "Metro-North Railroad",
              "languageCode": "en"
            },
            "url": "http://www.mta.info/mnr",
            "lines": [
              {
                "id": "ChIJOXpD29y2wokRryDO0CocwK0",
                "vehicleType": "HEAVY_RAIL",
                "displayName": {
                  "text": "Harlem",
                  "languageCode": "en"
                },
                "textColor": "#FFFFFF",
                "backgroundColor": "#0061AA",
                "vehicleIcon": {
                  "url": "https://maps.gstatic.com/mapfiles/transit/iw2/svg/rail2.svg"
                },
                "alerts": [
                  {
                    "effect": "OTHER",
                    "texts": [
                      {
                        "headline": {
                          "text": "Information",
                          "languageCode": "en"
                        },
                        "summary": {
                          "text": "Temporary platforms are in place at Botanical Garden, Williams Bridge, and Woodlawn for northbound travel. Build in extra travel time to reach the platform.",
                          "languageCode": "en"
                        },
                        "fullDescription": {
                          "text": "What's Happening? We are renovating some Harlem Line stations in the Bronx. Learn more about the project here.",
                          "languageCode": "en"
                        }
                      }
                    ],
                    "detailsUrls": [
                      {
                        "url": "https://new.mta.info/"
                      }
                    ],
                    "cause": "OTHER_CAUSE",
                    "startTime": "2026-04-16T04:00:00Z",
                    "endTime": "2026-12-01T04:45:00Z",
                    "attribution": {
                      "link": {
                        "text": "new.mta.info",
                        "url": "https://new.mta.info/"
                      }
                    },
                    "createTime": "2026-05-15T22:39:30Z",
                    "severityLevel": "INFO"
                  }
                ]
              },
              ...
            ]
          },
          ...
        ]
        "stops": [
          {
            "id": "ChIJOfdrigFZwokRJPllLwfPrJY",
            "location": {
              "latitude": 40.752823,
              "longitude": -73.977195999999992
            },
            "wheelchairAccessibleEntrance": true
          }
        ],
        "departureBoards": [
          {
            "displayType": "TIME_CENTRIC",
            "rows": [
              {
                "departures": [
                  {
                    "timedDeparture": {
                      "scheduledTime": "2026-05-15T22:42:00Z",
                      "timingType": "SCHEDULED",
                      "predictedTime": "2026-05-15T22:42:00Z",
                      "updateTime": "2026-05-15T22:38:50Z"
                    },
                    "originallyScheduledStopId": "ChIJOfdrigFZwokRJPllLwfPrJY",
                    "lineId": "ChIJAfBuQhwg6IkRYnFpClHxFrM"
                  }
                ]
              },
              ...
            ]
          }
        ]
      }
    },
    {
      "id": "ChIJ_4EAi-pZwokRWe5T1JmmWmc",
      "displayName": {
        "text": "Grand Central Station",
        "languageCode": "en"
      }
    }
  ]
}

Вы можете запросить входы и точки навигации для пункта назначения. Входы определяют точки входа и выхода для места (например, разные ворота в аэропорту или торговом центре). Точки навигации определяют места на обочине, где навигация должна заканчиваться. Это полезно, чтобы направлять пользователей на нужную сторону дороги или к определенной точке высадки.

Точки навигации возвращают navigationPointToken. Вы можете передать этот токен в Navigation SDK (доступен для Android и iOS) или Routes API, чтобы направлять водителей к этому месту. Подробнее о токенах точек навигации…

В примере ниже показан запрос текстового поиска (новый) для "San Francisco International Airport" с полями entrances и navigationPoints в маске поля.

curl -X POST \
-H "Content-Type: application/json" \
-H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: places.id,places.displayName,places.entrances,places.navigationPoints" \
-d '{
  "textQuery": "San Francisco International Airport",
  "pageSize": 1
}' \
"https://places.googleapis.com/v1/places:searchText"

Ответ содержит входы и точки навигации для места:

{
  "places": [
    {
      "id": "ChIJVVVVVYx3j4ARP-3NGldc8qQ",
      "displayName": {
        "text": "San Francisco International Airport",
        "languageCode": "en"
      },
      "entrances": [
        {
          "location": {
            "latitude": 37.6172154,
            "longitude": -122.3839724
          }
        },
        {
          "location": {
            "latitude": 37.6174073,
            "longitude": -122.384196
          }
        },
        ...
      ],
      "navigationPoints": [
        {
          "navigationPointToken": "ChIJoioBjMLOQkAR0A3yH_eYXsA...",
          "displayName": {
            "text": "International Terminal Departures Level",
            "languageCode": "en"
          },
          "location": {
            "latitude": 37.6153121,
            "longitude": -122.3900833
          },
          "travelModes": ["WALK"]
        },
        {
          "navigationPointToken": "ChIJy5JKws_OQkAROx0jNN2YXsA...",
          "displayName": {
            "text": "Domestic Garage - SFO Short Term Parking",
            "languageCode": "en"
          },
          "location": {
            "latitude": 37.6157153,
            "longitude": -122.3885012
          },
          "travelModes": ["DRIVE", "WALK"],
          "usages": ["PARKING"]
        },
        ...
      ]
    }
  ]
}

Попробовать

API Explorer позволяет отправлять тестовые запросы, чтобы вы могли ознакомиться с API и его возможностями.

Нажмите на значок API api в правой части страницы.
При необходимости измените параметры запроса.
Нажмите кнопку Execute (Выполнить). В диалоговом окне выберите аккаунт, который хотите использовать для отправки запроса.
На панели API Explorer нажмите на значок полноэкранного режима fullscreen, чтобы развернуть окно API Explorer.

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

Введение

Запросы к текстовому поиску (New)

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

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

FieldMask

textQuery

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

includeFutureOpeningBusinesses

includedType

includePureServiceAreaBusinesses

languageCode

locationBias

locationRestriction

evOptions

connectorTypes

minimumChargingRateKw

minRating

openNow

pageSize

pageToken

priceLevels

rankPreference

regionCode

strictTypeFiltering

Примеры использования новой версии текстового поиска

Как настроить поиск мест по строке запроса

Фильтровать места по уровню цен

Как ограничить поиск определенной областью

Ограничение области с помощью locationRestriction

Как задать смещение к области с помощью locationBias

Как искать зарядные устройства для ЭМ с минимальной скоростью зарядки

Поиск компаний, обслуживающих определенную территорию

Укажите количество результатов на странице

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

Как найти компании, которые откроются в будущем

Как получить информацию об остановке общественного транспорта

Как посмотреть входы и точки навигации

Попробовать

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