Дискретные подсказки для адреса
Команда fetch/address позволяет получить информацию об адресе, который ранее был обработан сервисом, например, с помощью команды стандартизации cleanse/address, или с помощью команды формирования подсказок suggest/address. В обоих случаях сервис возвращает уникальную сигнатуру почтового адреса, по которой можно запросить всю необходимую информацию о нём с помощью команды fetch/address.
Применительно к ранее стандартизованному адресу использование данной команды позволяет получить свежие сведения о нём, такие как географические координаты или коды по справочникам ФИАС, КЛАДР, ОКАТО и ОКТМО. Это может быть востребовано, если с момента стандартизации адреса прошло достаточно много времени, так что ранее полученная информация могла потерять актуальность.
При формировании подсказок пользователю также может потребоваться дополнительная информация о введённом адресе, например, почтовый индекс. Также может возникнуть необходимость представить адрес не в виде одной строки, каким он отображается при вводе, а в виде структуры с разбивкой на отдельные адресные поля. Все эти сведения не отображаются в подсказках непосредственно при его вводе, однако каждый подсказанный адрес снабжается сигнатурой, по которой уже после выбора подсказанного адреса можно получить всю необходимую информацию.
Использование данной команды совместно с подсказками подразумевает следующий сценарий. Пользователь вводит почтовый адрес в некоторой форме в вашем приложении или на сайте. В процессе этого ввода ему предлагаются подсказки, из которых он может выбрать подходящий адрес.
Каждая подсказка, возвращаемая сервисом, кроме непосредственно подсказываемого адреса снабжается уникальной сигнатурой, которая не отображается пользователю, но при этом доступна вашему сайту или приложению. Когда пользователь выбирает подходящую подсказку, приложение или сайт может запоминать соответствующую данной подсказке сигнатуру и использовать её в команде fetch/address для получения от сервиса полного комплекта сведений о выбранном адресе.
Приведённая ниже форма демонстрирует данный сценарий. В поле для ввода адреса нужно ввести какой-нибудь адрес и выбрать предложенный сервисом вариант подсказки. Выбранную подсказку нужно подвердить, нажав Enter, либо щёлкнув по ней мышкой.
Для отображения подсказок здесь используется jQuery-плагин jQuery-Autocomplete, доступный по следующей ссылке: https://github.com/devbridge/jQuery-Autocomplete. Для использования данного плагина в связке с командой fetch/address можно использовать следующий инициализирующий JavaScript код
//настраиваем плагин подсказок для работы с нашим сервисом var options = { serviceUrl:'https://ahunter.ru/site/suggest/address', params: { output: 'json' }, noCache: true, triggerSelectOnValidInput: false, paramName: "query", maxHeight: 500, //при выборе подсказки будем вызывать команду fetch/address onSelect: function( Suggestion ) { //вызываем fetch/address через ajax $.ajax( { //в query передаём сигнатуру адреса, полученную в подсказках data: { query : Suggestion.sign }, url: 'https://ahunter.ru/site/fetch/address?output=json', dataType: 'json', success : function( Response ) { //получили в Response стандартизованный почтовый адрес, //теперь можно использовать его по назначению ... alert( JSON.stringify( Response ) ); ... } } ); } }; //запускаем плагин, //селектор '#js-Field' соответствует полю, где вводится адрес $('#js-Field').autocomplete( options );
В приведённом примере полагается, что в форме для ввода есть текстовое поле с идентификатором js-Field, куда будет вводиться почтовый адрес. Плагин настраивается так, чтобы отслеживать пользовательский ввод почтового адреса в этом поле и отображать подходящие подсказки. Более подробно об использовании подсказок для почтовых адресов можно посмотреть по следующей ссылке suggest/address.
Когда пользователь выбирает подходящую подсказку, плагин вызывает подготовленный нами колбэк onSelect. Ему в качестве аргумента передаётся выбранная подсказка Suggestion. Внутри этого колбэка мы берём сигнатуру выбранного пользователем адреса Suggestion.sign и отсылаем в ajax запросе fetch/address нашему сервису. В качестве ответа Response мы получаем стандартизованный адрес, который далее используем, согласно нашей задаче. В приведённом примере полученный стандартизованный адрес просто выводится на экран.
Приведенный ниже запрос отсылает сервису сигнатуру 77s2908htдомhv5stстрsv3, которая соответствует почтовому адресу г Москва, ул Ткацкая, дом 5, стр 3. При этом используется минимальное количество параметров и опций.
В данном запросе используются следующие параметры.
Рассмотрим более подробно все параметры, которые сервис может получать в рамках данной команды.
Обязательные параметры для выполнения запроса.
Опциональные параметры.
Если при отправке запроса не указывать данный параметр, то обработка будет выполняться бесплатно, однако по запрошенному адресу сервис будет возвращать не все доступные сведения.
Данный параметр не следует использовать, если вы отсылаете ajax-запросы непосредственно из браузера с веб-страницы, публично доступной любому посетителю вашего веб-сайта. Поскольку в этом случае ваш API-токен может стать известен третьим лицам. Чтобы этого избежать, следует организовать отсылку этих запросов либо с backend-а вашего веб-сайта, либо с закрытой части веб-сайта, доступной, например, только вашим сотрудникам, выполняющим обработку заказов.
Приведенный ниже запрос отсылает сервису сигнатуру 77s2908htдомhv5stстрsv3, которая соответствует почтовому адресу г Москва, ул Ткацкая, дом 5, стр 3 с дополнительными параметрами.
В данном запросе используются следующие параметры.
Ниже приведен ответ сервиса с результатом обработки сигнатуры 77s2908htдомhv5stстрsv3, которая соответствует почтовому адресу г Москва, ул Ткацкая, дом 5, стр 3. Результирующий JSON-ответ получен с использованием опции output=json|pretty, позволяющей выполнить "красивое" форматирование JSON-текста. Данный ответ также получен при включенных в "Профиле" следующих флажках.
Это равносильно использованию опций output=ageo|acodes|adict|afiasall|apretty.
{ "address" : { "codes" : { "abr_actual_code" : "77s2908", "abr_detected_code" : "77s2908", "fias_Region" : "0c5b2444-70a0-4932-980c-b4dc0d3f02b5", "fias_actual_code" : "7700000000000002908", "fias_house" : "ad3d96c0-dbc2-41af-b6b9-92499de7030d", "fias_house_precise" : true, "fias_object" : "e998a78a-bd5a-44f4-81ce-cb2b78f2997b", "fias_object_level" : "Street", "ifns_fl" : "7719", "ifns_ul" : "7719", "kladr_actual_code" : "770000000002908", "okato" : "45263588000", "oktmo" : "45314000", "sign" : "77s2908htдомhv5stстрsv3" }, "fields" : [ { "c" : "77", "level" : "Region", "name" : "Москва", "type" : "г" }, { "level" : "District" }, { "level" : "City" }, { "level" : "Place" }, { "level" : "Site" }, { "c" : "2908", "level" : "Street", "name" : "Ткацкая", "type" : "ул" }, { "level" : "House", "name" : "5", "type" : "дом" }, { "level" : "Building" }, { "level" : "Structure", "name" : "3", "type" : "стр" }, { "level" : "Flat" }, { "level" : "Zip", "name" : "105318", "type" : "Индекс" } ], "geo_data" : { "house_level" : "House", "max" : { "lat" : 55.7871179, "lon" : 37.7456284 }, "mid" : { "lat" : 55.7864431, "lon" : 37.7219992 }, "min" : { "lat" : 55.7851785, "lon" : 37.7177840 }, "object_level" : "Street", "rel" : 100 }, "pretty" : "г Москва, ул Ткацкая, дом 5" }, "query" : "77s2908htдомhv5stстрsv3", "request_process_time" : 3 }
Результатом получения стандартизованного почтового адреса является JSON-объект со следующими элементами.
Здесь и далее приводится описание ответа сервиса в случае использования формата XML. По существу возвращаемые в XML-ответе элементы имеют аналогичное назначение JSON-элементам, описанным выше. Для получения ответа в формате XML необходимо в исходном запросе использовать значение параметра output=xml.
XML-ответ сервиса в результате обработки сигнатуры 77s2908htдомhv5stстрsv3, которая соответствует почтовому адресу г Москва, ул Ткацкая, дом 5, стр 3, имеет следующий вид.
<ProcessFetchResult> <Address> <Field level="Region" name="Москва" type="г" c="77"/> <Field level="District" name="" type=""/> <Field level="City" name="" type=""/> <Field level="Place" name="" type=""/> <Field level="Site" name="" type=""/> <Field level="Street" name="Ткацкая" type="ул" c="2908"/> <Field level="House" name="5" type="дом"/> <Field level="Building" name="" type=""/> <Field level="Structure" name="3" type="стр"/> <Field level="Flat" name="" type=""/> <Field level="Zip" name="105318" type="Индекс"/> <Pretty><![CDATA[ г Москва, ул Ткацкая, дом 5, стр 3 ]]></Pretty> <GeoData rel="100" object_level="Street" house_level="House"> <Mid lat="55.7864431" lon="37.7219992"/> <Min lat="55.7851785" lon="37.7177840"/> <Max lat="55.7871179" lon="37.7456284"/> </GeoData> <Codes> <ABR actual="77s2908" detected="77s2908"/> <Sign val="77s2908htдомhv5stстрsv3"/> <KLADR val="770000000002908"/> <FIAS object="e998a78a-bd5a-44f4-81ce-cb2b78f2997b" object_level="Street" house="ad3d96c0-dbc2-41af-b6b9-92499de7030d" house_precise="1" Region="0c5b2444-70a0-4932-980c-b4dc0d3f02b5"/> <OKATO val="45263588000"/> <OKTMO val="45314000"/> <IFNS_FL val="7719"/> <IFNS_UL val="7719"/> </Codes> </Address> <Query val="77s2908htдомhv5stстрsv3"/> </ProcessFetchResult>
Результатом стандартизации почтового адреса является XML-документ со следующими дочерними элементами.