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

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

Применительно к ранее стандартизованному адресу использование данной команды позволяет получить свежие сведения о нём, такие как географические координаты или коды по справочникам ФИАС, КЛАДР, ОКАТО и ОКТМО. Это может быть востребовано, если с момента стандартизации адреса прошло достаточно много времени, так что ранее полученная информация могла потерять актуальность.

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

Кроме этого, для адресов РФ данная команда может использоваться независимо от подсказок, если просто требуется получить сведения об адресе по его ФИАС-идентификатору, представленному в форме GUID.

Использование fetch/address в связке с подсказками почтового адреса

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

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

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

Для отображения подсказок здесь используется наш JavaScript модуль ahunter_suggest.js, доступный по следующей ссылке. В данном модуле есть встроенная поддержка команды fetch/address, поэтому здесь достаточно реализовать колбэк on_fetch, который будет принимать результат выполнения данной команды, после того, как пользователь выберет подсказку с подходящим адресом. Ниже показан пример такой реализации.

//настраиваем модуль подсказок для работы с нашим сервисом
var options = 
{  
  id: 'js-AddressField', 
    
  //колбэк при получении данных об адресе
  on_fetch : function( Suggestion, Address ) 
  {
    //выводим описатель Address на экран
    console.log( Suggestion, Address );
  }
} );

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

В приведённом примере полагается, что в форме для ввода есть текстовое поле с идентификатором js-AddressField, куда будет вводиться почтовый адрес. Наш JavaScript модуль настраивается так, чтобы отслеживать пользовательский ввод почтового адреса в этом поле и отображать подходящие подсказки. Более подробно об использовании подсказок для почтовых адресов можно посмотреть по следующей ссылке suggest/address.

Когда пользователь выбирает подходящую подсказку, модуль автоматически отсылает Ахантеру ajax-запрос fetch/address, в рамках которого сервису передаётся сигнатура выбранного адреса. После получения ответа от сервиса вызывается подготовленный нами колбэк on_fetch, который получает стандартизованный адрес, который далее используем, согласно нашей задаче. В приведённом примере полученный стандартизованный адрес просто выводится в консоль.

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

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

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

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

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

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

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

• https://ahunter.ru/site/fetch/address - URL-команды.
• output=json или output=xml - формат, в котором требуется вернуть результат выполнения команды.
• query=строка с сигнатурой, кодом или идентификатором адреса. Поддерживаются следующие форматы для данной строки:
  • Простая строка с сигнатурой, запрашиваемого почтового адреса, полученная либо через API-подсказок, либо через API-стандартизации адресов, например, 77s2908hдом:5uстр:3.
  • Строка с префиксом fias:, например, fias:ad3d96c0-dbc2-41af-b6b9-92499de7030d задаёт поиск не по сигнатуре, а по ФИАС-идентификатору в формате GUID.
  • Строка с префиксом kladr:, например, kladr:770000000002908 задаёт поиск не по сигнатуре, а по классификационному КЛАДР-коду, заданному до улицы включительно. Результатом команды в такой форме будет адрес с детализацией до улицы.

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

