Этот продукт имеет устаревший статус. С октября 2026 г. Places API (устаревшая версия) больше нельзя будет включить для новых проектов Google Cloud. Существующие проекты будут поддерживаться в полном объеме. Чтобы использовать новые функции и повысить производительность, перейдите на Places API (новую версию).

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

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

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

Примечание о серверных и клиентских библиотеках

Places API также доступен с клиентами Java, Python, Go и Node.js для сервисов Google Карт. Places API и клиентские библиотеки предназначены для использования в серверных приложениях.

Если вы создаете клиентское приложение, ознакомьтесь с Places SDK для Android (новая версия), Places SDK для iOS (новая версия) и библиотекой Places, Maps JavaScript API.

Query Autocomplete (устаревшая версия) позволяет предлагать варианты запросов при вводе текста в поле поиска.

Запросы к устаревшей версии сервиса автозаполнения

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

Query Autocomplete (Legacy) позволяет добавлять в приложение подсказки автозаполнения с учетом местоположения. Вместо того чтобы искать конкретное место, пользователь может ввести категорию, например "пицца в Москве", и сервис предложит список запросов, соответствующих этой строке. Поскольку функция автозаполнения запросов (устаревшая версия) может сопоставлять как полные слова, так и подстроки, приложения могут отправлять запросы по мере их ввода и сразу же предлагать похожие варианты.

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

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

где output может быть json или xml.

Для отправки запроса Query Autocomplete (Legacy) требуются определенные параметры. Параметры разделяются амперсандами (&) в соответствии со стандартом написания URL. Ниже перечислены параметры и их возможные значения.

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

ввод

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

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

language

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

Определяет точку, вокруг которой выполняется поиск, в виде координат latitude,longitude. Сервис Places использует местоположение, чтобы отдавать предпочтение результатам поиска в области, заданной параметрами location и radius. Результаты за пределами заданной области также могут быть показаны.

Параметр location может быть переопределен, если в параметре query указано точное местоположение, например Market in Barcelona. Использование кавычек в запросе также может повлиять на вес, присваиваемый location и radius.
вычесть

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

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

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

Примеры использования Query Autocomplete (Legacy)

URL

https://maps.googleapis.com/maps/api/place/queryautocomplete/json
  ?input=pizza%20near%20par
  &key=YOUR_API_KEY

curl

curl -L -X GET 'https://maps.googleapis.com/maps/api/place/queryautocomplete/json?input=pizza%20near%20par&key=YOUR_API_KEY'

Запрос "Пицца рядом с Пар" с результатами на французском языке:

URL

https://maps.googleapis.com/maps/api/place/queryautocomplete/json
  ?input=pizza%20near%20par
  &language=fr
  &key=YOUR_API_KEY

curl

curl -L -X GET 'https://maps.googleapis.com/maps/api/place/queryautocomplete/json?input=pizza%20near%20par&language=fr&key=YOUR_API_KEY'

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

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

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

URL

https://maps.googleapis.com/maps/api/place/queryautocomplete/json
  ?input=pizza%20near%20par
  &key=YOUR_API_KEY

curl

curl -L -X GET 'https://maps.googleapis.com/maps/api/place/queryautocomplete/json?input=pizza%20near%20par&key=YOUR_API_KEY'

JSON

