Подсказки мест

Google Places API Web Service предназначена для серверных приложений. Если вы создаете клиентское приложение, в этом вам помогут Google Places API for Android и Библиотека адресов в Google Maps JavaScript API.



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

  1. Запросы подсказок мест
    1. Предпочтение местоположений
    2. Типы мест
    3. Примеры запросов подсказок
  2. Ответы на запросы подсказок мест
    1. Коды состояния
    2. Сообщения об ошибках
    3. Результаты запросов подсказок

Запросы подсказок мест

Служба автозаполнения входит в состав веб-службы Google Places API Web Service. При работе с ней используется тот же ключ API, а все обращения учитываются в общей квоте Google Places API Web Service.

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

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

Запрос подсказок мест – это URL-адрес в формате HTTP, который выглядит следующим образом:

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

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

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

Чтобы инициировать запрос подсказок, необходимо указать определенные параметры. Все параметры разделяются амперсандами (&) в соответствии со стандартом URL-адресов. Ниже приведен список параметров и их возможные значения.

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

  • input – текстовая строка, по которой выполняется поиск. Служба подсказки мест возвращает подходящие варианты на основе этой строки. Результаты будут отсортированы по релевантности.
  • key – ключ API вашего приложения. Этот ключ используется для идентификации приложения в целях управления квотами. Выбрать проект API и получить ключ можно в Google Developers Console. Пользователи Google Maps API for Work должны использовать проект API, созданный при подписке на Google Places API for Work.

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

  • offset – положение символа в поисковом запросе, ограничивающего текст для поиска. Так, если введен текст "Google", а для параметра offset указано значение 3, подбор вариантов будет выполняться по запросу "Goo". Параметр offset применяется только к первому слову введенного запроса. Например, если введен текст "Google abc", а для параметра offset указано значение 3, подбор вариантов будет выполняться по запросу "Goo abc". Если значение параметра offset не указано, служба будет использовать все условие для поиска. Как правило, значение offset должно соответствовать положению текстового курсора.
  • location – точка, в окрестностях которой следует вести поиск информации о местах. Должны быть указаны ее координаты в формате: широта,долгота.
  • radius – расстояние в метрах, в пределах которого должны находиться найденные результаты. Следует учитывать, что при добавлении параметра radius предпочтение отдается результатам в указанной области, но поскольку строгое ограничение отсутствует, могут отображаться результаты и за ее пределами. См. дополнительную информацию в разделе Предпочтение местоположений ниже.
  • language – язык, на котором выводятся результаты. См. список поддерживаемых языков. Обратите внимание, что список языков постоянно пополняется, поэтому он может быть неполным. Если язык не указан, служба подсказки мест будет использовать базовый язык домена, из которого отправлен запрос.
  • types – типы мест в возвращаемых результатах. См. раздел Типы мест ниже. Если тип не указан, будут возвращены все типы.
  • components – группа мест, ограничивающая результаты поиска. Пока в качестве значений параметра components можно указывать только страны (в виде двухбуквенного кода по стандарту ISO 3166-1 Alpha-2). Значение components=country:ru ограничит область поиска местами из России.

Предпочтение местоположений

Если задать параметры location и radius, предпочтения в подсказке будут отдаваться местам из указанной области, однако более отдаленные точки также могут быть предложены пользователю. Чтобы оставить только места из определенной страны, используйте параметр components.

Совет. Поскольку организации обычно имеют невысокий рейтинг, они могут не отображаться в результатах поиска по большой области. Поэтому при смешанном поиске организаций и адресов указывайте меньший радиус или используйте параметр types=establishment, чтобы ограничить результаты поиска только организациями.

Типы мест

Чтобы получать в подсказках места только определенного типа, используйте параметр types. Задайте в качестве его значения конкретный тип или групповое указание типа из числа перечисленных ниже. Если опустить этот параметр, в результатах поиска возвращаются все типы. Обычно разрешается только один тип. Исключение составляют типы geocode и establishment, которые можно указывать вместе, однако это равносильно отсутствию указанных типов. Поддерживаются следующие типы:

  • geocode – ограничивает результаты поиска геокодами. Обычно такой запрос используется, когда существуют места с похожими адресами и требуется уточнить результаты.
  • address – ограничивает результаты поиска геокодами с точными адресами. Обычно такой запрос используется, если вы знаете, что пользователь будет искать полный адрес.
  • establishment – ограничивает результаты поиска организациями.
  • (regions) – групповое указание типа, которое ограничивает результаты поиска местами, соответствующими указанным ниже типам:
    • locality,
    • sublocality,
    • postal_code,
    • country,
    • administrative_area_level_1,
    • administrative_area_level_2.
  • (cities) – групповое указание типа, которое ограничивает результаты поиска местами с заданным значением locality или administrative_area_level_3.