• 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 | ainabr | astations | apostoffice | timezone | acountry | agar | aprop - опции, включающие в ответ сервиса дополнительную информацию об обработанном адресе. Можно указать одну или сразу несколько опций, разделив их вертикальной чертой. Опции имеют следующее назначение.
  • output=ageo - включает в ответ сервиса географические координаты обработанного почтового адреса. Данную опцию можно не указывать, если в личном кабинете пользователя в разделе "Профиль" установить флажок "Возвращать в API-ответах географические координаты обработанных адресов". Данная опция доступна только в платной версии команды.
  • output=acodes - включает в ответ сервиса информацию о дополнительных кодах, присвоенных адресу различными справочниками, например, код КЛАДР. Данную опцию можно не указывать, если в личном кабинете пользователя в разделе "Профиль" установить флажок "Возвращать в API-ответах информацию о кодах адреса по справочникам". Данная опция доступна только в платной версии команды.
  • output=adict - данную опцию следует использовать только совместно с предыдущей опцией acodes, она позволяет включить в состав возвращаемых кодов дополнительные коды адреса по ФИАС, ОКАТО, ОКТМО и ИФНС. Данная опция введена в качестве временной меры для обеспечения совместимости с приложениями, которые используют опцию acodes, но пока не готовы к получению полного комплекта поддерживаемых сервисом кодов. В перспективе эта опция будет упразднена, а ее возможности будут включены в перечень возможностей, предоставляемых опцией acodes. Данная опция доступна только в платной версии команды.
  • output=afiasall - данную опцию следует использовать только совместно с предыдущей опцией acodes, она позволяет включить в состав возвращаемых кодов коды по справочнику ФИАС для всех полей адреса. Без использования данной опции коды ФИАС будут возвращаться только для самого последнего поля адреса, например, для улицы, а также для номера дома, если таковой указан в исходном адресе. Данная опция доступна только в платной версии команды.
  • output=apretty - включает в ответ сервиса строку с "красивым" и правильным написанием адреса. Данная строка формируется путем сцепления полей стандартизованного адреса. Данную опцию можно не указывать, если в личном кабинете пользователя в разделе "Профиль" установить флажок "Возвращать в API-ответах блок с "красивым" строковым представлением стандартизованного адреса".
  • output=ainabr - при использовании данной опции сервис возвращает адрес в формате АБР классификатора, совместимого с классификатором ФИАС. В противном случае адрес будет возвращаться в формате КЛАДР. Кроме этого в составе ответа сервиса будут возвращаться дополнительные коды по классификаторам АБР и ФИАС. Данную опцию можно не указывать, если в личном кабинете пользователя в разделе "Профиль" установить флажок "В API и реестрах приводить почтовые адреса к структуре АБР/ФИАС, а не КЛАДР".
  • output=aareas - при использовании данной опции для успешно обработанного адреса сервис будет возвращать информацию о принадлежности адреса району и административному округу города, а также окружной кольцевой дороге. Данная информация возвращается только при условии, что город, в котором находится адрес, допускает деление на районы и/или округа. Информация о кольцевой дороге возвращается, если адрес находится внутри или рядом с городом, вокруг которого имеется кольцевая дорога. Данную опцию можно не указывать, если в личном кабинете пользователя в разделе "Профиль" установить флажок "Возвращать в API-ответах блок с городским районом и округом адреса".
  • output=astations - при использовании данного параметра для успешно обработанного адреса сервис возвращает ближайшие станции метро и станции скоростного легкорельсового транспорта. Данную опцию можно не указывать, если в личном кабинете пользователя в разделе "Профиль" установить флажок "Возвращать в API-ответах блок с ближайшими до адреса станциями".
  • output=apostoffice – данный параметр сообщает сервису, что для обработанного адресе нужно найти ближайшее почтовое отделение и включить информацию о нём в ответ сервиса. Данную опцию можно не указывать, если в личном кабинете пользователя в разделе "Профиль" установить флажок "Возвращать в API-ответах информацию о почтовом отделении адреса".
  • output=timezone – опция сообщает сервису, что при обработке адреса или телефона нужно определить его часовую зону и вернуть эту информацию в ответе сервиса. Данную опцию можно не указывать, если в личном кабинете пользователя в разделе "Профиль" установить флажок "Возвращать в API-ответах информацию о часовой зоне адреса/телефона".
  • output=acountry – опция включает в выдачу с результатом обработки адреса информацию о стране, которой он принадлежит. Данную опцию можно не указывать, если в личном кабинете пользователя в разделе "Профиль" установить флажок "Возвращать в API-ответах информацию о стране, которой принадлежит адрес".
  • output=agar – данную опцию следует использовать только совместно с опцией acodes, она позволяет включить в состав возвращаемых классификационных кодов дополнительные идентификаторы адреса по Государственному Адресному Реестру (ГАР) и кадастровые номера объектов недвижимости.
  • output=aprop – опция включает вывод в результат обработки адреса информацию с дополнительными свойствами адреса, например, сведения о количестве квартир или помещений в доме.

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

Приведенный ниже запрос отсылает сервису ФИАС-гуид 0356fd88-f317-4e8f-8012-8fb090589ed1, который соответствует почтовому адресу г Москва, ул Ткацкая, дом 1, кв 1П с дополнительными параметрами.

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

• user=demotoken – сообщает сервису API-токен пользователя, поэтому в данном случае полагается, что запрос выполняется платно, так что после его выполнения с баланса будет списана его стоимость.
• output=json|pretty|ageo - сообщает сервису о том, что необходимо вернуть ответ в формате JSON, отформатировав его "красиво". При этом у сервиса дополнительно запрашиваются географические координаты обработанного почтового адреса.
• query=fias:0356fd88-f317-4e8f-8012-8fb090589ed1 - строка, начинающаяся на префикс fias: и содержащая ФИАС-идентификатор запрашиваемого адреса, т.к. в данном примере запрашивается адрес на территории РФ по его ФИАС-гуид. Без данного префикса сервис будет интерпретировать query в качестве сигнатуры адреса и обрабатывать её соответствующим образом.

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

Ниже приведен ответ сервиса с результатом обработки сигнатуры 77s2908hдом:5uстр:3, которая соответствует почтовому адресу г Москва, ул Ткацкая, дом 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" : "77s2908hдом:5uстр:3"
        },
        "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" : "77s2908hдом:5uстр:3",
      "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-ответ сервиса в результате обработки сигнатуры 77s2908hдом:5uстр:3, которая соответствует почтовому адресу г Москва, ул Ткацкая, дом 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="77s2908hдом:5uстр:3"/>
      <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="77s2908hдом:5uстр:3"/>
</ProcessFetchResult>

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

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