Подсказки при вводе адреса одной строкой

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

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

Как работают подсказки для адреса

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

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

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

Чтобы всё это заработало, мы использовали здесь следующий JavaScript-код.

//готовим опции модуля
var options = { id : 'js-AddressField' };

//запускаем модуль
AhunterSuggest.Address.Solid( options );

Детальное описание этого кода, а также описание подготовки вашего сайта к использованию подсказок приводится далее в этой статье.

В большинстве случаев для работы с подсказками бывает достаточно использовать модуль ahunter_suggest.js. Однако если вам нужно встроить подсказки в отдельное приложение, либо если у вас есть своё JavaScript решение для отображения подсказок, то для получения подсказок от Ахантера нужно будет использовать напрямую его REST API. Соответствующее описание приводится во второй части данной статьи.

Как добавить подсказки для адресов на веб-сайт

Подготовка сайта для подключения подсказок

Для добавления наших подсказок на веб-сайт в первую очередь нужно подключить наш JavaScript-модуль. В хедере вашего сайта это должно выглядеть так.

<head>
...
  <script src="path_to_scripts/jquery.min.js"></script>
  <script src="path_to_scripts/ahunter_suggest.js"></script>
...
</head>

Здесь мы полагаем, что у вас на веб-сервере есть папка path_to_scripts, в которой лежат JavaScript-скрипты вашего сайта. Также мы полагаем, что в этой папке у вас уже лежит свежая версия jQuery в виде минифицированного файла jquery.min.js, а также свежая версия нашего модуля подсказок ahunter_suggest.js.

Чтобы подсказки хорошо отображались, в таблице стилей вашего сайта нужно определить следующие классы стилей.

  • u-AhunterSuggestions – данный класс присваивается контейнеру, в котором отображается список подсказок. Чтобы подсказки не сливались с основным содержимым вашего сайта, вы можете установить рамку у этого контейнера и определить ему особый цвет заливки. Например, на нашем сайте этот класс определён следующим образом:
    .u-AhunterSuggestions
    { 
      border: 1px solid #AAAAAA;
      background: white; 
      overflow: auto; 
      border-radius: 2px;
    }
  • u-AhunterSuggestion – данный класс присваивается каждой подсказке из списка подсказок. С помощью него можно управлять внешним видом подсказываемых почтовых адресов. Например, на нашем сайте этот класс определён следующим образом:
    .u-AhunterSuggestion
    { 
      padding: 5px;
      white-space: nowrap;
      overflow: hidden;
    }
  • u-AhunterEmptySuggestion – класс присваивается блоку, в котором выводится предупреждающее сообщение, когда сервис не смог предложить ни одной подсказки для тех данных, которые ввёл пользователь. Это сообщение появляется непосредственно под полем, куда вводится адрес. С помощью этого класса можно придать данному сообщению особый внешний вид, чтобы пользователь обратил на него внимание. Например, на нашем сайте этот класс определён следующим образом:
    .u-AhunterEmptySuggestion
    {
      padding: 5px;  
      font-style: italic;
      color: #b8661f;
    }
  • u-AhunterSelectedSuggestion – данный класс присваивается той подсказке, которую в настоящий момент выбрал пользователь. Когда пользователь двигается по списку предложенных подсказок с помощью стрелок на клавиатуре, происходит подсветка выбранной в настоящий момент подсказки. Чтобы выделить её как-то на фоне остальных подсказок, предусмотрен данный класс. У нас на сайте он определён так:
    .u-AhunterSelectedSuggestion   
    { 
      background: #E7E7E7; 
    }
  • u-AhunterSuggestions strong – этот селектор устанавливает на HTML-элемент strong особое оформление для той части каждой подсказки, которая совпала с введённым текстом. Например, если пользователь ввёл Мос и в подсказке отображается г Москва, то с помощью данного стиля можно отображать подсказку вот так г Москва, чтобы первые буквы подсказки были выделены особым образом. Мы на нашем сайте используем следующий стиль для этого.
    .u-AhunterSuggestions strong  
    { 
      font-weight: bold; 
      color: #1B7BB1; 
    }

