Стандартизация почтового адреса

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

Стандартизация адреса сопровождается его обогащением дополнительной информацией, такой как GPS-координаты, коды по справочникам (например, код КЛАДР), показателями качества, а также дополнительной служебной информацией.

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

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

https://ahunter.ru/site/cleanse/address?user=demotoken;output=json;query=%D0%BC%D0%BE%D1%81%D0%BA%D0%B2%D0%B0%20%D0%BC%D0%B8%D1%80%D0%B0

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

  • user=demotoken - сообщает сервису API-токен пользователя. При отправке реального запроса вместо значения demotoken нужно подставить токен из личного кабинета.
  • output=json - сообщает сервису о том, что необходимо вернуть ответ в формате JSON.
  • query=%D0%BC%D0 ... %80%D0%B0 - закодированный с использованием URL-encoding исходный адрес "москва мира", подлежащий обработке.

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

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

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

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

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

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

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

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

https://ahunter.ru/site/cleanse/address?user=demotoken;output=json|pretty|ageo;
mode=forcezip|weak;addresslim=1;query=%D0%BC%D0%BE%D1%81%D0%BA%D0%B2%D0%B0%20%D0%BC%D0%B8%D1%80%D0%B0

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

  • user=demotoken - сообщает сервису API-токен пользователя.
  • output=json|pretty|ageo - сообщает сервису о том, что необходимо вернуть ответ в формате JSON, отформатировав его "красиво". При этом у сервиса дополнительно запрашиваются географические координаты обработанного почтового адреса.
  • mode=forcezip|weak - сообщает сервису, что в процессе обработки нужно включить фильтрацию по индексу, но при этом снять некоторые строгие ограничения.
  • addresslim=1 - сообщает сервису, что в случае, если адрес будет распознан неоднозначно, то следует вернуть только один вариант распознавания, наиболее соответствующий исходной строке.
  • query=%D0%BC%D0 ... %80%D0%B0 - закодированный с использованием URL-encoding исходный адрес "москва мира", подлежащий обработке.

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

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

  • Возвращать в API-ответах информацию о покрытых адресом фрагментах исходной строки.
  • Возвращать в API-ответах географические координаты обработанных адресов.
  • Возвращать в API-ответах информацию о кодах адреса по справочникам (например, КЛАДР).
  • Возвращать в API-ответах информацию о показателях качества обработанных адресов.
  • Возвращать в API-ответах блок со статусом результата обработки, объясняющим причину отбраковки адреса.
  • Возвращать в API-ответах блок с "красивым" строковым представлением стандартизованного адреса.

Это равносильно использованию опций output=acover|ageo|acodes|aqual|apretty|status.

    {
      "addresses" : [
        {
          "codes" : {
            "fias_house" : "ffd3eaa6-0731-413f-b2e3-c4111e999ca5",
            "fias_house_precise" : false,
            "fias_object" : "e998a78a-bd5a-44f4-81ce-cb2b78f2997b",
            "fias_object_level" : "Street",
            "ifns_fl" : "7719",
            "ifns_ul" : "7719",
            "kladr_actual" : "770000000002908",
            "kladr_detected" : "770000000002908",
            "kladr_pure" : "770000000002908",
            "okato" : "45263588000",
            "oktmo" : "45314000"
          },
          "cover" : [
            {
              "in" : "москва"
            },
            {
              "in" : "ул. ткацкая"
            },
            {
              "in" : "д.5"
            },
            {
              "out" : "вход справа от магазина"
            }
          ],
          "fields" : [
            {
              "c" : "77",
              "cover" : "москва",
              "level" : "Region",
              "name" : "Москва",
              "ns" : 1.00,
              "ts" : 0.00,
              "type" : "г"
            },
            {
              "level" : "District"
            },
            {
              "level" : "City"
            },
            {
              "level" : "Place"
            },
            {
              "c" : "2908",
              "cover" : "ул. ткацкая",
              "level" : "Street",
              "name" : "Ткацкая",
              "ns" : 1.00,
              "ts" : 1.00,
              "type" : "ул"
            },
            {
              "c" : "0004",
              "cover" : "д.5",
              "level" : "House",
              "name" : "5",
              "ns" : 1.00,
              "ts" : 1.00,
              "type" : "дом"
            },
            {
              "level" : "Building"
            },
            {
              "level" : "Structure"
            },
            {
              "level" : "Flat"
            },
            {
              "level" : "Zip",
              "name" : "105318",
              "type" : "Индекс"
            }
          ],
          "geo_data" : {
            "house_level" : "House",
            "max" : {
              "lat" : 55.7865962,
              "lon" : 37.7331519
            },
            "mid" : {
              "lat" : 55.7864431,
              "lon" : 37.7219992
            },
            "min" : {
              "lat" : 55.7853957,
              "lon" : 37.7221214
            },
            "object_level" : "Street",
            "rel" : 100
          },
          "pretty" : "г Москва, ул Ткацкая, дом 5",
          "quality" : {
            "canonic_fields" : 2,
            "detected_fields" : 2,
            "precision" : 100,
            "recall" : 100,
            "verified_numeric_fields" : 1
          }
        }
      ],
      "check_info" : {
        "alts" : 1,
        "query" : "москва ул. ткацкая  д.5 вход справа от магазина",
        "time" : 0
      },
      "request_process_time" : 3
    }

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

  • addresses - массив с вариантами распознавания адреса.
  • check_info - объект со сводной информацией о результате обработки.
  • request_process_time - время обработки всего запроса в целом в миллисекундах.

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