{
  "predictions":
    [
      {
        "description": "pizza near Paris, France",
        "matched_substrings":
          [{ "length": 5, "offset": 0 }, { "length": 3, "offset": 11 }],
        "structured_formatting":
          {
            "main_text": "pizza",
            "main_text_matched_substrings": [{ "length": 5, "offset": 0 }],
            "secondary_text": "near Paris, France",
            "secondary_text_matched_substrings": [{ "length": 3, "offset": 5 }],
          },
        "terms":
          [
            { "offset": 0, "value": "pizza" },
            { "offset": 6, "value": "near" },
            { "offset": 11, "value": "Paris" },
            { "offset": 18, "value": "France" },
          ],
      },
      {
        "description": "pizza near Pari Chowk, NRI City, Omega II, Noida, Uttar Pradesh, India",
        "matched_substrings":
          [{ "length": 5, "offset": 0 }, { "length": 3, "offset": 11 }],
        "structured_formatting":
          {
            "main_text": "pizza",
            "main_text_matched_substrings": [{ "length": 5, "offset": 0 }],
            "secondary_text": "near Pari Chowk, NRI City, Omega II, Noida, Uttar Pradesh, India",
            "secondary_text_matched_substrings": [{ "length": 3, "offset": 5 }],
          },
        "terms":
          [
            { "offset": 0, "value": "pizza" },
            { "offset": 6, "value": "near" },
            { "offset": 11, "value": "Pari Chowk" },
            { "offset": 23, "value": "NRI City" },
            { "offset": 33, "value": "Omega II" },
            { "offset": 43, "value": "Noida" },
            { "offset": 50, "value": "Uttar Pradesh" },
            { "offset": 65, "value": "India" },
          ],
      },
      {
        "description": "pizza near Disneyland Park, Disneyland Drive, Anaheim, CA, USA",
        "matched_substrings":
          [{ "length": 5, "offset": 0 }, { "length": 3, "offset": 22 }],
        "structured_formatting":
          {
            "main_text": "pizza",
            "main_text_matched_substrings": [{ "length": 5, "offset": 0 }],
            "secondary_text": "near Disneyland Park, Disneyland Drive, Anaheim, CA, USA",
            "secondary_text_matched_substrings":
              [{ "length": 3, "offset": 16 }],
          },
        "terms":
          [
            { "offset": 0, "value": "pizza" },
            { "offset": 6, "value": "near" },
            { "offset": 11, "value": "Disneyland Park" },
            { "offset": 28, "value": "Disneyland Drive" },
            { "offset": 46, "value": "Anaheim" },
            { "offset": 55, "value": "CA" },
            { "offset": 59, "value": "USA" },
          ],
      },
      {
        "description": "pizza near Cathédrale Notre-Dame de Paris, Parvis Notre-Dame - place Jean-Paul-II, Paris, France",
        "matched_substrings":
          [{ "length": 5, "offset": 0 }, { "length": 3, "offset": 36 }],
        "structured_formatting":
          {
            "main_text": "pizza",
            "main_text_matched_substrings": [{ "length": 5, "offset": 0 }],
            "secondary_text": "near Cathédrale Notre-Dame de Paris, Parvis Notre-Dame - place Jean-Paul-II, Paris, France",
            "secondary_text_matched_substrings":
              [{ "length": 3, "offset": 30 }],
          },
        "terms":
          [
            { "offset": 0, "value": "pizza" },
            { "offset": 6, "value": "near" },
            { "offset": 11, "value": "Cathédrale Notre-Dame de Paris" },
            { "offset": 43, "value": "Parvis Notre-Dame - place Jean-Paul-II" },
            { "offset": 83, "value": "Paris" },
            { "offset": 90, "value": "France" },
          ],
      },
      {
        "description": "pizza near Paris Beauvais Airport, Route de l'Aéroport, Tillé, France",
        "matched_substrings":
          [{ "length": 5, "offset": 0 }, { "length": 3, "offset": 11 }],
        "structured_formatting":
          {
            "main_text": "pizza",
            "main_text_matched_substrings": [{ "length": 5, "offset": 0 }],
            "secondary_text": "near Paris Beauvais Airport, Route de l'Aéroport, Tillé, France",
            "secondary_text_matched_substrings": [{ "length": 3, "offset": 5 }],
          },
        "terms":
          [
            { "offset": 0, "value": "pizza" },
            { "offset": 6, "value": "near" },
            { "offset": 11, "value": "Paris Beauvais Airport" },
            { "offset": 35, "value": "Route de l'Aéroport" },
            { "offset": 56, "value": "Tillé" },
            { "offset": 63, "value": "France" },
          ],
      },
    ],
  "status": "OK",
}

