Автозаполнение мест (устаревшая версия)

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

Place Autocomplete (Legacy) – это веб-сервис, который возвращает подсказки мест в ответ на HTTP-запрос. В запросе указывается текстовая строка поиска и необязательные географические границы. Сервис можно использовать для автозаполнения текстовых географических запросов, возвращая названия мест, например компаний, адресов и достопримечательностей, по мере ввода текста.

Запросы автозаполнения мест (старая версия)

Сервис автозаполнения мест (устаревшая версия) является частью Places API и использует ключ API и квоты Places API.

Сервис автозаполнения мест (устаревшая версия) может обрабатывать полные слова и их части, предлагая подходящие названия мест, адреса и коды Plus Code. Приложения могут передавать запросы по мере их ввода и сразу же предлагать похожие варианты.

Коды plus необходимо форматировать правильно. Это означает, что символ плюса нужно экранировать в URL как %2B, а пробелы – как %20.

  • Глобальный код содержит четырехзначный код региона и не менее шести знаков местного кода. Например, глобальный код 849VCWC8+R9, который используется для экранирования URL, будет преобразован в 849VCWC8%2BR9.
  • Составной код содержит шесть или более знаков местного кода с точными данными о местоположении. Например, экранированный URL-адрес для кода CWC8+R9 Mountain View, CA, USA будет выглядеть так: CWC8%2BR9%20Mountain%20View%20CA%20USA.

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

Запрос автозаполнения мест (устаревшая версия) представляет собой URL с протоколом HTTP следующего формата:

https://maps.googleapis.com/maps/api/place/autocomplete/output?parameters

где output может принимать одно из следующих значений:

  • json (рекомендуется) – вывод в формате JSON (JavaScript Object Notation).
  • xml – вывод в формате XML.