JSON-массив addresses: варианты стандартизации адреса

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

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

  • obsolet - строка, возвращаемая только в случае, если распознанный адрес является устаревшим. В этом случае данная строка принимает следующие значения.
    • nonexistent - для распознанного адреса не существует актуальной версии, так что данный адрес в настоящий момент является не существующим. Такое возможно, например, если в адресе указан заброшенный нежилой к настоящему моменту населенный пункт.
    • has_actual - указывает на то, что исходный адрес не является актуальным, он был переподчинен, а в качестве результата распознавания возвращена его актуальная версия. Такое возможно, например, если в адресе указан населенный пункт, который в настоящий момент вошел в состав крупного города.
  • fields - JSON-массив, в котором каждый элемент соответствует отдельному адресному полю распознанного почтового адреса. Подробное описание объектов, являющихся элементами данного массива, приведено далее в соответствующем подразделе.
  • cover - JSON-массив, каждый элемент которого содержит фрагмент исходной обработанной строки с пометкой, принадлежит ли данный фрагмент какому-то полю адреса или нет. Данный массив возвращается в случае, если в запросе указан параметр output=acover, либо, если в "Профиле" личного кабинета выставлен флажок "Возвращать в API-ответах информацию о покрытых адресом фрагментах исходной строки".
  • pretty - строка, содержащая "красивое" написание стандартизованного адреса. Данная строка возвращается в случае, если в запросе указан параметр output=apretty, либо, если в "Профиле" личного кабинета выставлен флажок "Возвращать в API-ответах блок с "красивым" строковым представлением стандартизованного адреса".
  • geo_data - JSON-объект, содержащий географические координаты почтового адреса. Данный объект возвращается в случае, если в запросе указан параметр output=ageo, либо, если в "Профиле" личного кабинета выставлен флажок "Возвращать в API-ответах географические координаты обработанных адресов".
  • codes - JSON-объект, в котором приведены коды распознанного адреса по справочникам, например, код по классификатору КЛАДР. Данный объект возвращается в случае, если в запросе указан параметр output=acodes, либо, если в "Профиле" личного кабинета выставлен флажок "Возвращать в API-ответах информацию о кодах адреса по справочникам (например, КЛАДР)".
  • quality - JSON-объект, содержащий показатели качества, позволяющих количественно оценивать качество полученного результата распознавания. Данный объект возвращается в случае, если в запросе указан параметр output=aqual, либо, если в "Профиле" личного кабинета выставлен флажок "Возвращать в API-ответах информацию о показателях качества обработанных адресов".

JSON-массив fields: адресные поля

Данный массив является элементом JSON-объекта, соответствующего одному варианту распознавания адреса в рамках JSON-массива addresses. Фактически массив fields представляет стандартизованный адрес, разбитый на отдельные компоненты - адресные поля.

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

    {
      "c" : "2908",
      "cover" : "ул. ткацкая",
      "level" : "Street",
      "name" : "Ткацкая",
      "ns" : 1.00,
      "ts" : 1.00,
      "type" : "ул"
    }

В общем случае эти объекты могут содержать следующие элементы.

  • level - содержит строковое имя уровня адресного поля. Для первых пяти полей адреса уровень поля соответствует уровню модели адресов КЛАДР. Данное поле может принимать следующие значения.
    • Region - поле соответствует уровню регионов (первый уровень КЛАДР).
    • District - поле соответствует уровню административных районов (второй уровень КЛАДР).
    • City - поле соответствует уровню крупных городов (третий уровень КЛАДР).
    • Place - поле соответствует уровню населенных пунктов (четвертый уровень КЛАДР).
    • Street - поле соответствует уровню улиц (пятый уровень КЛАДР).
    • House - поле содержит номер дома.
    • Building - поле содержит номер корпуса.
    • Structure - поле содержит номер строения.
    • Flat - поле содержит номер квартиры, помещения, комнаты или офиса.
    • Zip - поле содержит почтовый индекс.
  • name - содержит исправленное и нормализованное имя адресного объекта, размещенного в поле адреса на соответствующем уровне, либо числовое значение для полей от уровня House до Zip. Отсутствие данного элемента в рамках JSON-объекта или его пустое значение говорит о том, что нормализованный вариант адреса не содержит адресных объектов на данном уровне. В приведенном выше примере в составе адреса не содержится населенный пункт, поэтому объект на уровне населенного пункта "level": "Place" не содержит элемента name.
  • type - содержит нормализованное сокращенное наименование типа адресного объекта (тип адресного объекта), размещенного на соответствующем уровне адреса. Отсутствие данного элемента в рамках JSON-объекта или пустое его значение говорит о том, что нормализованный вариант адреса не содержит адресных объектов в данном поле адреса.
  • ns - число от 0 до 1, дающее количественную оценку похожести имени адресного объекта в исходном запросе на нормализованное имя адресного объекта, возвращенное в элементе name данного JSON-объекта. Данное число может быть использовано приложением пользователя, например, для расчета комплексного показателя степени доверия результату распознавания. Данный элемент не выводится для незаполненных адресных полей.
  • ts - число от 0 до 1, дающее количественную оценку похожести типа адресного объекта в исходном запросе на нормализованное имя типа адресного объекта в элементе type данного JSON-объекта. Значение 0 соответствует отсутствию распознанного типа в исходном запросе. Значение 1 соответствует успешному распознаванию типа. Данный элемент не выводится для незаполненных адресных полей.
  • c - число, отражающее уникальный код адресного объекта в пределах его родителя по классификатору адресов КЛАДР. Данный элемент не выводится для незаполненных адресных полей.
  • st - целое число, отражающее административный статус адресного объекта. Данный элемент может принимать следующие значения.
    • 1 - объект является центром района;
    • 2 - объект является центром (столицей) региона;
    • 3 - объект является одновременно и центром района и центром региона;
    • 4 - объект является районом, в котором находится центр региона.
    Для остальных адресных объектов данный элемент не выводится.
  • cover - строка, содержащая фрагмент исходного обработанного запроса, на основании которого было выполнено распознавание данного поля адреса. Эта информация выводится только для тех полей, которые реально были распознаны в исходном запросе. Адресные поля, информация по которым была лишь восстановлена по эталонному адресному хранилищу сервиса, но не распознана в исходном тексте, выводятся без элемента cover. Вывод поля cover является опциональным. Для его включения в состав результирующего ответа необходимо в запросе использовать параметр output=acover, либо установить флажок "Возвращать в API-ответах информацию о покрытых адресом фрагментах исходной строки" в "Профиле" личного кабинета.

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