Подключение подсказок на сайте

Чтобы запустить подсказки, на вашем сайте также должна присутствовать форма с полем для ввода почтового адреса. Этому полю должен быть присвоен идентификатор, чтобы по нему наш модуль ahunter_suggest.js смог найти это поле на странице и запустить для него подсказки. Например, в простейшем случае HTML-разметка с таким полем может иметь следующий вид.

<div>
  <input id="js-AddressField" placeholder="Введите адрес">  
</div>

Теперь, чтобы запустить подсказки, достаточно где-нибудь на странице добавить следующий инициализирующий скрипт:

<script>
  
  //готовим настройки модуля
  var options = { id : 'js-AddressField' };

  //запускаем модуль подсказок
  AhunterSuggest.Address.Solid( options );
  
</script>

Здесь выполняется заполнение опций options, которые затем передаются модулю подсказок посредством вызова AhunterSuggest.Address.Solid( options ). Этот вызов привяжет функционал подсказок к полю с идентификатором js-AddressField, после чего ввод почтовых адресов в этом поле будет приводить к отображению подсказок.

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

Опции модуля подсказок

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

Для адреса, вводимого в одно поле, в опциях объекта options {...} можно передавать следующие параметры.

  • id – обязательный строковый параметр, должен содержать идентификатор HTML-элемента, в который будет вводиться почтовый адрес и для которого нужно будет формировать подсказки.
  • ahunter_url – полный веб-адрес нашего сервиса. По умолчанию используется https://ahunter.ru/. Если вы используете подсказки с коробочной версией сервиса, развёрнутого на вашем сервере, то с помощью этого параметра нужно будет указать реальный веб-адрес, по которому доступен именно ваш сервер.
  • empty_msg – строка с сообщением, которое будет отображаться в том случае, если наш сервис не вернул подходящих подсказок для вводимых в настоящий момент данных. По умолчанию используется такой текст: "Нет подходящей подсказки". Чтобы отключить вывод данного сообщения, нужно в качестве значения явно передать пустую строку, например, так:
      var options = 
      { 
        ..., 
        empty_msg : '', 
        ... 
      };
  • limit – число, с помощью которого задаётся количество подсказок, возвращаемых сервисом. По умолчанию используется значение 10, это соответствует лимиту, установленному на стороне сервиса. Больше этого количества подсказок сервис не предложит, однако параметр limit позволяет запросить меньшее их число. Например, если вам покажется, что 10 подсказок – это слишком много для вашего сайта.
  • suggest_on_focus – флаг булевского типа, если выставлен в true, то при возврате фокуса в поле ввода подсказки будут автоматически предлагаться, не дожидаясь нового ввода от пользователя, при условии что поле ввода не пусто. По умолчанию имеет значение true.
  • z_index – значение css-свойства z-index, устанавливаемое у контейнера с подсказками.
  • max_height – значение css-свойства max-height, устанавливаемое у контейнера с подсказками.
  • on_fetch – ваша колбэк-функция, которую будет вызывать наш модуль, когда пользователь акцентированно выберет предложенную подсказку. Акцентированный выбор происходит, когда пользователь выделяет подсказку в предложенном списке и нажимает клавишу Enter, либо когда пользователь щёлкает мышкой по предложенной подсказке. В это случае наш модуль асинхронно отправит на сервис API-команду fetch/address, чтобы получить по выбранному в подсказке адресу полные сведения (коды по справочникам, координаты и др.), после чего вызовет ваш колбэк on_fetch и передаст ему в качестве аргументов два следующих объекта:
    • Suggestion - выбранная пользователем подсказка. Состав полей данного объекта описан ниже в данной статье в описании REST API.
    • Address - соответствующий выбранной подсказке структурированный почтовый адрес. Состав полей данного объекта можно посмотреть в описании команды fetch/address здесь.
    Опцию on_fetch и соответствующий ей функционал можно использовать только совместно с параметром user, подтверждающим, что у вас есть действующий аккаунт на нашем сервисе.
  • on_fetch_context – объект, который будет выступать в роли this-контекста при вызове колбэка on_fetch.
  • user – открытый API-токен из личного кабинета, передаваемый сервису при выполнении колбэка on_fetch. С помощью данного токена сервис идентифицирует ваш аккаунт, чтобы корректно выполнить on_fetch. Данную опцию следует использовать, только если вы планируете получать дополнительные сведения о выбранной подсказке с помощью вызова on_fetch.