XML

      
<AutocompletionResponse>
 <status>OK</status>
 <prediction>
  <description>pizza near Paris, France</description>
  <term>
   <value>pizza</value>
   <offset>0</offset>
  </term>
  <term>
   <value>near</value>
   <offset>6</offset>
  </term>
  <term>
   <value>Paris</value>
   <offset>11</offset>
  </term>
  <term>
   <value>France</value>
   <offset>18</offset>
  </term>
  <matched_substring>
   <offset>0</offset>
   <length>5</length>
  </matched_substring>
  <matched_substring>
   <offset>11</offset>
   <length>3</length>
  </matched_substring>
  <structured_formatting>
   <description>pizza</description>
   <subdescription>near Paris, France</subdescription>
   <description_matched_substring>
    <offset>0</offset>
    <length>5</length>
   </description_matched_substring>
   <subdescription_matched_substring>
    <offset>5</offset>
    <length>3</length>
   </subdescription_matched_substring>
  </structured_formatting>
 </prediction>
 <prediction>
  <description>pizza near Pari Chowk, NRI City, Omega II, Noida, Uttar Pradesh, India</description>
  <term>
   <value>pizza</value>
   <offset>0</offset>
  </term>
  <term>
   <value>near</value>
   <offset>6</offset>
  </term>
  <term>
   <value>Pari Chowk</value>
   <offset>11</offset>
  </term>
  <term>
   <value>NRI City</value>
   <offset>23</offset>
  </term>
  <term>
   <value>Omega II</value>
   <offset>33</offset>
  </term>
  <term>
   <value>Noida</value>
   <offset>43</offset>
  </term>
  <term>
   <value>Uttar Pradesh</value>
   <offset>50</offset>
  </term>
  <term>
   <value>India</value>
   <offset>65</offset>
  </term>
  <matched_substring>
   <offset>0</offset>
   <length>5</length>
  </matched_substring>
  <matched_substring>
   <offset>11</offset>
   <length>3</length>
  </matched_substring>
  <structured_formatting>
   <description>pizza</description>
   <subdescription>near Pari Chowk, NRI City, Omega II, Noida, Uttar Pradesh, India</subdescription>
   <description_matched_substring>
    <offset>0</offset>
    <length>5</length>
   </description_matched_substring>
   <subdescription_matched_substring>
    <offset>5</offset>
    <length>3</length>
   </subdescription_matched_substring>
  </structured_formatting>
 </prediction>
 <prediction>
  <description>pizza near Disneyland Park, Disneyland Drive, Anaheim, CA, USA</description>
  <term>
   <value>pizza</value>
   <offset>0</offset>
  </term>
  <term>
   <value>near</value>
   <offset>6</offset>
  </term>
  <term>
   <value>Disneyland Park</value>
   <offset>11</offset>
  </term>
  <term>
   <value>Disneyland Drive</value>
   <offset>28</offset>
  </term>
  <term>
   <value>Anaheim</value>
   <offset>46</offset>
  </term>
  <term>
   <value>CA</value>
   <offset>55</offset>
  </term>
  <term>
   <value>USA</value>
   <offset>59</offset>
  </term>
  <matched_substring>
   <offset>0</offset>
   <length>5</length>
  </matched_substring>
  <matched_substring>
   <offset>22</offset>
   <length>3</length>
  </matched_substring>
  <structured_formatting>
   <description>pizza</description>
   <subdescription>near Disneyland Park, Disneyland Drive, Anaheim, CA, USA</subdescription>
   <description_matched_substring>
    <offset>0</offset>
    <length>5</length>
   </description_matched_substring>
   <subdescription_matched_substring>
    <offset>16</offset>
    <length>3</length>
   </subdescription_matched_substring>
  </structured_formatting>
 </prediction>
 <prediction>
  <description>pizza near Cathédrale Notre-Dame de Paris, Parvis Notre-Dame - place Jean-Paul-II, Paris, France</description>
  <term>
   <value>pizza</value>
   <offset>0</offset>
  </term>
  <term>
   <value>near</value>
   <offset>6</offset>
  </term>
  <term>
   <value>Cathédrale Notre-Dame de Paris</value>
   <offset>11</offset>
  </term>
  <term>
   <value>Parvis Notre-Dame - place Jean-Paul-II</value>
   <offset>43</offset>
  </term>
  <term>
   <value>Paris</value>
   <offset>83</offset>
  </term>
  <term>
   <value>France</value>
   <offset>90</offset>
  </term>
  <matched_substring>
   <offset>0</offset>
   <length>5</length>
  </matched_substring>
  <matched_substring>
   <offset>36</offset>
   <length>3</length>
  </matched_substring>
  <structured_formatting>
   <description>pizza</description>
   <subdescription>near Cathédrale Notre-Dame de Paris, Parvis Notre-Dame - place Jean-Paul-II, Paris, France</subdescription>
   <description_matched_substring>
    <offset>0</offset>
    <length>5</length>
   </description_matched_substring>
   <subdescription_matched_substring>
    <offset>30</offset>
    <length>3</length>
   </subdescription_matched_substring>
  </structured_formatting>
 </prediction>
 <prediction>
  <description>pizza near Paris Beauvais Airport, Route de l'Aéroport, Tillé, France</description>
  <term>
   <value>pizza</value>
   <offset>0</offset>
  </term>
  <term>
   <value>near</value>
   <offset>6</offset>
  </term>
  <term>
   <value>Paris Beauvais Airport</value>
   <offset>11</offset>
  </term>
  <term>
   <value>Route de l'Aéroport</value>
   <offset>35</offset>
  </term>
  <term>
   <value>Tillé</value>
   <offset>56</offset>
  </term>
  <term>
   <value>France</value>
   <offset>63</offset>
  </term>
  <matched_substring>
   <offset>0</offset>
   <length>5</length>
  </matched_substring>
  <matched_substring>
   <offset>11</offset>
   <length>3</length>
  </matched_substring>
  <structured_formatting>
   <description>pizza</description>
   <subdescription>near Paris Beauvais Airport, Route de l'Aéroport, Tillé, France</subdescription>
   <description_matched_substring>
    <offset>0</offset>
    <length>5</length>
   </description_matched_substring>
   <subdescription_matched_substring>
    <offset>5</offset>
    <length>3</length>
   </subdescription_matched_substring>
  </structured_formatting>
 </prediction>