JSON-массив cover: покрытия адресных полей

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

Каждый объект данного массива может содержать один из двух следующих элементов.

  • in - строка, являющаяся фрагментом исходного запроса, задействованная при распознавании какого-то поля обработанного адреса.
  • out - строка, являющаяся фрагментом исходного запроса, не использованная при распознавании полей обработанного адреса.

Пример JSON-массива cover приведен ниже.

    "cover" : [
      {
        "in" : "москва"
      },
      {
        "in" : "ул. ткацкая"
      },
      {
        "in" : "д.5"
      },
      {
        "out" : "вход справа от магазина"
      }
    ]

Исходя из данного примера, фрагменты исходного запроса "москва" и "ул. ткацкая" были задействованы при распознавании полей адреса, поэтому они размещены в in-элементах. Фрагмент "вход справа от магазина" не использовался при распознавании адреса, поэтому он заключен в out-элементе.

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

JSON-объект geo_data: GPS-координаты адреса

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

Вся эта информация передается в элементах mid, min и max в составе объекта geo_data. Пример JSON-объекта geo_data приведен ниже.

    "geo_data" : {
      "house_level" : "House",
      "max" : {
        "lat" : 55.7865962,
        "lon" : 37.7331519
      },
      "mid" : {
        "lat" : 55.7864431,
        "lon" : 37.7219992
      },
      "min" : {
        "lat" : 55.7853957,
        "lon" : 37.7221214
      },
      "object_level" : "Street",
      "rel" : 100
    }

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

  • mid - JSON-объект, содержащий координаты серединной точки адресного объекта. Данная точка располагается внутри объекта и соответствует его условному центру. Центр является условным, поскольку в общем случае адресный объект имеет неправильную форму, не позволяющую найти его корректный геометрический центр. Серединная точка позволяет рассматривать любой адресный объект не в виде сложной фигуры, а в виде простой одиночной точки, размещенной на поверхности земного шара. Все дома, здания и постройки, расположенные на карте, сервис рассматривает исключительно в виде серединных точек, независимо от их формы и размеров.
  • min и max - JSON-объекты, содержащие координаты нижней и верхней границы адресного объекта соответственно. Для всех адресных объектов, размещенных выше уровня House (уровень дома), сервис дополнительно возвращает координаты нижней и верхней границы. Эти границы задают область на поверхности земного шара, в пределах которой располагается объект сложной формы, например, улица или населенный пункт. Для небольших объектов, данную область можно рассматривать как ограничивающий прямоугольник, в этом случае точка min будет содержать координаты левого нижнего (юго-западного) угла прямоугольника, а точка max - координаты верхнего правого (северо-восточного) угла прямоугольника, как это показано на рисунке ниже.

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

JSON-объекты mid, min и max содержат координаты широты и долготы соответствующей точки: серединной, нижней и верхней. Для этого используются следующие элементы этих объектов.

  • lat - число, содержащее широту адресного объекта.
  • lon - число, содержащее долготу адресного объекта.

Кроме элементов mid, min и max JSON-объект geo_data содержит следующие элементы.

  • rel - число от 0 до 100, отражающее достоверность возвращаемых гео-данных.
  • object_level - имя уровня адресного объекта в составе распознанного адреса, для которого удалось выполнить определение координат нижней и верхней границы min и max. Данный элемент может принимать значения от Region до Street, объяснение которых приводилось ранее для значений элемента level JSON-объекта, описывающего отдельное адресное поле. Важно иметь в виду, что гео-данные могут быть получены не для самого нижнего поля распознанного адреса, в силу отсутствия этой информации на используемой сервисом карте. Например, адрес может быть успешно распознан до улицы включительно, однако координаты могут возвращаться не для улицы, а для населенного пункта, в составе которого присутствует данная улица, поскольку на карте в настоящий момент нет информации об улице.
  • house_level - данный элемент включается в состав гео-данных и принимает значение House в случае, если в обработанном адресе присутствует номер дома и этот дом удалось найти на карте. В этом случае координаты серединной точки mid будут содержать широту и долготу дома. Если в исходном адресе не указан номер дома, или если на карте этот дом отсутствует, элемент house_level не возвращается в составе geo_data, при этом координаты серединной точки mid будут содержать широту и долготу адресного объекта, уровень которого указан в элементе object_level.

JSON-объект codes: справочные коды адреса