Пример запуска подсказок с разными опциями

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

//Готовим опции для модуля подсказок
var options = 
{ 
  //Наше поле, куда пользователи будут вводить почтовые адреса
  id: "js-AddressField",

  //Веб-адрес облачной версии сервиса
  ahunter_url : "https://ahunter.ru/",

  //Не будем показывать предупреждающее сообщение, когда подсказок нет
  empty_msg : "",

  //Будем показывать только 5 топовых подсказок
  limit : 5,
  
  //Не будем показывать подсказки при возврате фокуса в поле ввода
  suggest_on_focus : false,

  //При выборе подсказки будем выводить её в отладочную консоль
  on_fetch : function( Suggestion, Address ) 
  {
    console.log( Suggestion, Address );
  },
  
  //Указываем свой открытый API-токен, чтобы работал on_fetch
  user : "demotoken"
};

//Запускаем модуль подсказок
AhunterSuggest.Address.Solid( options );

После выполнения этой инициализации всякий раз, когда пользователи будут вводить адреса в поле js-AddressField, на экране будут появляться подсказки с подходящими почтовыми адресами.

REST API подсказок для почтовых адресов

Если вам нужно встроить подсказки для почтовых адресов не на веб-сайте, а в ваше приложение, либо если вы по каким-то причинам не можете подключить наш JavaScript-модуль подсказок ahunter_suggest.js, то в этом случае вам следует напрямую использовать API-команду suggest/address нашего сервиса для запроса и получения подсказок для вводимого пользователем почтового адреса.

Принципы использования API подсказок при вводе адреса

Использование команды suggest/address полагает, что адрес вводится пользователем в режиме реального времени. Каждый раз, когда пользователь вводит очередной символ целевого почтового адреса, увеличивается количество информации, на основе которой сервис может сформировать подсказки для остальной части адреса.

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

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

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

После того, как пользователь выбрал подходящую подсказку, ваше приложение может запросить у Ахантера полную информацию об этом адресе, например, его географические координаты или коды по справочникам ФИАС и КЛАДР. Для этого каждая подсказка снабжается уникальным идентификатором-сигнатурой. Когда пользователь вашего приложения выбирает подсказку, ваше приложение может брать соответствующую ей сигнатуру и отсылать её с помощью команды fetch/address. В качестве ответа сервис вернёт структурированный адрес с полной информацией о нём.

Пример простого запроса подсказок

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

http://ahunter.ru/site/suggest/address?output=json;query=%D0%BC%D0%BE%D1%81

В данном запросе используются следующие параметры.

  • output=json - сообщает сервису о том, что необходимо вернуть ответ в формате JSON.
  • query=%D0%BC%D0%BE%D1%81 - закодированный с использованием URL-encoding фрагмент введенного адреса "мос" в кодировке UTF-8, для которого необходимо получить подсказки.

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

Параметры команды

Обязательные параметры для выполнения запроса.

  • http://ahunter.ru/site/suggest/address - URL-команды.
  • output=json или output=xml - формат, в котором требуется вернуть результат выполнения команды.
  • query=строка запроса - строка, содержащая фрагмент введенного адреса, для которого требуется получить подсказки.

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

  • output=pretty - опция, применимая только в случае использования JSON формата ответа сервиса. Данная опция требует, чтобы сервис выполнил "красивое" форматирование возвращаемого JSON текста, расставив в нем переносы строк, отступы и пробельное прореживание. Опция может быть полезна при отладке взаимодействия пользовательского приложения с сервисом.
  • output=cp1251 - опция применима только в случае использования XML формата ответа сервиса. Данная опция требует, чтобы сервис вернул XML-ответ в кодировке windows-1251.
  • input=utf8 или input=cp1251 - кодировка UTF-8 или windows-1251, в которой представлены входные данные в параметре query.
  • addresslim=число - лимит на число возвращаемых подсказок адреса. Если данное значение превышает допустимый порог, установленный администратором сервиса, то данное значение будет принудительно уменьшено до этого допустимого порога. Если в запросе данный параметр не указан, то в качестве лимита будет выступать некоторое умолчальное значение, установленное администратором сервиса.