</AutocompletionResponse>

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

PlacesQueryAutocompleteResponse

Поле	Обязательно	Тип	Описание
`predictions`	Обязательно	Array<PlaceAutocompletePrediction>	Содержит массив подсказок. Подробную информацию можно найти в статье PlaceAutocompletePrediction.
`status`	Обязательно	PlacesAutocompleteStatus	Содержит статус запроса и может включать отладочную информацию, которая поможет вам понять, почему запрос не был выполнен. Дополнительную информацию можно найти в разделе PlacesAutocompleteStatus.
`error_message`	необязательно	string	Если сервис возвращает код статуса, отличный от `OK`, в объекте ответа может присутствовать дополнительное поле `error_message`. В этом поле содержится более подробная информация о причинах, по которым был присвоен тот или иной код статуса. Это поле возвращается не всегда, и его содержимое может меняться.
`info_messages`	необязательно	Array<string>	Если сервис возвращает дополнительную информацию о спецификации запроса, в объекте ответа может быть дополнительное поле `info_messages`. Это поле возвращается только для успешных запросов. Оно может возвращаться не всегда, а его содержимое может меняться.

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

Поле	Обязательно	Тип	Описание
`description`	Обязательно	string	Содержит человекочитаемое название возвращенного результата. Для результатов `establishment` обычно указывается название компании. Этот текст должен отображаться "как есть", без дополнительной программной обработки.
`matched_substrings`	Обязательно	Массив<PlaceAutocompleteMatchedSubstring>	Список подстрок, описывающих местоположение введенного термина в тексте результата прогнозирования, чтобы при необходимости можно было выделить этот термин. Дополнительную информацию можно найти в описании класса PlaceAutocompleteMatchedSubstring.
`structured_formatting`	Обязательно	PlaceAutocompleteStructuredFormat	Предоставляет предварительно отформатированный текст, который можно показывать в результатах автозаполнения. Этот текст должен отображаться "как есть", без дополнительной программной обработки. Подробнее PlaceAutocompleteStructuredFormat…
`terms`	Обязательно	Array<PlaceAutocompleteTerm>	Массив терминов, определяющих каждый раздел возвращенного описания (раздел описания обычно заканчивается запятой). Каждая запись в массиве содержит поле `value` с текстом термина и поле `offset`, определяющее начальную позицию этого термина в описании, измеряемую в символах Юникода. Дополнительную информацию можно найти в описании класса PlaceAutocompleteTerm.
`distance_meters`	необязательно	Целое число	Расстояние по прямой в метрах от исходной точки. Это поле возвращается только в запросах, сделанных с помощью `origin`.
`place_id`	необязательно	string	уникальный текстовый идентификатор места. Чтобы извлечь информацию о месте, передайте этот идентификатор в поле placeId запроса к Places API. Подробнее об идентификаторах мест…
`reference`	необязательно	string	`reference` больше не поддерживается. См. place_id.
`types`	необязательно	Array<string>	Массив типов, относящихся к этому месту. Примеры:`[ "political", "locality" ]` или `[ "establishment", "geocode", "beauty_salon" ]`. Массив может содержать несколько значений. Подробнее о типах мест…