Для отправки запроса автозаполнения мест (устаревшего) требуются определенные параметры. Параметры разделяются амперсандами (&) в соответствии со стандартом написания URL. Список параметров и их возможных значений приведен ниже.

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

  • ввод

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

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

  • компоненты

    Группа мест, в пределах которой вы хотите ограничить результаты поиска. С помощью компонентов можно фильтровать результаты, чтобы в них входили места из не более чем пяти стран. Страны нужно указывать в виде двухбуквенного кода по стандарту ISO 3166-1 Alpha-2. Например, components=country:fr ограничит результаты местами во Франции. Чтобы указать несколько стран, передайте несколько фильтров country:XX, разделив их вертикальной чертой |. Например, components=country:us|country:pr|country:vi|country:gu|country:mp ограничит результаты местами в США и на их неинкорпорированных организованных территориях.

    Примечание. Если использование кода страны приводит к непредвиденным результатам, убедитесь, что код включает нужные страны, зависимые территории и особые географические области. Коды можно найти в статье Википедии со списком кодов стран по ISO 3166 и на онлайн-платформе ISO.

  • language

    Язык, на котором будут возвращены результаты.

    • Вы можете ознакомиться со списком поддерживаемых языков. Google часто обновляет список поддерживаемых языков, поэтому он может быть неполным.
    • Если параметр language не указан, API попытается использовать предпочитаемый язык, заданный в заголовке Accept-Language.
    • API старается предоставить почтовый адрес, который будет понятен как пользователю, так и местным жителям. Для этого он возвращает почтовые адреса на местном языке, при необходимости транслитерируя их в систему письма, понятную пользователю, с учетом предпочитаемого языка. Все остальные адреса возвращаются на предпочитаемом языке. Все компоненты адреса возвращаются на одном языке, который выбирается на основе первого компонента.
    • Если название на предпочитаемом языке недоступно, API использует ближайшее соответствие.
    • Предпочтительный язык незначительно влияет на набор результатов, возвращаемых API, и порядок их следования. Геокодер интерпретирует сокращения по-разному в зависимости от языка, например сокращения типов улиц или синонимы, которые могут быть действительны на одном языке, но не на другом. Например, в венгерском языке слова utca и tér являются синонимами слова "улица".

  • местоположение

    Точка, вокруг которой нужно получить информацию о местах. Необходимо указать значение latitude,longitude. При указании местоположения также необходимо задать параметр radius. Если параметр radius не указан, параметр location игнорируется.

    При использовании Text Search API параметр `location` может быть переопределен, если в параметре `query` указано местоположение, например `Рынок в Барселоне`.

  • locationbias

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

    • "Смещение по IP-адресу" – указывает API использовать смещение по IP-адресу. Передайте строку ipbias (у этого варианта нет дополнительных параметров).
    • Круг. Строка, в которой указан радиус в метрах, а также широта и долгота в десятичных градусах. Используйте следующий формат: circle:radius@lat,lng.
    • Прямоугольник: строка, содержащая две пары координат широты и долготы в десятичных градусах, представляющие юго-западную и северо-восточную точки прямоугольника. Используйте следующий формат:rectangle:south,west|north,east. Обратите внимание, что значения долготы (восток/запад) должны находиться в диапазоне от -180 до 180, а значения широты (север/юг) – в диапазоне от -90 до 90.

  • locationrestriction

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

    • Круг: строка, в которой указан радиус в метрах, а также широта и долгота в десятичных градусах. Используйте следующий формат: circle:radius@lat,lng.
    • Прямоугольник: строка, содержащая две пары координат широты и долготы в десятичных градусах, представляющие юго-западную и северо-восточную точки прямоугольника. Используйте следующий формат:rectangle:south,west|north,east. Обратите внимание, что значения долготы (восток/запад) приводятся к диапазону от -180 до 180, а значения широты (север/юг) – к диапазону от -90 до 90.

  • смещение;

    Позиция последнего символа в поисковом запросе, который сервис использует для сопоставления подсказок. Например, если входные данные – Google, а смещение – 3, сервис найдет соответствие для Goo. Строка, определяемая смещением, сопоставляется только с первым словом во входном термине. Например, если в качестве входного термина указано Google abc, а смещение равно 3, то сервис попытается найти совпадение с Goo abc. Если смещение не указано, сервис будет использовать весь срок. Смещение обычно должно быть установлено на позицию текстового курсора.

  • происхождение

    Исходная точка, от которой рассчитывается расстояние по прямой до пункта назначения (возвращается как distance_meters). Если это значение не указано, расстояние по прямой не возвращается. Необходимо указать следующее значение: latitude,longitude.

  • радиус

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

    Радиус будет автоматически ограничен максимальным значением в зависимости от типа поиска и других параметров.

    • Автозаполнение: 50 000 метров.
    • Поиск поблизости:
      • с keyword или name – 50 000 метров;
      • без keyword или name
        • До 50 000 метров. Радиус корректируется динамически в зависимости от плотности застройки и не зависит от параметра rankby.
        • При использовании параметра rankby=distance параметр радиуса не принимается и приводит к ошибке INVALID_REQUEST.
    • Автозаполнение запросов: 50 000 м.
    • Текстовый поиск: 50 000 метров.

  • регион

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

  • sessiontoken

    Случайная строка, которая идентифицирует сеанс автозаполнения для выставления счетов.

    Сеанс начинается в тот момент, когда пользователь начинает вводить запрос, а завершается тогда, когда он выбирает место и выполняется вызов информации о местах. В каждом сеансе может быть несколько запросов, после которых следует выбор одного места. Ключи API, используемые для каждого запроса в рамках сеанса, должны принадлежать одному и тому же проекту Google Cloud Console. Когда сеанс завершается, токен перестает быть действительным. Ваше приложение должно создавать новый токен для каждого сеанса. Если параметр sessiontoken не указан или вы повторно используете токен сеанса, плата за сеанс будет начислена как при отсутствии токена (каждый запрос оплачивается отдельно).

    Мы рекомендуем следующее:

    • Используйте токены сеансов для всех сеансов автозаполнения.
    • Создавайте новый токен для каждого сеанса. Рекомендуется использовать UUID версии 4.
    • Убедитесь, что ключи API, используемые для всех запросов автозаполнения мест и информации о местах в рамках сеанса, принадлежат одному и тому же проекту Cloud Console.
    • Обязательно передавайте уникальный токен сеанса для каждого нового сеанса. Если использовать один токен для нескольких сеансов, плата за каждый сеанс будет начислена по отдельности.

  • strictbounds

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

  • типы

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

    У места может быть только один основной тип из таблицы 1 или таблицы 2. Например, отель, в котором подают еду, можно вернуть только с помощью значения types=lodging, а не types=restaurant.

    Для значения параметра types можно указать один из приведенных ниже вариантов.

    • До пяти значений из таблицы 1 или таблицы 2. Если значений несколько, разделите их вертикальной чертой (|). Пример:

      types=book_store|cafe

    • Любой поддерживаемый фильтр из таблицы 3. Нельзя объединять коллекции разных типов.

    Запрос будет отклонен с ошибкой INVALID_REQUEST, если:

    • Указано более пяти типов.
    • присутствуют неизвестные типы;
    • Типы из таблицы 1 или таблицы 2 сочетаются с любыми фильтрами из таблицы 3.