Пример запроса подсказок с дополнительными опциями

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

http://ahunter.ru/site/suggest/address?addresslim=3;output=json|pretty;query=%D0%BC%D0%BE%D1%81%D0%BA%D0%B2%D0%B0%20%D1%83%D0%BB

В данном запросе используются следующие параметры.

  • output=json|pretty - сообщает сервису о том, что необходимо вернуть ответ в формате JSON, отформатировав его "красиво".
  • addresslim=3 - сообщает сервису, что следует вернуть только три наиболее подходящие подсказки для вводимого адреса.
  • query=%D0%BC%D0%BE%D1%81%D0%BA%D0%B2%D0%B0%20%D1%83%D0%BB - закодированный с использованием URL-encoding исходный фрагмент адреса "москва ул", по которому сервис должен сформировать подсказки.

Результат запроса: подсказки адреса в формате JSON

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

Результирующий JSON-ответ получен с использованием опции output=json|pretty, позволяющей выполнить "красивое" форматирование JSON-текста.

{
  "query" : "ангарск ул Б",
  "request_process_time" : 0,
  "suggestions" : [
    {
      "value" : "обл Иркутская, г Ангарск, ул Бабушкина, ",
      "sign" : "38c4s65526",
      "zip" : "665809"
    },
    {
      "value" : "обл Иркутская, г Ангарск, ул Баумана, ",
      "sign" : "38c4s65527",
      "zip" : "665809"
    },
    {
      "value" : "обл Иркутская, г Ангарск, ул Белорусская, ",
      "sign" : "38c4s65523",
      "zip" : "665809"
    },
    {
      "value" : "обл Иркутская, г Ангарск, ул Береговая, ",
      "sign" : "38c4s65524",
      "zip" : "665806"
    },
    {
      "value" : "обл Иркутская, г Ангарск, ул Блудова, ",
      "sign" : "38c4s336",
      "zip" : "665826"
    },
    {
      "value" : "обл Иркутская, г Ангарск, ул Боткина, ",
      "sign" : "38c4s274",
      "zip" : "665821"
    },
    {
      "value" : "обл Иркутская, г Ангарск, ул Бульварная, ",
      "sign" : "38c4s113",
      "zip" : "665824"
    },
    {
      "value" : "обл Иркутская, г Ангарск, ул Богдана Хмельницкого, ",
      "sign" : "38c4s264",
      "zip" : "665821"
    },
    {
      "value" : "обл Иркутская, г Ангарск, мкр Байкальск, ул Боткина, ",
      "sign" : "38c4p1s9",
      "zip" : "665821"
    }
  ]
}

Результатом формирования подсказок для вводимого адреса является JSON-объект со следующими элементами.

  • suggestions - массив с вариантами подсказок для обработанного запроса.
  • query - строка, содержащая исходный обработанный запрос.
  • request_process_time - время обработки всего запроса в целом в миллисекундах.

Ниже приведено детальное описание этих элементов.

JSON-массив suggestions

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

Пример JSON-объекта, соответствующего одному варианту подсказок для вводимого адреса приведен ниже.

    {
      "value" : "обл Иркутская, г Ангарск, ул Бабушкина, ",
      "sign" : "38c4s65526",
      "zip" : "665809"
    }

Каждый элемент массива suggestions представляет собой JSON-объект со следующими элементами.

  • value - строка, содержащая вариант полного написания предлагаемого адреса в рамках данной подсказки в стандартизованном "красивом" виде. Адрес, предлагаемый сервисом в этой строке, записывается, начиная с поля региона и заканчивая названием улицы. Адресные поля в этой строке разделяются запятой.
  • sign - строка, содержащая сигнатуру адреса. Сигнатуру следует рассматривать как уникальный идентификатор адреса, по которому можно получить полную информацию с помощью команды fetch/address.
  • zip - строка, содержащая почтовый индекс адреса.

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

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