Данный объект является элементом JSON-объекта, соответствующего одному варианту распознавания адреса в рамках JSON-массива addresses, и содержит информацию о дополнительных кодах, присвоенных адресу различными справочниками. В настоящий момент поддерживаются коды классификатора КЛАДР, ФИАС, ОКАТО, ОКТМО и коды ИФНС. В процессе расширения функций сервиса состав возвращаемых кодов будет также расширяться. Пример JSON-объекта codes приведен ниже.

    "codes" : {
      "fias_City" : "7dde11f6-f6ab-4a05-8052-78e0cab8fc59",
      "fias_Region" : "0c5b2444-70a0-4932-980c-b4dc0d3f02b5",
      "fias_house" : "6b938964-05dd-4b10-a233-29b4c285c9c5",
      "fias_house_precise" : true,
      "fias_object" : "6abaaa36-ba06-4417-a3cd-08cd9e2d7a3c",
      "fias_object_level" : "Street",
      "ifns_fl" : "7751",
      "ifns_ul" : "7751",
      "kladr_actual" : "770000050000067",
      "kladr_detected" : "500000180000001",
      "kladr_pure" : "770000050000067",
      "okato" : "45298578001",
      "oktmo" : "45931000"
    }

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

  • fias_house – строка, содержащая код номера дома по классификатору ФИАС, если дом присутствует в адресе. Если в адресе отсутствует номер дома, либо если указанный в адресе номер дома не найден в ФИАС, то данный элемент не будет выводиться в ответе сервиса.
  • fias_house_precise – элемент булевского типа принимает значение true, если номер дома точно найден в ФИАС. Если номер дома найден неточно, то элемент примет значение false. Дом может быть найден неточно, например, если в ФИАС указан не конкретный номер, а диапазон домов, в который попадает дом из обработанного адреса. Также дом может быть найден неточно, если между его записью в исходном адресе и записью дома в ФИАС будет выявлено одно из следующих отличий:
    • отличие в буквенной части, например, "дом 5" и "дом 5А".
    • отличие в дробной части, например, "дом 5" и "дом 5/3".
    • отличие в строении, например, "дом 5" и "дом 5 стр 3".
    • отличие в корпусе, например, "дом 5" и "дом 5 корп 3".
  • fias_object – строка, содержащая код ФИАС для адресного объекта самого нижнего заполненного нечислового поля адреса, например, для улицы.
  • fias_object_level – строка содержит название уровня, которому принадлежит объект адреса, код которого возвращен в рамках fias_object. Данный элемент может принимать значения от Region до Street, описание которых приводилось ранее для значений элемента level JSON-объекта, описывающего отдельное адресное поле.
  • fias_Region, fias_District, fias_City, fias_Place – строки, содержащие коды ФИАС для полей адреса на уровне региона, района, города и населённого пункта соответственно. Данные элементы возвращаются сервисом только в случае использования в запросе опции output=afiasall, а также только при фактическом наличии соответствующих полей в обработанном адресе.
  • ifns_fl – строка содержит код ИФНС, обслуживающей физических лиц по данному адресу.
  • ifns_ul – строка содержит код ИФНС, обслуживающей юридических лиц по данному адресу.
  • kladr_actual - строка, содержащая актуальный код адреса до улицы включительно по справочнику КЛАДР.
  • kladr_detected - строка, содержащая код по справочнику КЛАДР для распознанного адреса в исходном запросе. Данный код может отличаться от кода, приведенного в элементе kladr_actual в случае, если в исходном запросе был указан устаревший адрес. В этом случае в kladr_detected будет записан код устаревшего адреса, а в элемент kladr_actual будет записан код адреса, являющегося его настоящей актуальной версией.
  • kladr_pure - строка, содержащая компактную версию кода kladr_actual, не включающую хвостовые нули. Например, если элемент kladr_actual имеет значение "770000000000000", то в kladr_pure будет записано лишь "77".
  • okato – строка, содержащая код ОКАТО, указывающий на объект административно-территориального деления, которому принадлежит адрес.
  • oktmo – строка, содержащая код ОКТМО, указывающий на территорию муниципального образования, на которой находится обработанный адрес.

JSON-объект quality: показатели качества стандартизации

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

    "quality" : {
      "canonic_fields" : 2,
      "detected_fields" : 2,
      "precision" : 100,
      "recall" : 100,
      "verified_numeric_fields" : 0,
      "warnings" : "Incomplete|HouseIsAbsent|"
    }

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

  • canonic_fields - число содержит количество канонических полей адреса, информация по которым в идеале должна была присутствовать в исходном запросе. Данный показатель учитывает только поля, соответствующие уровням адресных объектов от Region до Street.
  • detected_fields - число содержит количество реально распознанных полей адреса в исходных адресных данных. Данное количество может совпадать или быть меньше количества полей, возвращаемых в элементе canonic_fields. Количество реально распознанных полей может быть меньше количества канонических полей адреса в том случае, если в исходных адресных данных пропущена информация о некоторых адресных полях, например, адрес записан без явного указания региона.
  • precision - число содержит информацию о точности распознавания адреса. Точность распознавания представляет собой число от 0 до 100, которое является количественной мерой того, насколько исходные адресные данные соответствуют стандартизованному адресу. Чем меньше ошибок и неточностей допущено при написании исходного адреса, тем выше возвращаемое значение точности.
  • recall - число содержит информацию о полноте использования исходных адресных данных в процессе распознавания. Полнота использования исходных данных представляет собой число от 0 до 100, которое является количественной мерой того, насколько полно были задействованы текстовые данные исходного адреса при распознавании. Чем больше в исходном тексте адреса лишних неадресных данных, не участвующих в распознавании адреса, тем меньше полнота.
  • verified_numeric_fields - число содержит количество числовых адресных полей, значения которых удалось проверить по эталонным справочникам. Например, если в исходном адресе указан номер дома, который удалось распознать и проверить на существование по справочнику КЛАДР, данный показатель примет значение 1.
  • warnings - строка содержит предупреждающие флаги, акцентирующие внимание на определенных свойствах распознанного адреса. Данный элемент не выводится, если в ходе обработки адреса не возникло предупреждений. Наличие предупреждающих флагов не обязательно свидетельствует об ошибке в адресе, тем не менее, приложение пользователя может использовать данные флаги для классификации обрабатываемых адресов или для формирования текстовых комментариев. Несколько флагов разделяются символом вертикальной черты |. В текущей версии сервиса поддерживаются следующие флаги.
    • ChildIsSkipped - наличие данного предупреждающего флага указывает на то, что хотя распознанный адрес и является завершенным и может использоваться для почтовой рассылки, тем не менее в адресном хранилище сервиса для данного адреса есть дочерние адресные объекты, пропущенные в исходном запросе. Например, данный флаг возвращается, если в исходном адресе указано название населенного пункта без улицы, при этом в адресном хранилище сервиса у данного населенного пункта есть как дочерние улицы, так и дочерние дома, не привязанные к конкретным улицам. Такая ситуация соответствует населенным пунктам, у которых допустимо записывать адрес как с указанием улицы, так и без нее. Поскольку заранее не известно, является ли ошибкой отсутствие в таком адресе улицы, результат его обработки не отбраковывается, однако снабжается данным флагом.
    • Incomplete - возвращенный адрес не является завершенным, поскольку в исходных обработанных адресных данных не удалось распознать адресные поля нижних уровней, например, улицу. Незавершенность адреса может быть обусловлена следующими причинами:
      • В исходных данных информация по полям нижних уровней отсутствует. Например, такой незавершенный адрес может быть записан следующим образом "Краснодарский край, г. Краснодар". В данном случае в явном виде не указано название улицы.
      • В исходных данных указана некорректная информация по полям нижних уровней. Например, такой незавершенный адрес может быть записан следующим образом "Краснодарский край, г. Краснодар, Особая улица. В данном случае указано название несуществующей улицы в городе "Краснодар", поэтому сервис вернет адрес, с незаполненным полем улицы и снабдит его предупреждением Incomplete.
    • HouseIsAbsent - в обработанном адресе не распознан дом, корпус и строение. Такие адреса обычно не пригодны для почтовой рассылки, однако, отсутствие дома не является поводом для отбраковки адреса. Решение по таким адресам зависит от пользовательских задач, поэтому сервис помечает такие адреса предупреждающим флагом, не отбраковывая их.
    • RestoredPlaceOrCity - в распознанном адресе восстановлен населенный пункт или город, отсутствующий в исходном запросе. Во многих ситуациях сервис старается отбраковывать адреса, у которых явно пропущено название города или населенного пункта, тем не менее, есть ситуации, когда сервис выполняет восстановление этих полей. Поскольку в таких ситуациях есть небольшой шанс восстановить населенный пункт там, где на самом деле населенный пункт не указан осознанно, такие адреса отмечаются данным флагом.

