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

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

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

Введение

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

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

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

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

Запрос к новому текстовому поиску представляет собой 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: *

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

    • Следующие поля активируют 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 текстового поиска 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

      * Дескрипторы адресов доступны клиентам в Индии и находятся на этапе тестирования в других странах.

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

    • Следующие поля активируют корпоративный код "Поиск по тексту":

      places.currentOpeningHours
      places.currentSecondaryOpeningHours
      places.internationalPhoneNumber
      places.nationalPhoneNumber
      places.priceLevel
      places.priceRange
      places.rating
      places.regularOpeningHours
      places.regularSecondaryOpeningHours
      places.transitStation
      places.userRatingCount
      places.websiteUri

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

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

      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

      * Только для текстового поиска и поиска поблизости.

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

  • textQuery

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

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

    Тип запроса Пример
    Слишком много понятий или ограничений, например названия нескольких мест, дорог или городов в одном запросе. "Маркет-стрит Сан-Франциско аэропорт Сан-Хосе"
    Элементы почтового адреса, не представленные на Google Картах "C/O John Smith 123 Main Street"
    "P.O. Box 13 San Francisco"
    Названия компаний, сетей или категорий, объединенные с местоположениями, в которых эти объекты недоступны. "Tesco рядом с Далласом, Техас"
    Неоднозначные запросы, которые можно интерпретировать по-разному. "Возврат зарядного устройства"
    Исторические названия, которые больше не используются "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 – регион, в котором результаты, скорее всего, будут находиться или рядом с которым они могут быть, но не обязательно внутри него.

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

    • Окружность определяется центральной точкой и радиусом в метрах. Радиус должен быть в диапазоне от 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 – регион, в котором результаты, скорее всего, будут находиться или рядом с которым они могут быть, но не обязательно внутри него.

  • maxResultCount (поддержка прекращена)

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

  • evOptions

    Указывает параметры для определения доступных коннекторов для зарядки электромобилей и скорости зарядки.

    • connectorTypes

      Фильтрует места по типу доступного коннектора для зарядки электромобилей. Места, которые не поддерживают ни один из типов коннекторов, будут отфильтрованы. Поддерживаются следующие типы разъемов: комбинированные (AC и DC), 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, который можно передать в последующий запрос для доступа к следующей странице.

  • pageToken

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

  • priceLevels

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

    Уровни цен могут быть указаны для мест следующих типов:

    Если указан параметр priceLevels, в ответе не будут представлены места неподдерживаемых типов.

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

    Пример:

    "priceLevels":["PRICE_LEVEL_INEXPENSIVE", "PRICE_LEVEL_MODERATE"]

  • 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 (по умолчанию), ответ может содержать места, не соответствующие указанным типам.

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

Поиск места по строке запроса

В примере ниже показан запрос к новому API текстового поиска для поиска "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"
      }
    },
    {
      "formattedAddress": "29 King St, Sydney NSW 2000, Australia",
      "displayName": {
        "text": "Peace Harmony",
        "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

Используйте параметр 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"
          },
          {
            "type": "EV_CONNECTOR_TYPE_CCS_COMBO_1",
            "maxChargeRateKw": 350,
            "count": 6,
            "availableCount": 3,
            "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"
          }
        ]
      }
    },
    {
      "displayName": {
        "text": "EVgo Charging Station",
        "languageCode": "en"
      },
      "evChargeOptions": {
        "connectorCount": 5,
        "connectorAggregation": [
          {
            "type": "EV_CONNECTOR_TYPE_J1772",
            "maxChargeRateKw": 3.5999999046325684,
            "count": 1,
            "availableCount": 0,
            "outOfServiceCount": 1,
            "availabilityLastUpdateTime": "2024-01-10T19:10:00Z"
          },
          {
            "type": "EV_CONNECTOR_TYPE_CHADEMO",
            "maxChargeRateKw": 50,
            "count": 2,
            "availableCount": 0,
            "outOfServiceCount": 0,
            "availabilityLastUpdateTime": "2024-01-10T19:10:00Z"
          },
          {
            "type": "EV_CONNECTOR_TYPE_CCS_COMBO_1",
            "maxChargeRateKw": 50,
            "count": 2,
            "availableCount": 0,
            "outOfServiceCount": 0,
            "availabilityLastUpdateTime": "2024-01-10T19:10:00Z"
          }
        ]
      }
    },
    {
      "displayName": {
        "text": "Electric Vehicle Charging Station",
        "languageCode": "en"
      },
      "evChargeOptions": {
        "connectorCount": 10,
        "connectorAggregation": [
          {
            "type": "EV_CONNECTOR_TYPE_OTHER",
            "maxChargeRateKw": 210,
            "count": 10
          }
        ]
      }
    }
  ]
}

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