В случае если пользователь ввёл адрес самостоятельно без выбора предложенной подсказки, то полную информацию о таком адресе можно получить с помощью команды cleanse/address.

Результат запроса: подсказки адреса в формате XML

Здесь и далее приводится описание ответа сервиса в случае использования формата XML. По существу возвращаемые в XML-ответе элементы имеют аналогичное назначение JSON-элементам, описанным выше. Для получения ответа в формате XML необходимо в исходном запросе использовать значение параметра output=xml.

XML-ответ сервиса в результате формирования подсказок по фрагменту адреса "ангарск ул Б" имеет следующий вид.

<ProcessSuggestResult>
  <Suggestion val="обл Иркутская, г Ангарск, ул Бабушкина, " 
              zip="665809" 
              sign="38c4s65526"/>
  <Suggestion val="обл Иркутская, г Ангарск, ул Баумана, "
              zip="665809" 
              sign="38c4s65527"/>
  <Suggestion val="обл Иркутская, г Ангарск, ул Белорусская, "
              zip="665809" 
              sign="38c4s65523"/>
  <Suggestion val="обл Иркутская, г Ангарск, ул Береговая, "
              zip="665806" 
              sign="38c4s65524"/>
  <Suggestion val="обл Иркутская, г Ангарск, ул Блудова, "
              zip="665826" 
              sign="38c4s336"/>  
  <Suggestion val="обл Иркутская, г Ангарск, ул Боткина, "
              zip="665821" 
              sign="38c4s274"/>
  <Suggestion val="обл Иркутская, г Ангарск, ул Бульварная, "
              zip="665824" 
              sign="38c4s113"/>
  <Suggestion val="обл Иркутская, г Ангарск, ул Богдана Хмельницкого, "
              zip="665821" 
              sign="38c4s264"/>
  <Suggestion val="обл Иркутская, г Ангарск, мкр Байкальск, ул Боткина, "
              zip="665821" 
              sign="38c4p1s9"/>
  <Query val="ангарск ул Б"/>
</ProcessSuggestResult>

Результатом формирования подсказок для вводимого адреса является XML-документ со следующими дочерними элементами.

  • Suggestion - данный XML-элемент соответствует одному из предложенных сервисом вариантов завершения вводимого адреса. Поскольку в результате формирования подсказок, как правило, возникает несколько вариантов завершения адреса, в XML-ответе может присутствовать несколько элементов Suggestion, каждый из которых соответствует одному из предложенных сервисом вариантов. Список из всех XML-элементов Suggestion является аналогом JSON-массива suggestions, возвращаемого в JSON-ответе сервиса.
  • Query - данный XML-элемент содержит обработанную строку запроса. Эта строка передается с помощью атрибута val этого XML-элемента. Данный элемент является полным аналогом JSON-элемента query, возвращаемого в JSON-ответе сервиса.

Ниже приведено детальное описание этих XML-элементов.

XML-элемент Suggestion

Элемент Suggestion содержит информацию об одной подсказке из предложенного сервисом перечня подсказок по вводимому адресу. Пример данного элемента приведен ниже.

  <Suggestion val="обл Иркутская, г Ангарск, ул Бабушкина, " 
              zip="665809" 
              sign="38c4s65526"/>

Данный элемент содержит следующие атрибуты.

  • val - содержит вариант полного написания предлагаемого в рамках данной подсказки адреса в стандартизованном "красивом" виде. Данный атрибут является аналогом JSON-элемента value в составе JSON-объекта массива suggestions.
  • sign – содержит сигнатуру адреса, предлагаемого данной подсказкой. Данный атрибут является аналогом JSON-элемента sign в составе JSON-объекта массива suggestions.
  • zip – содержит почтовый индекс адреса.
версия сервиса:
© ixLab, 2007-2018, e-mail: info@ixlab.ru
обработано за 4 (мс)