PlaceAutocompleteMatchedSubstring

Поле	Обязательно	Тип	Описание
`length`	Обязательно	число	Длина совпадающей подстроки в тексте результата подсказки.
`offset`	Обязательно	число	Начальная позиция соответствующей подстроки в тексте результата прогноза.

PlaceAutocompleteStructuredFormat

Поле	Обязательно	Тип	Описание
`main_text`	Обязательно	string	Содержит основной текст подсказки, обычно название места.
`main_text_matched_substrings`	Обязательно	Array<PlaceAutocompleteMatchedSubstring>	Содержит массив со значением `offset` и `length`. Они описывают местоположение введенного термина в тексте результата подсказки, чтобы при желании его можно было выделить. Дополнительную информацию можно найти в описании класса PlaceAutocompleteMatchedSubstring.
`secondary_text`	необязательно	string	Содержит дополнительный текст подсказки, обычно местоположение места.
`secondary_text_matched_substrings`	необязательно	Массив<PlaceAutocompleteMatchedSubstring>	Содержит массив со значением `offset` и `length`. Они описывают местоположение введенного термина в тексте результата прогноза, чтобы при необходимости его можно было выделить. Дополнительную информацию можно найти в описании класса PlaceAutocompleteMatchedSubstring.

PlaceAutocompleteTerm

Поле	Обязательно	Тип	Описание
`offset`	Обязательно	число	Начальная позиция этого термина в описании, измеряемая в символах Юникода.
`value`	Обязательно	string	Текст термина.

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

Запросы к устаревшей версии сервиса автозаполнения

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

ввод

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

language

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

вычесть

радиус

Примеры использования Query Autocomplete (Legacy)

URL

curl

URL

curl

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

URL

curl

JSON

XML

PlacesQueryAutocompleteResponse

predictions

status

error_message

info_messages

PlacesAutocompleteStatus

PlaceAutocompletePrediction

description

matched_substrings

structured_formatting

terms

distance_meters

place_id

reference

types

PlaceAutocompleteMatchedSubstring

length

offset

PlaceAutocompleteStructuredFormat

main_text

main_text_matched_substrings

secondary_text

secondary_text_matched_substrings

PlaceAutocompleteTerm

offset

value

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

`predictions`

`status`

`error_message`

`info_messages`

`description`

`matched_substrings`

`structured_formatting`

`terms`

`distance_meters`

`place_id`

`reference`

`types`

`length`

`offset`

`main_text`

`main_text_matched_substrings`

`secondary_text`

`secondary_text_matched_substrings`

`offset`

`value`