JSON-объект check_info: сводная информация о результате

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

    "check_info" : {
        "number" : 0,
        "alts" : 0,
        "query" : "на деревню дедушке",
        "status" : NotFound|,
        "time" : 203,
    }

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

  • number - число, указывающее на порядковый номер адреса в случае, когда адрес входит в состав записи из нескольких элементов разного типа, обрабатываемой, например, командой cleanse/record или cleanse/chunk. Нумерация элементов записи начинается с 0. Если адрес не является частью записи, то данный элемент не выводится.
  • alts - число содержит общее количество альтернативных вариантов распознавания и нормализации, подобранных для исходного запроса. Данное число может быть полезно, если требуется узнать реальное количество вариантов распознавания, подобранных сервисом. Это число может быть больше количества вариантов, возвращенных сервисом, поскольку при формировании массива с вариантами распознавания addresses используются лимиты, заданные в запросе или установленные в "Профиле" личного кабинета пользователя. Данное число может быть использовано клиентским приложением, например, для расчета комплексного показателя степени доверия полученному результату распознавания.
  • query - содержит текстовую строку с адресными данными, обработанными сервисом. В общем случае данная строка может не совпадать со строкой, которую сервис получил в исходном запросе, т.к. содержимое строки query учитывает результат предварительной очистки исходных данных, в рамках которой сервис выполняет замену непечатных символов на пробелы, а также делает преобразования некоторых символов алфавита. Данный элемент в первую очередь предназначен для контроля правильности кодировки данных, передаваемых сервису на обработку, при отладке и тестировании интеграции приложения с сервисом.
  • status - строка содержит дополнительную информацию о причинах, по которым обработанный адрес не был распознан. Данный элемент выводится в случае, если в исходном запросе задан параметр output=status, либо если в "Профиле" личного кабинета выставлен флажок "Возвращать в API-ответах блок со статусом результата обработки, объясняющим причину отбраковки адреса". Данный элемент не выводится для успешно распознанных адресов. Возможны следующие значения статуса обработанного адреса.
    • NotFound - обработанный адрес не найден в адресной базе данных сервиса.
    • FilteredByMask - исходный адрес был распознан по некоторому фрагменту исходного запроса, при этом в процессе обработки сервис обнаружил другие важные адресные фрагменты, которые не удалось использовать при распознавании, в результате адрес был отбракован. Данный случай соответствует, например, ситуации, когда в адресе указано по ошибке название региона, не соответствующее остальной части адреса.
  • time - число содержит количество миллисекунд, которые потребовались сервису на обработку исходного запроса.

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

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

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

<ProcessCheckResult>
  <Address>
    <Field level="Region" name="Москва" type="г" 
           ns="1.00" ts="0.00" c="77">
      <![CDATA[москва]]>
    </Field>
    <Field level="District" name="" type=""/>
    <Field level="City" name="" type=""/>
    <Field level="Place" name="" type=""/>
    <Field level="Street" name="Ткацкая" type="ул" 
           ns="1.00" ts="1.00" c="2908">
      <![CDATA[ул. ткацкая]]>
    </Field>
    <Field level="House" name="5" type="дом" 
           ns="1.00" ts="1.00" c="0004">
      <![CDATA[д.5]]>
    </Field>
    <Field level="Building" name="" type=""/>
    <Field level="Structure" name="" type=""/>
    <Field level="Flat" name="" type=""/>
    <Field level="Zip" name="105318" type="Индекс"/>
    <Cover>
      <![CDATA[<b>москва</b> <b>ул. ткацкая</b>  <b>д.5</b> 
      вход справа от магазина]]>
    </Cover>
    <Pretty><![CDATA[г Москва, ул Ткацкая, дом 5]]></Pretty>
    <GeoData rel="100" object_level="Street" house_level="House">
      <Mid lat="55.7864431" lon="37.7219992"/>
      <Min lat="55.7853957" lon="37.7221214"/>
      <Max lat="55.7865962" lon="37.7331519"/>
    </GeoData>
    <Codes>
      <KLADR val="770000000002908"/>
      <FIAS object="e998a78a-bd5a-44f4-81ce-cb2b78f2997b" 
            object_level="Street" 
            house="ffd3eaa6-0731-413f-b2e3-c4111e999ca5" 
            house_precise="0"
            Region="0c5b2444-70a0-4932-980c-b4dc0d3f02b5"/>
      <OKATO val="45263588000"/>
      <OKTMO val="45314000"/>
      <IFNS_FL val="7719"/>
      <IFNS_UL val="7719"/>
    </Codes>
    <Quality>
      <Precision val="100"/>
      <Recall val="100"/>
      <CanonicFields val="2"/>
      <DetectedFields val="2"/>
      <VerifiedNumericFields val="1"/>
    </Quality>
  </Address>
  <CheckInfo>
    <String>
      <![CDATA[москва ул. ткацкая  д.5 вход справа от магазина]]>
    </String>
    <Time>3</Time>
    <Alts>1</Alts>
  </CheckInfo>