Используйте параметр 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"
      }
    },
    {
      "formattedAddress": "1455 Bancroft Ave, San Francisco, CA 94124, USA",
      "displayName": {
        "text": "Magic Plumbing Heating & Cooling",
        "languageCode": "en"
      }
    },
    /.../
    {
      "displayName": {
        "text": "Starboy Plumbing Inc.",
        "languageCode": "en"
      }
    },
    {
      "formattedAddress": "78 Dorman Ave, San Francisco, CA 94124, USA",
      "displayName": {
        "text": "Cabrillo Plumbing, Heating & Air",
        "languageCode": "en"
      }
    },
    {
      "formattedAddress": "540 Barneveld Ave # D, San Francisco, CA 94124, USA",
      "displayName": {
        "text": "Mr. Rooter Plumbing of San Francisco",
        "languageCode": "en"
      }
    },
    /.../
    {
      "displayName": {
        "text": "Pipeline Plumbing",
        "languageCode": "en"
      }
    },
    {
      "formattedAddress": "350 Bay St #100-178, San Francisco, CA 94133, USA",
      "displayName": {
        "text": "One Source Plumbing and Rooter",
        "languageCode": "en"
      }
    },
    /.../
  ]
}

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

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

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

 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"
    },
    {
      "id": "ChIJrXXKn5NZwokR78g0ipCnY60"
    },
    {
      "id": "ChIJ6ySICVZYwokR9rIK8HjXhzE"
    },
    {
      "id": "ChIJ6xvs94VZwokRnT1D2lX2OTw"
    }
  ],
  "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"
    },
    {
      "id": "ChIJ6ffdpJNZwokRmcafdROM5q0"
    },
    {
      "id": "ChIJ8Q2WSpJZwokRQz-bYYgEskM"
    },
    {
      "id": "ChIJ8164qwFZwokRhplkmhvq1uE"
    }
  ],
  "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
          },
          {
            "name": "places/ChIJ8WvuSB7Lj4ARFyHppkxDRQ4",
            "placeId": "ChIJ8WvuSB7Lj4ARFyHppkxDRQ4",
            "displayName": {
              "text": "Macy's",
              "languageCode": "en"
            },
            "types": [
              "clothing_store",
              "department_store",
              "establishment",
              "point_of_interest",
              "store"
            ],
            "straightLineDistanceMeters": 116.24196
          },
          {
            "name": "places/ChIJ9d3plB_Lj4ARzyaU5bn80WY",
            "placeId": "ChIJ9d3plB_Lj4ARzyaU5bn80WY",
            "displayName": {
              "text": "Bank of America Financial Center",
              "languageCode": "en"
            },
            "types": [
              "bank",
              "establishment",
              "finance",
              "point_of_interest"
            ],
            "straightLineDistanceMeters": 121.61515
          },
          {
            "name": "places/ChIJaXCjxvXLj4ARCPmQpvJ52Lw",
            "placeId": "ChIJaXCjxvXLj4ARCPmQpvJ52Lw",
            "displayName": {
              "text": "Bloomingdale's",
              "languageCode": "en"
            },
            "types": [
              "clothing_store",
              "department_store",
              "establishment",
              "furniture_store",
              "home_goods_store",
              "point_of_interest",
              "shoe_store",
              "store"
            ],
            "straightLineDistanceMeters": 81.32396
          }
        ],
        "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"
          },
          {
            "name": "places/ChIJtYoUX2DLj4ARKoKOb1G0CpM",
            "placeId": "ChIJtYoUX2DLj4ARKoKOb1G0CpM",
            "displayName": {
              "text": "Central San Jose",
              "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
      }
    }
  ]
}

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

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

В примере ниже показан запрос для станции "Grand Central Station":

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, чтобы направлять водителей к определенному местоположению. Подробнее о токенах точек навигации…

В примере ниже показан запрос текстового поиска (New) для "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 и его возможностями.

  1. Нажмите на значок API api в правой части страницы.

  2. При необходимости измените параметры запроса.

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

  4. На панели APIs Explorer нажмите на значок полноэкранного режима , чтобы развернуть окно APIs Explorer.