Примеры использования автозаполнения мест (устаревшая версия)

Запрос на поиск организаций, в названии которых есть строка "Amoeba", в области с центром в Сан-Франциско, Калифорния:

URL

https://maps.googleapis.com/maps/api/place/autocomplete/json
      ?input=amoeba
      &types=establishment
      &location=37.76999%2C-122.44696
      &radius=500
      &key=YOUR_API_KEY

curl

curl -L -X GET 'https://maps.googleapis.com/maps/api/place/autocomplete/json?input=amoeba&types=establishment&location=37.76999%2C-122.44696&radius=500&key=YOUR_API_KEY'

Тот же запрос, но с ограничением на результаты в пределах 500 метров от пересечения улиц Эшбери и Хейт в Сан-Франциско:

URL

https://maps.googleapis.com/maps/api/place/autocomplete/json
      ?input=amoeba
      &types=establishment
      &location=37.76999%2C-122.44696&radius=500
      &strictbounds=true
      &key=YOUR_API_KEY

curl

curl -L -X GET 'https://maps.googleapis.com/maps/api/place/autocomplete/json?input=amoeba&types=establishment&location=37.76999%2C-122.44696&radius=500&strictbounds=true&key=YOUR_API_KEY'

Запрос на поиск адресов, в которых содержится слово "Vict". Результаты отображаются на французском языке.

URL

https://maps.googleapis.com/maps/api/place/autocomplete/json
      ?input=Vict
      &types=geocode
      &language=fr
      &key=YOUR_API_KEY

curl

curl -L -X GET 'https://maps.googleapis.com/maps/api/place/autocomplete/json?input=Vict&types=geocode&language=fr&key=YOUR_API_KEY'

Запрос городов, содержащих "Vict", с результатами на бразильском португальском языке:

URL

https://maps.googleapis.com/maps/api/place/autocomplete/json
      ?input=Vict
      &types=(cities)
      &language=pt_BR&key=YOUR_API_KEY

curl

curl -L -X GET 'https://maps.googleapis.com/maps/api/place/autocomplete/json?input=Vict&types=(cities)&language=pt_BR&key=YOUR_API_KEY'

Обратите внимание, что в этих примерах вам нужно будет заменить ключ API на свой.

Ответ автозаполнения мест (устаревшая версия)

Ответы автозаполнения мест (Legacy) возвращаются в формате, указанном флагом output в пути URL запроса. Ниже приведены результаты, которые могут быть возвращены для запроса со следующими параметрами:

URL

https://maps.googleapis.com/maps/api/place/autocomplete/json
      ?input=Paris
      &types=geocode
      &key=YOUR_API_KEY

curl

curl -L -X GET 'https://maps.googleapis.com/maps/api/place/autocomplete/json?input=Paris&types=geocode&key=YOUR_API_KEY'

JSON

