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

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

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

«10 High Street, Великобритания» или «123 Main Street, США». Несколько «Хай-стрит» в Великобритании; несколько «Мейн-стрит» в США. Запрос не возвращает желаемых результатов, если не установлено ограничение местоположения.
«Сеть ресторанов Нью-Йорк» Несколько ресторанов ChainRestaurant в Нью-Йорке; ни адреса, ни даже названия улицы.
«10 High Street, Escher UK» или «123 Main Street, Pleasanton US» Единственная «Хай-стрит» в британском городе Эшер; только одна «Мейн-стрит» в американском городе Плезантон, Калифорния.
«UniqueRestaurantName Нью-Йорк» В Нью-Йорке только одно заведение с таким названием; никакой адрес не нужен для различения.
"пиццерии в Нью-Йорке" Этот запрос содержит ограничение по местоположению, а «рестораны-пиццерии» – это четко определенный тип места. Он возвращает несколько результатов.
"+1 514-670-8700"

Этот запрос содержит номер телефона. Он возвращает несколько результатов для мест, связанных с этим номером телефона.

API Explorer позволяет вам делать запросы в реальном времени, чтобы вы могли ознакомиться с API и опциями 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)
    }
  ]
}

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

  • Маска поля

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

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

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

    X-Goog-FieldMask: places.displayName,places.formattedAddress

    Используйте * чтобы получить все поля.

    X-Goog-FieldMask: *

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

    • Следующие поля запускают SKU текстового поиска (только идентификатор) :

      places.id , places.name *

      * Поле places.name содержит имя ресурса места в форме: places/ PLACE_ID . Используйте places.displayName для доступа к текстовому названию места.
    • Следующие поля активируют SKU текстового поиска (базовый) :

      places.accessibilityOptions , places.addressComponents , places.adrFormatAddress , places.businessStatus , places.displayName , places.formattedAddress , places.googleMapsUri , places.iconBackgroundColor , places.iconMaskBaseUri , places.location , places.photos , places.plusCode , places.primaryType , places.primaryTypeDisplayName , places.shortFormattedAddress , places.subDestinations , places.types , places.utcOffsetMinutes , places.viewport
    • Следующие поля активируют SKU текстового поиска (расширенный) :

      places.currentOpeningHours , places.currentSecondaryOpeningHours , places.internationalPhoneNumber , places.nationalPhoneNumber , places.priceLevel , places.rating , places.regularOpeningHours , places.regularSecondaryOpeningHours , places.userRatingCount , places.websiteUri
    • Следующие поля активируют SKU текстового поиска (предпочтительный) :

      places.allowsDogs , places.curbsidePickup , places.delivery , places.dineIn , places.editorialSummary , places.evChargeOptions , places.fuelOptions , places.goodForChildren , places.goodForGroups , places.goodForWatchingSports , places.liveMusic , places.menuForChildren , places.parkingOptions , places.paymentOptions places.servesDinner places.outdoorSeating , places.reservable places.restroom places.reviews , places.servesBeer , места.сервыЗавтрак , places.servesBreakfast , places.servesBrunch , places.servesCocktails , places.servesCoffee , places.servesDesserts , places.servesLunch , places.servesVegetarianFood , places.servesWine , places.takeout
  • текстовый запрос

    Текстовая строка для поиска, например: «ресторан», «123 Main Street» или «лучшее место для посещения в Сан-Франциско». API возвращает совпадения кандидатов на основе этой строки и упорядочивает результаты на основе их предполагаемой релевантности.

Дополнительные параметры

  • включенный тип

    Ограничивает результаты местами, соответствующими указанному типу, определенному в таблице A. Можно указать только один тип. Например:

    • "includedType":"bar"
    • "includedType":"pharmacy"
  • языковой код

    Язык, на котором возвращаются результаты.

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

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

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

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

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

      Оба значения low и high должны быть заполнены, а представленное поле не может быть пустым. Пустое окно просмотра приводит к ошибке.

      Например, это окно просмотра полностью охватывает Нью-Йорк:

      "locationBias": {
        "rectangle": {
          "low": {
            "latitude": 40.477398,
            "longitude": -74.259087
          },
          "high": {
            "latitude": 40.91618,
            "longitude": -73.70018
          }
        }
      }
  • МестоположениеОграничение

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

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

  • МаксРезультатКаунт

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

  • evOptions

    Определяет параметры для определения доступных разъемов для зарядки электромобилей (EV) и тарифов на зарядку.

    • Типы разъемов

      Фильтры по типу разъема для зарядки электромобиля доступны на месте. Место, не поддерживающее ни один из типов разъемов, будет отфильтровано. Поддерживаемые типы разъемов для зарядки электромобилей включают комбинированные зарядные устройства (переменного и постоянного тока), зарядные устройства Tesla, зарядные устройства, соответствующие стандарту GB/T (для быстрой зарядки электромобилей в Китае), и зарядные устройства для настенных розеток. Дополнительную информацию смотрите в справочной документации.

    • Минимальная скорость зарядки, кВт

      Фильтрует места по минимальной скорости зарядки электромобилей в киловаттах (кВт). Любые места, где взимается ставка ниже минимальной, отфильтровываются. Например, чтобы найти зарядные устройства для электромобилей со скоростью зарядки не менее 10 кВт, вы можете установить для этого параметра значение «10».

  • минРейтинг

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

  • Открой сейчас

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

  • ценаУровни

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

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

    Например:

    "priceLevels":["PRICE_LEVEL_INEXPENSIVE", "PRICE_LEVEL_MODERATE"]
  • рангПредпочтение

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

    • Для категориального запроса, такого как «Рестораны в Нью-Йорке», по умолчанию используется RELEVANCE (ранжирование результатов по релевантности поиска). Вы можете установить для rankPreference значение RELEVANCE или DISTANCE (ранжировать результаты по расстоянию).
    • Для некатегорийного запроса, такого как «Маунтин-Вью, Калифорния», мы рекомендуем оставить rankPreference неустановленным.
  • Код региона

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

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

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

  • строгая фильтрация типов

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

Примеры текстового поиска

Найти место по строке запроса

В следующем примере показан запрос текстового поиска «Острая вегетарианская еда в Сиднее, Австралия»:

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

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

curl -X POST -d '{
  "textQuery" : "Spicy Vegetarian Food",
  "openNow": true,
  "maxResultCount": 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",
    "maxResultCount": 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
          }
        ]
      }
    }
  ]
}

Попробуй это!

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

  1. Выберите значок API, Разверните API Explorer. , в правой части страницы.

  2. При необходимости разверните Показать стандартные параметры и установите для параметра fields маску поля .

  3. При желании отредактируйте тело запроса .

  4. Нажмите кнопку «Выполнить» . Во всплывающем диалоговом окне выберите учетную запись, которую вы хотите использовать для отправки запроса.

  5. На панели API Explorer выберите значок развертывания, Разверните API Explorer. , чтобы развернуть окно API Explorer.