Чтобы переводить контент на ваш предпочитаемый язык, 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 (Legacy)

Query Autocomplete (Legacy) – это часть Places API (Legacy). У них общий ключ API и квота.

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

Запрос 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, параметр radius не принимается и возвращается ошибка 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'

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

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 на собственный.

Ответ Query Autocomplete (устаревший)

Ответы Query Autocomplete (Legacy) возвращаются в формате, указанном флагом 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`	Обязательно	Массив<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`	Обязательно	Array<PlaceAutocompleteMatchedSubstring>	Список подстрок, описывающих местоположение введенного термина в тексте результата подсказки, чтобы при желании его можно было выделить. Подробную информацию можно найти в описании класса PlaceAutocompleteMatchedSubstring.
`structured_formatting`	Обязательно	PlaceAutocompleteStructuredFormat	Предоставляет предварительно отформатированный текст, который может быть показан в результатах автозаполнения. Этот текст должен отображаться "как есть", без дополнительной программной обработки. Дополнительную информацию можно найти в статье PlaceAutocompleteStructuredFormat.
`terms`	Обязательно	Array<PlaceAutocompleteTerm>	Содержит массив терминов, идентифицирующих каждый раздел возвращенного описания (раздел описания обычно заканчивается запятой). Каждый элемент массива содержит поле `value` с текстом термина и поле `offset`, определяющее начальную позицию этого термина в описании, измеряемую в символах Unicode. Дополнительную информацию можно найти в описании класса 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`	необязательно	Array<PlaceAutocompleteMatchedSubstring>	Содержит массив со значением `offset` и `length`. Они описывают местоположение введенного термина в тексте результата подсказки, чтобы при желании его можно было выделить. Подробную информацию можно найти в описании класса PlaceAutocompleteMatchedSubstring.

PlaceAutocompleteTerm

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

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

Запросы к Query Autocomplete (Legacy)

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

ввод

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

language

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

вычесть

радиус

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

URL

curl

URL

curl

Ответ Query Autocomplete (устаревший)

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`