{
  "predictions":
    [
      {
        "description": "Paris, France",
        "matched_substrings": [{ "length": 5, "offset": 0 }],
        "place_id": "ChIJD7fiBh9u5kcRYJSMaMOCCwQ",
        "reference": "ChIJD7fiBh9u5kcRYJSMaMOCCwQ",
        "structured_formatting":
          {
            "main_text": "Paris",
            "main_text_matched_substrings": [{ "length": 5, "offset": 0 }],
            "secondary_text": "France",
          },
        "terms":
          [
            { "offset": 0, "value": "Paris" },
            { "offset": 7, "value": "France" },
          ],
        "types": ["locality", "political", "geocode"],
      },
      {
        "description": "Paris, TX, USA",
        "matched_substrings": [{ "length": 5, "offset": 0 }],
        "place_id": "ChIJmysnFgZYSoYRSfPTL2YJuck",
        "reference": "ChIJmysnFgZYSoYRSfPTL2YJuck",
        "structured_formatting":
          {
            "main_text": "Paris",
            "main_text_matched_substrings": [{ "length": 5, "offset": 0 }],
            "secondary_text": "TX, USA",
          },
        "terms":
          [
            { "offset": 0, "value": "Paris" },
            { "offset": 7, "value": "TX" },
            { "offset": 11, "value": "USA" },
          ],
        "types": ["locality", "political", "geocode"],
      },
      {
        "description": "Paris, TN, USA",
        "matched_substrings": [{ "length": 5, "offset": 0 }],
        "place_id": "ChIJ4zHP-Sije4gRBDEsVxunOWg",
        "reference": "ChIJ4zHP-Sije4gRBDEsVxunOWg",
        "structured_formatting":
          {
            "main_text": "Paris",
            "main_text_matched_substrings": [{ "length": 5, "offset": 0 }],
            "secondary_text": "TN, USA",
          },
        "terms":
          [
            { "offset": 0, "value": "Paris" },
            { "offset": 7, "value": "TN" },
            { "offset": 11, "value": "USA" },
          ],
        "types": ["locality", "political", "geocode"],
      },
      {
        "description": "Paris, Brant, ON, Canada",
        "matched_substrings": [{ "length": 5, "offset": 0 }],
        "place_id": "ChIJsamfQbVtLIgR-X18G75Hyi0",
        "reference": "ChIJsamfQbVtLIgR-X18G75Hyi0",
        "structured_formatting":
          {
            "main_text": "Paris",
            "main_text_matched_substrings": [{ "length": 5, "offset": 0 }],
            "secondary_text": "Brant, ON, Canada",
          },
        "terms":
          [
            { "offset": 0, "value": "Paris" },
            { "offset": 7, "value": "Brant" },
            { "offset": 14, "value": "ON" },
            { "offset": 18, "value": "Canada" },
          ],
        "types": ["neighborhood", "political", "geocode"],
      },
      {
        "description": "Paris, KY, USA",
        "matched_substrings": [{ "length": 5, "offset": 0 }],
        "place_id": "ChIJsU7_xMfKQ4gReI89RJn0-RQ",
        "reference": "ChIJsU7_xMfKQ4gReI89RJn0-RQ",
        "structured_formatting":
          {
            "main_text": "Paris",
            "main_text_matched_substrings": [{ "length": 5, "offset": 0 }],
            "secondary_text": "KY, USA",
          },
        "terms":
          [
            { "offset": 0, "value": "Paris" },
            { "offset": 7, "value": "KY" },
            { "offset": 11, "value": "USA" },
          ],
        "types": ["locality", "political", "geocode"],
      },
    ],
  "status": "OK",
}

