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

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

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

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

Для визуализации предлагаемых сервисом подсказок здесь используется популярный jQuery-плагин jQuery-Autocomplete, доступный по следующей ссылке: https://github.com/devbridge/jQuery-Autocomplete. Для использования данного плагина с нашим сервисом следует использовать следующий инициализирующий JavaScript код.

//настраиваем плагин для работы с нашим сервисом
var options = { 
                serviceUrl:'http://ahunter.ru/site/suggest/address',
                params: { output: "json" },
                noCache: true,
                triggerSelectOnValidInput: false,
                paramName: "query",
                maxHeight: 500
              };

//запускаем плагин, 
//селектор '#js-Field' соответствует полю, где вводится адрес
$('#js-Field').autocomplete( options );

API нашего сервиса не ограничивает пользователя в выборе средств визуализации подсказок. Вместо jQuery-Autocomplete может быть использован любой GUI фреймоворк, в составе которого присутствуют компоненты для организации автоматического дополнения при заполнении форм ввода.

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

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

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

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

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

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

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

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" : "обл Иркутская, г Ангарск, ул Бабушкина, "
    },
    {
      "value" : "обл Иркутская, г Ангарск, ул Баумана, "
    },
    {
      "value" : "обл Иркутская, г Ангарск, ул Белорусская, "
    },
    {
      "value" : "обл Иркутская, г Ангарск, ул Береговая, "
    },
    {
      "value" : "обл Иркутская, г Ангарск, ул Блудова, "
    },
    {
      "value" : "обл Иркутская, г Ангарск, ул Боткина, "
    },
    {
      "value" : "обл Иркутская, г Ангарск, ул Бульварная, "
    },
    {
      "value" : "обл Иркутская, г Ангарск, ул Богдана Хмельницкого, "
    },
    {
      "value" : "обл Иркутская, г Ангарск, мкр Байкальск, ул Боткина, "
    }
  ]
}

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

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

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

JSON-массив suggestions

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

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

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

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

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

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

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

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

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

<ProcessSuggestResult>
  <Suggestion val="обл Иркутская, г Ангарск, ул Бабушкина, "/>
  <Suggestion val="обл Иркутская, г Ангарск, ул Баумана, "/>
  <Suggestion val="обл Иркутская, г Ангарск, ул Белорусская, "/>
  <Suggestion val="обл Иркутская, г Ангарск, ул Береговая, "/>
  <Suggestion val="обл Иркутская, г Ангарск, ул Блудова, "/>
  <Suggestion val="обл Иркутская, г Ангарск, ул Боткина, "/>
  <Suggestion val="обл Иркутская, г Ангарск, ул Бульварная, "/>
  <Suggestion val="обл Иркутская, г Ангарск, ул Богдана Хмельницкого, "/>
  <Suggestion val="обл Иркутская, г Ангарск, мкр Байкальск, ул Боткина, "/>
  <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="обл Иркутская, г Ангарск, ул Бабушкина, "/>

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

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