Получение стандартизованного адреса

Команда fetch/address позволяет получить информацию об адресе, который ранее был обработан сервисом, например, с помощью команды стандартизации cleanse/address, или с помощью команды формирования подсказок suggest/address. В обоих случаях сервис возвращает уникальную сигнатуру почтового адреса, по которой можно запросить всю необходимую информацию о нём с помощью команды fetch/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. При этом используется минимальное количество параметров и опций.

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

• output=json - сообщает сервису о том, что необходимо вернуть ответ в формате JSON.
• query=77s2908htдомhv5stстрsv3 - сигнатура запрашиваемого почтового адреса. Поскольку сигнатура может содержать символы кириллицы, перед отправкой запроса необходимо закодировать её с использованием URL-encoding.

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

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

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

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

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

• user=API-токен - опциональный API-токен пользователя из личного кабинета. Данный параметр не является обязательным. Его следует использовать в случае, если по запрашиваемому адресу нужно получить расширенную информацию, например, географические координаты. Обработка такого запроса будет выполняться платно, поэтому сервис будет списывать со счёта аккаунта стоимость выполнения данной команды согласно цене, указанной в Профиле личного кабинета.

  Если при отправке запроса не указывать данный параметр, то обработка будет выполняться бесплатно, однако по запрошенному адресу сервис будет возвращать не все доступные сведения.

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

• output=pretty - опция, применимая только в случае использования JSON формата ответа сервиса. Данная опция требует, чтобы сервис выполнил "красивое" форматирование возвращаемого JSON текста, расставив в нем переносы строк, отступы и пробельное прореживание. Опция может быть полезна при отладке взаимодействия пользовательского приложения с сервисом.
• output=cp1251 - опция применима только в случае использования XML формата ответа сервиса. Данная опция требует, чтобы сервис вернул XML-ответ в кодировке windows-1251.
• input=utf8 или input=cp1251 - кодировка UTF-8 или windows-1251, в которой представлены входные данные в параметре query.
• output=ageo|acodes|adict|afiasall|apretty - опции, включающие в ответ сервиса дополнительную информацию об обработанном адресе. Можно указать одну или сразу несколько опций, разделив их вертикальной чертой. Опции имеют следующее назначение.
  • output=ageo - включает в ответ сервиса географические координаты обработанного почтового адреса. Данную опцию можно не указывать, если в личном кабинете пользователя в разделе "Профиль" установить флажок "Возвращать в API-ответах географические координаты обработанных адресов". Данная опция доступна только в платной версии команды.
  • output=acodes - включает в ответ сервиса информацию о дополнительных кодах, присвоенных адресу различными справочниками, например, код КЛАДР. Данную опцию можно не указывать, если в личном кабинете пользователя в разделе "Профиль" установить флажок "Возвращать в API-ответах информацию о кодах адреса по справочникам". Данная опция доступна только в платной версии команды.
  • output=adict - данную опцию следует использовать только совместно с предыдущей опцией acodes, она позволяет включить в состав возвращаемых кодов дополнительные коды адреса по ФИАС, ОКАТО, ОКТМО и ИФНС. Данная опция введена в качестве временной меры для обеспечения совместимости с приложениями, которые используют опцию acodes, но пока не готовы к получению полного комплекта поддерживаемых сервисом кодов. В перспективе эта опция будет упразднена, а ее возможности будут включены в перечень возможностей, предоставляемых опцией acodes. Данная опция доступна только в платной версии команды.
  • output=afiasall - данную опцию следует использовать только совместно с предыдущей опцией acodes, она позволяет включить в состав возвращаемых кодов коды по справочнику ФИАС для всех полей адреса. Без использования данной опции коды ФИАС будут возвращаться только для самого последнего поля адреса, например, для улицы, а также для номера дома, если таковой указан в исходном адресе. Данная опция доступна только в платной версии команды.
  • output=apretty - включает в ответ сервиса строку с "красивым" и правильным написанием адреса. Данная строка формируется путем сцепления полей стандартизованного адреса. Данную опцию можно не указывать, если в личном кабинете пользователя в разделе "Профиль" установить флажок "Возвращать в API-ответах блок с "красивым" строковым представлением стандартизованного адреса".

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

Приведенный ниже запрос отсылает сервису сигнатуру 77s2908htдомhv5stстрsv3, которая соответствует почтовому адресу г Москва, ул Ткацкая, дом 5, стр 3 с дополнительными параметрами.

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

• user=demotoken – сообщает сервису API-токен пользователя, поэтому в данном случае полагается, что запрос выполняется платно, так что после его выполнения с баланса будет списана его стоимость.
• output=json|pretty|ageo - сообщает сервису о том, что необходимо вернуть ответ в формате JSON, отформатировав его "красиво". При этом у сервиса дополнительно запрашиваются географические координаты обработанного почтового адреса.
• query=77s2908htдомhv5stстрsv3 - сигнатура запрашиваемого почтового адреса. Для наглядности здесь она приведена без использования URL-encoding.

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

Ниже приведен ответ сервиса с результатом обработки сигнатуры 77s2908htдомhv5stстрsv3, которая соответствует почтовому адресу г Москва, ул Ткацкая, дом 5, стр 3. Результирующий JSON-ответ получен с использованием опции output=json|pretty, позволяющей выполнить "красивое" форматирование JSON-текста. Данный ответ также получен при включенных в "Профиле" следующих флажках.

• Возвращать в API-ответах географические координаты обработанных адресов.
• Возвращать в API-ответах информацию о кодах адреса по справочникам.
• Возвращать в API-ответах блок с "красивым" строковым представлением стандартизованного адреса.

Это равносильно использованию опций 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-объект со следующими элементами.

• address – объект, содержащий информацию о запрошенном адресе. Если в запросе будет указана некорректная сигнатура, либо сигнатура не существующего адреса, то в ответе сервиса не будет содержаться данный объект. Описание объектов такого типа приведено в документации к API-команде cleanse/address по следующей ссылке cleanse/address#JSON-addresses.
• query – исходный запрос, полученный и обработанный сервисом.
• request_process_time – время обработки всего запроса в целом в миллисекундах.

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

Здесь и далее приводится описание ответа сервиса в случае использования формата 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-документ со следующими дочерними элементами.

• Address - данный XML-элемент содержит информацию, о запрошенном адресе. Если в запросе будет указана некорректная сигнатура, либо сигнатура не существующего адреса, то в ответе сервиса не будет содержаться данный XML-элемент. Описание данного элемента приведено в документации к API-команде cleanse/address по следующей ссылке cleanse/address#XML-Address.
• Query - данный XML-элемент содержит обработанную строку запроса. Эта строка передается с помощью атрибута val этого XML-элемента. Данный элемент является полным аналогом JSON-элемента query, возвращаемого в JSON-ответе сервиса.