XML

    
<?xml version="1.0" encoding="UTF-8"?>
<AutocompletionResponse>
 <status>OK</status>
 <prediction>
  <description>Paris, France</description>
  <type>locality</type>
  <type>political</type>
  <type>geocode</type>
  <reference>ChIJD7fiBh9u5kcRYJSMaMOCCwQ</reference>
  <term>
   <value>Paris</value>
   <offset>0</offset>
  </term>
  <term>
   <value>France</value>
   <offset>7</offset>
  </term>
  <matched_substring>
   <offset>0</offset>
   <length>5</length>
  </matched_substring>
  <place_id>ChIJD7fiBh9u5kcRYJSMaMOCCwQ</place_id>
  <structured_formatting>
   <description>Paris</description>
   <subdescription>France</subdescription>
   <description_matched_substring>
    <offset>0</offset>
    <length>5</length>
   </description_matched_substring>
  </structured_formatting>
 </prediction>
 <prediction>
  <description>Paris, TX, USA</description>
  <type>locality</type>
  <type>political</type>
  <type>geocode</type>
  <reference>ChIJmysnFgZYSoYRSfPTL2YJuck</reference>
  <term>
   <value>Paris</value>
   <offset>0</offset>
  </term>
  <term>
   <value>TX</value>
   <offset>7</offset>
  </term>
  <term>
   <value>USA</value>
   <offset>11</offset>
  </term>
  <matched_substring>
   <offset>0</offset>
   <length>5</length>
  </matched_substring>
  <place_id>ChIJmysnFgZYSoYRSfPTL2YJuck</place_id>
  <structured_formatting>
   <description>Paris</description>
   <subdescription>TX, USA</subdescription>
   <description_matched_substring>
    <offset>0</offset>
    <length>5</length>
   </description_matched_substring>
  </structured_formatting>
 </prediction>
 <prediction>
  <description>Paris, TN, USA</description>
  <type>locality</type>
  <type>political</type>
  <type>geocode</type>
  <reference>ChIJ4zHP-Sije4gRBDEsVxunOWg</reference>
  <term>
   <value>Paris</value>
   <offset>0</offset>
  </term>
  <term>
   <value>TN</value>
   <offset>7</offset>
  </term>
  <term>
   <value>USA</value>
   <offset>11</offset>
  </term>
  <matched_substring>
   <offset>0</offset>
   <length>5</length>
  </matched_substring>
  <place_id>ChIJ4zHP-Sije4gRBDEsVxunOWg</place_id>
  <structured_formatting>
   <description>Paris</description>
   <subdescription>TN, USA</subdescription>
   <description_matched_substring>
    <offset>0</offset>
    <length>5</length>
   </description_matched_substring>
  </structured_formatting>
 </prediction>
 <prediction>
  <description>Paris, Brant, ON, Canada</description>
  <type>neighborhood</type>
  <type>political</type>
  <type>geocode</type>
  <reference>ChIJsamfQbVtLIgR-X18G75Hyi0</reference>
  <term>
   <value>Paris</value>
   <offset>0</offset>
  </term>
  <term>
   <value>Brant</value>
   <offset>7</offset>
  </term>
  <term>
   <value>ON</value>
   <offset>14</offset>
  </term>
  <term>
   <value>Canada</value>
   <offset>18</offset>
  </term>
  <matched_substring>
   <offset>0</offset>
   <length>5</length>
  </matched_substring>
  <place_id>ChIJsamfQbVtLIgR-X18G75Hyi0</place_id>
  <structured_formatting>
   <description>Paris</description>
   <subdescription>Brant, ON, Canada</subdescription>
   <description_matched_substring>
    <offset>0</offset>
    <length>5</length>
   </description_matched_substring>
  </structured_formatting>
 </prediction>
 <prediction>
  <description>Paris, KY, USA</description>
  <type>locality</type>
  <type>political</type>
  <type>geocode</type>
  <reference>ChIJsU7_xMfKQ4gReI89RJn0-RQ</reference>
  <term>
   <value>Paris</value>
   <offset>0</offset>
  </term>
  <term>
   <value>KY</value>
   <offset>7</offset>
  </term>
  <term>
   <value>USA</value>
   <offset>11</offset>
  </term>
  <matched_substring>
   <offset>0</offset>
   <length>5</length>
  </matched_substring>
  <place_id>ChIJsU7_xMfKQ4gReI89RJn0-RQ</place_id>
  <structured_formatting>
   <description>Paris</description>
   <subdescription>KY, USA</subdescription>
   <description_matched_substring>
    <offset>0</offset>
    <length>5</length>
   </description_matched_substring>
  </structured_formatting>
 </prediction>
</AutocompletionResponse>

PlacesAutocompleteResponse

Поле Обязательно Тип Описание
Обязательно Массив<PlaceAutocompletePrediction>

Содержит массив подсказок.

Подробную информацию можно найти в статье PlaceAutocompletePrediction.

Обязательно PlacesAutocompleteStatus

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

Дополнительную информацию можно найти в разделе PlacesAutocompleteStatus.

необязательно string

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

необязательно Array<string>

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

Особый интерес в результатах представляют элементы place_id, которые можно использовать для запроса более подробных сведений о месте с помощью отдельного запроса. Подробнее о запросах информации о местах (устаревшая версия)…