Примеры запросов подсказок

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

https://maps.googleapis.com/maps/api/place/autocomplete/xml?input=Amoeba&types=establishment&location=37.76999,-122.44696&radius=500&key=YOUR_API_KEY

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

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

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

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

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

Ответы на запросы подсказок мест

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

input=Paris&types=geocode

JSON
{
  "status": "OK",
  "predictions" : [
      {
         "description" : "Paris, France",
         "id" : "691b237b0322f28988f3ce03e321ff72a12167fd",
         "matched_substrings" : [
            {
               "length" : 5,
               "offset" : 0
            }
         ],
         "place_id" : "ChIJD7fiBh9u5kcRYJSMaMOCCwQ",
         "reference" : "CjQlAAAA_KB6EEceSTfkteSSF6U0pvumHCoLUboRcDlAH05N1pZJLmOQbYmboEi0SwXBSoI2EhAhj249tFDCVh4R-PXZkPK8GhTBmp_6_lWljaf1joVs1SH2ttB_tw",
         "terms" : [
            {
               "offset" : 0,
               "value" : "Paris"
            },
            {
               "offset" : 7,
               "value" : "France"
            }
         ],
         "types" : [ "locality", "political", "geocode" ]
      },
      {
         "description" : "Paris Avenue, Earlwood, New South Wales, Australia",
         "id" : "359a75f8beff14b1c94f3d42c2aabfac2afbabad",
         "matched_substrings" : [
            {
               "length" : 5,
               "offset" : 0
            }
         ],
         "place_id" : "ChIJrU3KAHG6EmsR5Uwfrk7azrI",
         "reference" : "CkQ2AAAARbzLE-tsSQPgwv8JKBaVtbjY48kInQo9tny0k07FOYb3Z_z_yDTFhQB_Ehpu-IKhvj8Msdb1rJlX7xMr9kfOVRIQVuL4tOtx9L7U8pC0Zx5bLBoUTFbw9R2lTn_EuBayhDvugt8T0Oo",
         "terms" : [
            {
               "offset" : 0,
               "value" : "Paris Avenue"
            },
            {
               "offset" : 14,
               "value" : "Earlwood"
            },
            {
               "offset" : 24,
               "value" : "New South Wales"
            },
            {
               "offset" : 41,
               "value" : "Australia"
            }
         ],
         "types" : [ "route", "geocode" ]
      },
      {
         "description" : "Paris Street, Carlton, New South Wales, Australia",
         "id" : "bee539812eeda477dad282bcc8310758fb31d64d",
         "matched_substrings" : [
            {
               "length" : 5,
               "offset" : 0
            }
         ],
         "place_id" : "ChIJCfeffMi5EmsRp7ykjcnb3VY",
         "reference" : "CkQ1AAAAAERlxMXkaNPLDxUJFLm4xkzX_h8I49HvGPvmtZjlYSVWp9yUhQSwfsdveHV0yhzYki3nguTBTVX2NzmJDukq9RIQNcoFTuz642b4LIzmLgcr5RoUrZhuNqnFHegHsAjtoUUjmhy4_rA",
         "terms" : [
            {
               "offset" : 0,
               "value" : "Paris Street"
            },
            {
               "offset" : 14,
               "value" : "Carlton"
            },
            {
               "offset" : 23,
               "value" : "New South Wales"
            },
            {
               "offset" : 40,
               "value" : "Australia"
            }
         ],
         "types" : [ "route", "geocode" ]
      },
  ...additional results ...
      
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>
  <place_id>ChIJD7fiBh9u5kcRYJSMaMOCCwQ</place_id>
  <reference>CiQRAAAAJm0CiCHIC8C4GOjREdm3QtHYhMyFaUXKWAbGSaZImQ8SECnHAhpcuZaoSr0_TKfeHvwaFHMIq_BmUccTC4mt6EWVNMa67Xuq</reference>
  <id>691b237b0322f28988f3ce03e321ff72a12167fd</id>
  <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>
 </prediction>
 <prediction>
  <description>Paris, TX, United States</description>
  <type>colloquial_area</type>
  <type>political</type>
  <type>geocode</type>
  <place_id>ChIJrU3KAHG6EmsR5Uwfrk7azrI</place_id>
  <reference>CiQcAAAArNRoGmiHh0PNVH5LSnJEbT5L7DfUE-APvTfYac9Ta5USEIfAOzXTkqTpioZX9qeevY8aFPgN_H6qcRnGLqPUq4zkOE-_g-ul</reference>
  <id>029556239a911839382f42ec36c5ce2b85be9be3</id>
  <term>
   <value>Paris</value>
   <offset>0</offset>
  </term>
  <term>
   <value>TX</value>
   <offset>7</offset>
  </term>
  <term>
   <value>United States</value>
   <offset>11</offset>
  </term>
  <matched_substring>
   <offset>0</offset>
   <length>5</length>
  </matched_substring>
 </prediction>
 <prediction>
  <description>Paris, Ontario, Canada</description>
  <type>locality</type>
  <type>political</type>
  <type>geocode</type>
  <place_id>ChIJCfeffMi5EmsRp7ykjcnb3VY</place_id>
  <reference>CiQaAAAApuD3Th6N5_EcJjKw0umu_IonagFPBo9idTf7WB8-cw8SEGS5wSvHzhuUvCqPH-uM5B8aFIedLGNSuh5M5eqWdBJCtc0Ibvd0</reference>
  <id>e7ac9c89d4a590305242b0cb5bf43064027223c9</id>
  <term>
   <value>Paris</value>
   <offset>0</offset>
  </term>
  <term>
   <value>Ontario</value>
   <offset>7</offset>
  </term>
  <term>
   <value>Canada</value>
   <offset>16</offset>
  </term>
  <matched_substring>
   <offset>0</offset>
   <length>5</length>
  </matched_substring>
 </prediction>
</AutocompletionResponse>

Ответ в формате JSON содержит два корневых элемента:

  • status – содержит метаданные по запросу. См. раздел Коды состояния ниже.
  • predictions – содержит массив названий мест с информацией о каждом из них. Подробную информацию об этих результатах см. в разделе Результаты запросов подсказок. Google Places API Web Service возвращает до 5 результатов.

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

Подробную информацию о синтаксическом анализе ответов в формате JSON см. в разделе Обработка JSON с помощью JavaScript.

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

  • Отдельный элемент <status>, содержащий метаданные по запросу. См. раздел Коды состояния ниже.
  • Несколько (или ни одного) элементов <prediction>, каждый из которых содержит информацию об одном месте. Подробную информацию об этих результатах см. в разделе Результаты запросов подсказок. Google Places API Web Service возвращает до 5 результатов.

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

Коды состояния

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

  • OK – ошибок нет, получен хотя бы один результат.
  • ZERO_RESULTS – поиск выполнен, результатов не найдено. Такое может произойти, если для поиска были переданы границы (bounds) отдаленной области.
  • OVER_QUERY_LIMIT – превышена квота.
  • REQUEST_DENIED – означает, что запрос отклонен, как правило, из-за отсутствия или неверного значения параметра key.
  • INVALID_REQUEST – обычно означает, что отсутствует параметр input.

Сообщения об ошибках

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

Результаты запросов подсказок

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

В каждом результате-подсказке имеются следующие поля.

  • description – содержит удобочитаемое название результата. Для результатов в категории establishment обычно используется название компании.
  • place_id – уникальный текстовый идентификатор места. Чтобы извлечь информацию о месте, передайте этот идентификатор в поле placeid запроса Google Places API Web Service. Подробные сведения об идентификаторах мест см. в соответствующем обзоре.
  • reference – содержит уникальный токен, который можно использовать для получения дополнительной информации в запросе данных о месте. Хотя токен однозначно определяет место, обратное утверждение неверно. Место может иметь несколько токенов с действительными ссылками. Мы не гарантируем, что в результате выполнения различных поисковых запросов для одного и того же места всегда будет возвращен один и тот же токен. Примечание. Вместо параметра reference рекомендуется использовать place_id. См. уведомление о прекращении использования на этой странице.
  • id – содержит уникальный постоянный идентификатор места. Этот идентификатор не позволяет получить информацию о месте, но с его помощью можно объединять данные об этом месте и распознавать его в разных поисковых запросах. Примечание. Вместо параметра id рекомендуется использовать place_id. См. уведомление о прекращении использования на этой странице.
  • terms – содержит массив поисковых слов, определяющих каждый раздел показанного описания. Разделы описания обычно разделяются запятыми. У каждой записи в массиве есть поле value, в котором содержится текст условия, а также поле offset, определяющее начальное положение этого условия в описании (измеряется в символах Unicode).
  • types – содержит массив типов, к которым относится это место. Например: [ "political", "locality" ] или [ "establishment", "geocode" ].
  • matched_substring – содержит значение параметров offset и length. Они описывают местоположение введенного поискового слова в тексте результата-подсказки. Это позволяет при необходимости выделить его.

Параметр sensor

Ранее запросы Google Places API Web Service обязательно должны были содержать параметр sensor, чтобы указать, использовался ли приложением датчик для определения местоположения пользователя. Этот параметр больше не используется.

Оставить отзыв о...

Текущей странице
Google Places API Web Service
Google Places API Web Service