</ProcessCheckResult>

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

  • Address - данный XML-элемент соответствует одному из вариантов нормализации обработанного адреса. Поскольку в результате обработки адреса может возникнуть несколько вариантов его распознавания, в XML-ответе может присутствовать несколько элементов Address, каждый из которых соответствует одному из предложенных сервисом вариантов. Список из всех XML-элементов Address является аналогом JSON-массива addresses, возвращаемого в JSON-ответе сервиса.
  • CheckInfo - данный XML-элемент содержит сводную информацию о результате обработки. Данный элемент является полным аналогом JSON-объекта check_info, возвращаемого в JSON-ответе сервиса.

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

XML-элемент Address: вариант стандартизации адреса

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

  • Field - элемент, содержащий информацию об адресном поле. Каждому полю распознанного адреса соответствует отдельный элемент Field в составе XML-элемента Address. Список этих элементов в составе XML-элемента Address является аналогом JSON-массива fields, возвращаемого в ответе сервиса в формате JSON.
  • Cover - предоставляет информацию о границах покрытия распознанного адреса в рамках исходного обработанного текста. Данный элемент является аналогом JSON-массива cover, возвращаемого в ответе сервиса в формате JSON.
  • Pretty - содержит строку с "красивым" написанием стандартизованного адреса, обрамленную секцией CDATA. Данный элемент является аналогом JSON-элемента pretty, возвращаемого в ответе сервиса в формате JSON.
  • GeoData - предоставляет информацию о географических координатах адреса. Данный элемент является аналогом JSON-объекта geo_data, возвращаемого в ответе сервиса в формате JSON.
  • Codes - предоставляет информацию о кодах, приписанных адресу различными справочниками, например, классификатором КЛАДР. Данный элемент является аналогом JSON-объекта codes, возвращаемого в ответе сервиса в формате JSON.
  • Quality - содержит показатели качества распознанного адреса. Данный элемент является аналогом JSON-объекта quality, возвращаемого в ответе сервиса в формате JSON.

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

  • obsolet="1" - указывает на то, что исходный адрес не является актуальным, он был переподчинен, в качестве результата распознавания возвращена его актуальная версия.
  • obsolet="2" - указывает на то, что исходный адрес не является актуальным, однако актуальной версии для адреса не существует.

XML-элемент Field: адресное поле

Элемент Field является дочерним по отношению к элементу Address и включает информацию о поле распознанного адреса. Пример XML-элемента Field приведен ниже.

<Field level="Region" name="Москва" type="г" ns="1.00" ts="0.00" c="77">
  <![CDATA[москва]]>
</Field>

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

  • level - содержит имя уровня, которому принадлежит поле адреса. Данный атрибут принимает значения, описанные ранее для JSON-элемента level в составе JSON-объекта массива fields.
  • name - содержит исправленное и нормализованное имя адресного объекта, размещенного на соответствующем уровне адреса, либо числовое значение для полей от уровня House до Zip. Отсутствие значения у данного атрибута говорит о том, что нормализованный вариант адреса не содержит адресных объектов на соответствующем данному полю уровне. Данный атрибут является аналогом JSON-элемента name в составе JSON-объекта массива fields.
  • type - сокращенное нормализованное наименование типа адресного объекта, размещенного на соответствующем уровне адреса. Данный атрибут является аналогом JSON-элемента type в составе JSON-объекта массива fields.
  • ns - число от 0 до 1, дающее количественную оценку похожести имени адресного объекта в исходном запросе на нормализованное имя адресного объекта, возвращенное в атрибуте name. Атрибут ns является аналогом JSON-элемента ns в составе JSON-объекта массива fields.
  • ts - число от 0 до 1, дающее количественную оценку похожести типа адресного объекта в исходном запросе на нормализованное имя типа адресного объекта в атрибуте type. Атрибут ts является аналогом JSON-элемента ts в составе JSON-объекта массива fields.
  • c - число, отражающее уникальный код адресного объекта в пределах его родителя по классификатору адресов КЛАДР.
  • st - число, отражающее административный статус адресного объекта. Возможные значения статуса аналогичны значениям, возвращаемым сервисом в JSON-элементе st в составе JSON-объекта массива fields.

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

Элемент Field может содержать дочерний текстовый элемент, обрамленный секцией CDATA, в которой сервис возвращает фрагмент исходного обработанного текста, на основании которого было выполнено распознавание данного поля адреса. Эта информация выводится только для тех полей, которые реально были распознаны в исходном тексте. Поля адреса, информация по которым была лишь восстановлена, но не распознана в исходном тексте, секцией CDATA не снабжаются. Информация, выводимая в данную секцию CDATA, аналогична информации, выводимой в JSON-элемент cover в составе JSON-объекта массива fields.

XML-элемент Cover: покрытия адресных полей