Ответ XML состоит из одного элемента <AutocompletionResponse> с двумя типами дочерних элементов:

  • Элемент <status> содержит метаданные запроса. Подробнее о кодах статуса…
  • Ноль или более элементов <prediction>, каждый из которых содержит информацию об одном месте. Подробную информацию о результатах можно найти в статье Результаты автозаполнения мест (Legacy). Places API возвращает до пяти результатов.

Мы рекомендуем использовать флаг json в качестве предпочтительного выходного флага, если только вашему приложению по какой-либо причине не требуется флаг xml. При обработке XML-деревьев нужно внимательно следить за тем, чтобы вы ссылались на правильные узлы и элементы. Подробнее о том, как обрабатывать XML с помощью XPath…

PlacesAutocompleteStatus

Коды статуса, возвращаемые сервисом.

  • OK означает, что запрос к API успешно выполнен;
  • ZERO_RESULTS означает, что поиск выполнен успешно, но результаты не найдены. Такое может произойти, если при поиске были переданы границы в отдаленном местоположении.
  • INVALID_REQUEST означает, что запрос к API сформирован неправильно, как правило, из-за отсутствия параметра input.
  • OVER_QUERY_LIMIT, в котором указано одно из следующего:
    • Вы превысили лимиты на количество запросов в секунду.
    • В вашем аккаунте не включены платежные функции.
    • Превышен месячный бонус в размере 200 долларов США или заданное ограничение на использование.
    • Указанный способ оплаты больше не действует (например, истек срок действия кредитной карты).
    Подробнее о том, как устранить эту ошибку, можно узнать в разделе часто задаваемых вопросов о Картах.
  • REQUEST_DENIED – запрос был отклонен, как правило, по одной из следующих причин:
    • В запросе отсутствует ключ API.
    • Недопустимый параметр key.
  • UNKNOWN_ERROR означает неизвестную ошибку.

Когда сервис Places возвращает результаты поиска в формате JSON, он помещает их в массив predictions. Даже если сервис не возвращает никаких результатов (например, если location находится в отдаленном месте), он все равно возвращает пустой массив predictions. Ответы в формате XML состоят из нуля или более элементов <prediction>.

PlaceAutocompletePrediction

Поле Обязательно Тип Описание
Обязательно string

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

Обязательно Массив<PlaceAutocompleteMatchedSubstring>

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

Дополнительную информацию можно найти в описании класса PlaceAutocompleteMatchedSubstring.

Обязательно PlaceAutocompleteStructuredFormat

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

Подробнее PlaceAutocompleteStructuredFormat…

Обязательно Массив<PlaceAutocompleteTerm>

Содержит массив терминов, идентифицирующих каждый раздел возвращенного описания (раздел описания обычно заканчивается запятой). Каждая запись в массиве содержит поле value с текстом термина и поле offset, определяющее начальную позицию этого термина в описании (в символах Юникода).

Дополнительную информацию можно найти в описании класса PlaceAutocompleteTerm.

необязательно Целое число

Расстояние по прямой в метрах от пункта отправления. Это поле возвращается только в запросах, сделанных с помощью origin.

необязательно string

уникальный текстовый идентификатор места. Чтобы извлечь информацию о месте, передайте этот идентификатор в поле placeId запроса к Places API. Подробнее об идентификаторах мест…

необязательно string

См. place_id.
необязательно Array<string>

Массив типов, относящихся к этому месту. Примеры:[ "political", "locality" ] или [ "establishment", "geocode", "beauty_salon" ]. Массив может содержать несколько значений. Подробнее о типах мест…

PlaceAutocompleteMatchedSubstring

Поле Обязательно Тип Описание
Обязательно число

Длина совпадающей подстроки в тексте результата прогноза.
Обязательно число

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

PlaceAutocompleteStructuredFormat

Поле Обязательно Тип Описание

main_text

Обязательно string

Содержит основной текст подсказки, обычно название места.

main_text_matched_substrings

Обязательно Массив<PlaceAutocompleteMatchedSubstring>

Содержит массив со значением offset и length. Они описывают местоположение введенного термина в тексте результата прогноза, чтобы его можно было выделить, если он будет выбран.

Дополнительную информацию можно найти в описании класса PlaceAutocompleteMatchedSubstring.

secondary_text

необязательно string

Содержит дополнительный текст подсказки, обычно местоположение места.

secondary_text_matched_substrings

необязательно Массив<PlaceAutocompleteMatchedSubstring>

Содержит массив со значением offset и length. Они описывают местоположение введенного термина в тексте результата прогноза, чтобы его можно было выделить, если он будет выбран.

Дополнительную информацию можно найти в описании класса PlaceAutocompleteMatchedSubstring.

PlaceAutocompleteTerm

Поле Обязательно Тип Описание
Обязательно число

Определяет начальную позицию термина в описании, измеряемую в символах Юникода.

Обязательно string

Текст термина.

Оптимизация автозаполнения мест (устаревшая версия)

В этом разделе приведены рекомендации по эффективному использованию сервиса автозаполнения мест (устаревшая версия).

Рассмотрим некоторые общие рекомендации.

Рекомендации по оптимизации затрат

Базовая оптимизация затрат

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

Дополнительная оптимизация затрат

Рассмотрите возможность программно реализовать сервис Place Autocomplete (устаревшая версия), чтобы получить доступ к коду Autocomplete – Per Request и запрашивать результаты Geocoding API о выбранном месте вместо Place Details (устаревшая версия). Тариф Per Request в сочетании Geocoding API будет выгоднее, чем тариф Per Session (на основе сеансов), если соблюдаются два следующих условия:

  • Если вам нужны только широта и долгота или адрес выбранного пользователем места, получить эту информацию с помощью Geocoding API дешевле, чем вызывать Place Details (Legacy).
  • Если пользователи выбирают подсказку автозаполнения в среднем из четырех запросов автозаполнения мест (Legacy) или из меньшего числа, тариф за запрос может быть выгоднее, чем за сеанс.
Чтобы получить помощь в выборе подходящей реализации автозаполнения мест (устаревшая версия), нажмите на вкладку, которая соответствует вашему ответу на приведенный ниже вопрос.

Требуется ли в вашем приложении какая-либо информация помимо адреса и широты и долготы выбранной подсказки?

Да, нужно больше сведений

Используйте сервис автозаполнения мест (устаревший) на основе сеансов совместно с информацией о местах (устаревшая версия).
Поскольку вашему приложению требуются данные о месте (устаревшая версия), например название места, статус компании или часы работы, в реализации Place Autocomplete (устаревшая версия) следует использовать токен сеанса (программно или встроенный в виджеты JavaScript, Android или iOS) на сеанс, а также применимые коды SKU для данных о местах в зависимости от того, какие поля данных о местах вы запрашиваете.1

Реализация виджета
Функция автоматического управления сеансами встроена в виджеты для JavaScript, Android, или iOS. В нее входят как запросы автозаполнения мест (устаревшая версия), так и запрос информации о местах (устаревшая версия) для выбранной подсказки. Обязательно укажите параметр fields, чтобы запрашивались только нужные поля данных автозаполнения мест (устаревшее).

Программная реализация
Используйте токен сеанса с запросами автозаполнения мест (устаревшая версия). Запрашивая информацию о местах (устаревшей версии) о выбранной подсказке, указывайте следующие параметры:

  1. идентификатор места из ответа автозаполнения мест (устаревшая версия)
  2. токен сеанса, использованный в запросе автозаполнения мест (устаревшая версия);
  3. Параметр fields, указывающий нужные поля данных автозаполнения мест (устаревшая версия).

Нет, нужны только адрес и местоположение

Возможно, для вашего приложения Geocoding API будет более выгодным вариантом, чем Place Details (Legacy). Это зависит от того, насколько эффективно вы используете Place Autocomplete (Legacy). Эффективность функции автозаполнения мест (устаревшей) в каждом приложении зависит от того, какие запросы вводят пользователи, где используется приложение и реализованы ли рекомендации по оптимизации производительности.

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

Выбирают ли пользователи подсказку автозаполнения мест (устаревшая версия) в среднем из числа первых четырех запросов?

Да

Реализуйте автозаполнение мест (устаревшая версия) программно без токенов сеансов и вызывайте Geocoding API для выбранной подсказки места.
Geocoding API предоставляет адреса и координаты широты и долготы. Четыре запроса Autocomplete – Per Request вместе с вызовом Geocoding API о выбранной подсказке места стоят меньше, чем сеанс Place Autocomplete (устаревшая версия)1.