Данный элемент является дочерним по отношению к элементу Address и предоставляет информацию о границах покрытия распознанного адреса в рамках исходного обработанного текста. Информация, выводимая в данном элементе, аналогична информации, выводимой в JSON-массиве cover в составе JSON-объекта, соответствующего одному варианту распознавания адреса. Пример XML-элемента Cover приведен ниже.

<Cover>
  <![CDATA[<b>москва</b> <b>ул. ткацкая</b> <b>д.5</b> 
  вход справа от магазина]]>
</Cover>

Текст данного элемента содержит секцию CDATA, в которой выводится исходная обработанная строка адреса, в которой разделителем <b> отмечена позиция, после которой в строке следуют слова распознанного поля адреса, а разделителем </b> отмечена позиция, на которой заканчиваются слова распознанного поля адреса. С помощью данных разделителей исходная строка может быть представлена в следующем виде.

    слова вне адреса <b>слова части адреса</b> слова вне адреса

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

XML-элемент GeoData: GPS-координаты адреса

Данный элемент является дочерним по отношению к элементу Address и предоставляет информацию о географических координатах обработанного адреса. В рамках этого элемента сервис возвращает широту и долготу серединной точки адресного объекта, а также координаты нижней и верхней границы охватывающей адресный объект области. Информация, выводимая в данном элементе, аналогична информации, выводимой в JSON-объекте geo_data. Пример XML-элемента GeoData приведен ниже.

<GeoData rel="100" object_level="Street" house_level="House">
  <Mid lat="55.7864431" lon="37.7219992"/>
  <Min lat="55.7853957" lon="37.7221214"/>
  <Max lat="55.7865962" lon="37.7331519"/>
</GeoData>

Элемент GeoData содержит следующие дочерние элементы.

  • Mid - элемент, в атрибутах lat и lon которого сервис возвращает широту и долготу серединной точки адресного объекта. Информация, выводимая в данном элементе, аналогична информации, выводимой в элементе mid JSON-объекта geo_data.
  • Min - элемент, в атрибутах lat и lon которого сервис возвращает широту и долготу нижней границы адресного объекта. Информация, выводимая в данном элементе, аналогична информации, выводимой в элементе min JSON-объекта geo_data.
  • Max - элемент, в атрибутах lat и lon которого сервис возвращает широту и долготу верхней границы адресного объекта. Информация, выводимая в данном элементе, аналогична информации, выводимой в элементе max JSON-объекта geo_data.

Элемент GeoData снабжается следующими атрибутами.

  • rel - число от 0 до 100, отражающее достоверность возвращаемых координат. Данный атрибут аналогичен элементу rel JSON-объекта geo_data.
  • object_level - имя уровня адресного объекта в составе распознанного адреса, для которого удалось выполнить определение координат нижней и верхней границы Min и Max. Данный атрибут может принимать значения от Region до Street. Данный атрибут аналогичен элементу object_level JSON-объекта geo_data.
  • house_level - атрибут принимает значение House в случае, если в обработанном адресе присутствует номер дома и этот дом удалось найти на карте. В этом случае координаты серединной точки Mid содержат широту и долготу дома. Если в исходном адресе не указан номер дома, или если на карте этот дом отсутствует, атрибут house_level не возвращается в составе GeoData, при этом координаты серединной точки Mid будут содержать широту и долготу адресного объекта, уровень которого указан в атрибуте object_level. Данный атрибут аналогичен элементу house_level JSON-объекта geo_data.

XML-элемент Codes: справочные коды адреса

Данный элемент является дочерним по отношению к элементу Address и содержит информацию о дополнительных кодах, присвоенных адресу различными справочниками. В настоящий момент поддерживаются коды классификатора КЛАДР, ФИАС, ОКАТО, ОКТМО и коды ИФНС. При разработке веб-приложения, использующего информацию данного XML-элемента, необходимо учитывать, что состав его дочерних элементов в будущем может быть расширен, если сервис начнет поддерживать коды других классификаторов. Информация, выводимая в рамках данного элемента, аналогична информации, выводимой в JSON-объекте codes. Пример XML-элемента Codes приведен ниже.

<Codes>
  <KLADR val="770000000002908"/>
  <FIAS object="e998a78a-bd5a-44f4-81ce-cb2b78f2997b" 
        object_level="Street" 
        house="ffd3eaa6-0731-413f-b2e3-c4111e999ca5" 
        house_precise="0"
        Region="0c5b2444-70a0-4932-980c-b4dc0d3f02b5"/>
  <OKATO val="45298578001"/>
  <OKTMO val="45931000"/>
  <IFNS_FL val="7751"/>
  <IFNS_UL val="7751"/>
</Codes>

Элемент Codes содержит следующие дочерние элементы.

  • KLADR - содержит информацию об актуальном коде КЛАДР обработанного адреса до уровня улиц включительно. Значение кода КЛАДР возвращается посредством атрибута val данного XML-элемента. Информация, выводимая в данном элементе, аналогична информации, выводимой в JSON-объекте kladr_actual.
  • FIAS - содержит информацию о кодах ФИАС для обработанного адреса. Данный элемент может иметь следующие атрибуты.
    • object – содержит код ФИАС для адресного объекта самого нижнего заполненного нечислового поля адреса, например, для улицы. Данный атрибут аналогичен элементу fias_object JSON-объекта codes.
    • object_level - содержит название уровня, которому принадлежит объект адреса, код которого возвращен в рамках атрибута object. Данный атрибут аналогичен элементу fias_object_level JSON-объекта codes.
    • house – содержит код номера дома по классификатору ФИАС, если дом присутствует в адресе. Данный атрибут аналогичен элементу fias_house JSON-объекта codes.
    • house_precise - принимает значение 1, если номер дома точно найден в ФИАС. Если номер дома найден неточно, то атрибут примет значение 0. Данный атрибут аналогичен элементу fias_house_precise JSON-объекта codes.
    • Region, District, City, Place - содержат коды ФИАС для полей адреса на уровне региона, района, города и населённого пункта соответственно. Данные атрибуты возвращаются сервисом только в случае использования в запросе опции output=afiasall, а также только при фактическом наличии соответствующих полей в обработанном адресе. Данные атрибуты аналогичны элементам fias_Region, fias_District, fias_City, fias_Place JSON-объекта codes.
  • OKATO - содержит код ОКАТО, указывающий на объект административно-территориального деления, которому принадлежит адрес. Значение кода возвращается посредством атрибута val данного XML-элемента.
  • OKTMO - содержит код ОКТМО, указывающий на территорию муниципального образования, на которой находится обработанный адрес. Значение кода возвращается посредством атрибута val данного XML-элемента.
  • IFNS_FL - содержит код ИФНС, обслуживающей физических лиц по данному адресу. Значение кода возвращается посредством атрибута val данного XML-элемента.
  • IFNS_UL - содержит код ИФНС, обслуживающей юридических лиц по данному адресу. Значение кода возвращается посредством атрибута val данного XML-элемента.