Рассмотрите возможность применить рекомендации по оптимизации эффективности, чтобы помочь пользователям получать нужные результаты, вводя минимальное количество символов.

Нет

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

Реализация виджета
Функция автоматического управления сеансами встроена в виджеты для JavaScript, Android и iOS. В нее входят как запросы автозаполнения мест (Legacy), так и запрос информации о местах (Legacy) для выбранной подсказки. Обязательно укажите параметр fields, чтобы запрашивались только нужные поля.

Программная реализация
Используйте токен сеанса с запросами автозаполнения мест (устаревшая версия). Запрашивая у Place Details (устаревшая версия) информацию о выбранной подсказке, указывайте следующие параметры:

  1. идентификатор места из ответа автозаполнения мест (устаревшая версия)
  2. токен сеанса, использованный в запросе автозаполнения мест (устаревшая версия);
  3. Параметр fields, указывающий поля Basic Data, например адрес и геометрические данные.

Рассмотрите возможность откладывать запросы автозаполнения мест (устаревшая версия)
Вы можете попробовать различные стратегии, например откладывать запрос автозаполнения мест (устаревшая версия), пока пользователь не введет первые три или четыре символа, чтобы ваше приложение совершало меньше запросов. Например, если вы будете отправлять запросы Place Autocomplete (Legacy) для каждого символа после того, как пользователь введет третий символ, то при вводе семи символов и выборе подсказки, для которой вы отправите один запрос Geocoding API, общая стоимость составит 4 запроса Place Autocomplete (Legacy) Per Request + Geocoding.1

Если при откладывании запросов среднее число автоматизированных запросов станет меньше четырех, вы сможете эффективно использовать сервис автозаполнения мест (Legacy) с Geocoding API. Обратите внимание, что пользователь, ожидающий появления подсказок с каждым введенным символом, может принять откладывание запросов за задержку.

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

  1. Информацию о стоимости можно найти в списках цен на платформу Google Карт.

Рекомендации по повышению эффективности

В рекомендациях ниже описаны способы оптимизации производительности автозаполнения мест (устаревшей версии):

  • Добавьте в свою реализацию Place Autocomplete (Legacy) ограничения по стране, предпочтение местоположений и (для программных реализаций) предпочитаемый язык. Предпочитаемый язык не нужен в случае виджетов, потому что для них язык определяется на основе настроек браузера или мобильного устройства.
  • Если вместе с автозаполнением мест (Legacy) отображается карта, вы можете сделать предпочитаемым местоположением видимую область карты.
  • Если пользователь не выберет ни одну из подсказок автозаполнения мест (устаревшая версия) – чаще всего такое бывает, если ни одна из них не соответствует искомому адресу, – вы можете повторно использовать ввод данных пользователем, чтобы получить более подходящие результаты:
    • Если вы рассчитываете, что пользователь будет вводить только информацию об адресе, повторно используйте изначально введенные им данные в вызове Geocoding API.
    • Если пользователь скорее всего будет вводить запросы для определенного места по названию или адресу, используйте запрос информации о местах (устаревший). Если ожидается, что результаты будут из определенного региона, используйте предпочтение местоположений.
    К другим сценариям, при которых лучше вернуться к использованию Geocoding API, относятся следующие:
    • Пользователи вводят адреса помещений, например квартир в здании. Так, для адреса в Чехии "Stroupežnického 3191/17, Praha" автозаполнение мест (устаревшее) покажет частичную подсказку.
    • Пользователь вводит адрес с префиксом для ряда домов, например "23-30 29th St, Queens" в Нью-Йорке или "47-380 Kamehameha Hwy, Kaneohe" на острове Кауаи (Гавайи).

Смещение местоположения

Настроить предпочтение результатов из определенной области, передав параметры location и radius. Это указывает автозаполнению мест (устаревшее), что результаты в пределах заданной области должны показываться в первую очередь. однако более отдаленные точки также могут быть включены в ответ. С помощью параметра includedRegionCodes можно отфильтровать результаты и показывать только места в определенной стране.

Ограничение местоположений

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

Вы также можете ограничить результаты регионом, заданным параметрами location и radius, добавив параметр strictbounds. В этом случае автозаполнение мест (устаревшее) будет возвращать только результаты из указанного региона.