XML-элемент Quality: показатели качества стандартизации

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

<Quality>
  <Precision val="100"/>
  <Recall val="100"/>
  <CanonicFields val="2"/>
  <DetectedFields val="2"/>
  <VerifiedNumericFields val="0"/>
  <Warnings val="Incomplete|HouseIsAbsent|"/>
</Quality>

Элемент Quality содержит следующие дочерние элементы.

  • Precision - содержит информацию о точности распознавания адреса. Точность распознавания представляет собой число от 0 до 100, которое является количественной мерой того, насколько исходные адресные данные соответствуют адресным объектам в составе нормализованного адреса. Чем меньше ошибок и неточностей допущено при написании исходного адреса, тем выше возвращаемое значение точности. Значение точности передается посредством атрибута val данного XML-элемента.
  • Recall - содержит информацию о полноте использования исходных адресных данных в процессе распознавания. Полнота использования исходных данных представляет собой число от 0 до 100, которое является количественной мерой того, насколько полно были задействованы текстовые данные исходного адреса при распознавании. Чем больше в исходном тексте адреса лишних неадресных данных, не участвующих в распознавании адреса, тем меньше полнота. Значение полноты возвращается посредством атрибута val данного XML-элемента.
  • CanonicFields - содержит количество канонических полей адреса, информация по которым в идеале должна была присутствовать в исходном запросе. Данный показатель учитывает только поля, соответствующие уровням адресных объектов от Region до Street. Значение данного показателя возвращается посредством атрибута val данного XML-элемента.
  • DetectedFields - содержит количество реально распознанных полей адреса в исходном запросе. Данное количество может совпадать или быть меньше количества полей, возвращаемых в элементе CanonicFields. Количество реально распознанных полей может быть меньше количества канонических полей адреса в том случае, если в исходном запросе пропущена информация о некоторых адресных полях, например, адрес записан без явного указания региона. Значение данного показателя возвращается посредством атрибута val данного XML-элемента.
  • VerifiedNumericFields - содержит количество числовых адресных полей, значения которых удалось проверить по эталонным справочникам. Например, если в исходном адресе указан номер дома, который удалось распознать и проверить на существование по справочнику КЛАДР, данный показатель примет значение 1. Значение данного показателя возвращается посредством атрибута val данного XML-элемента.
  • Warnings - содержит предупреждающие флаги, акцентирующие внимание на определенных свойствах распознанного адреса. Наличие предупреждающих флагов не обязательно свидетельствует об ошибке в адресе, тем не менее, приложение пользователя может использовать данные флаги для классификации обрабатываемых адресов или для формирования текстовых комментариев, выдаваемых конечному пользователю, выполняющему обработку адресных данных. Предупреждающие флаги возвращаются посредством атрибута val данного XML-элемента. Несколько флагов разделяются символом вертикальной черты |. Возможные значения флагов аналогичны значениям, возвращаемым сервисом в элементе warnings JSON-объекта quality.

XML-элемент CheckInfo: сводная информация о результате

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

<CheckInfo>
  <Number>0</Number>
  <String><![CDATA[на деревню дедушке]]></String>
  <Time>3</Time>
  <Alts>0</Alts>
  <Status val="NotFound|"/>
</CheckInfo>

Элемент CheckInfo содержит следующие дочерние элементы.

  • Number - содержит порядковый номер адреса в случае, когда адрес входит в состав записи из нескольких элементов разного типа, обрабатываемой, например, командой cleanse/record или cleanse/chunk. Нумерация элементов записи начинается с 0. Если адрес не является частью записи, то данный элемент не выводится.
  • String - содержит секцию CDATA, в которую сервис выводит строку с адресными данными, обработанными сервисом. В общем случае данная строка может не совпадать со строкой, которую сервис получил в исходном запросе, поскольку исходная строка может содержать символы, запрещенные для использования в рамках XML-документов. Содержимое строки String также учитывает результат предварительной очистки исходных данных, при которой сервис выполняет замену непечатных символов на пробелы, а также делает преобразования некоторых символов алфавита. Элемент String в первую очередь предназначен для контроля правильности кодировки данных, передаваемых сервису на обработку, при отладке и тестировании интеграции приложения с сервисом.
  • Time - содержит количество миллисекунд, которое потребовалось сервису на обработку исходного запроса.
  • Alts - содержит общее число альтернативных вариантов распознавания и нормализации, подобранных для исходного запроса.
  • Status - содержит информацию о причине, по которой адрес не был распознан. Значения статуса возвращаются в атрибуте val данного элемента. Возможные значения статуса аналогичны значениям, возвращаемым сервисом в элементе status JSON-объекта check_info.
версия сервиса:
© ixLab, 2007-2017, e-mail: info@ixlab.ru
обработано за 60 (мс)