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

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

Стандартизация адреса сопровождается его обогащением дополнительной информацией, такой как 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=строка запроса - строка, содержащая обрабатываемый почтовый адрес.

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

  • country=код страны - строка, с помощью которой задаётся страна, которой принадлежит обрабатываемый адрес. Название страны передаётся в виде трёхбуквенного латинского кода в нижнем регистре по справочнику ОКСМ. На данный момент поддерживаются следующие страны:
    • rus - Россия;
    • kaz - Казахстан.
  • output=pretty - опция применима только в случае использования JSON формата ответа сервиса. Данная опция требует, чтобы сервис выполнил "красивое" форматирование возвращаемого JSON текста, расставив в нем переносы строк, отступы и пробельное прореживание. Опция может быть полезна при отладке взаимодействия пользовательского приложения с сервисом.
  • output=cp1251 - опция применима только в случае использования XML формата ответа сервиса. Данная опция требует, чтобы сервис вернул XML-ответ в кодировке windows-1251.
  • input=utf8 или input=cp1251 - кодировка UTF-8 или windows-1251, в которой представлены входные данные в параметре query.
  • afilter=адресный фильтр - строка с описанием адресного фильтра, который следует применить к результату обработки почтового адреса. Подробнее об адресных фильтрах и способах их описания можно ознакомиться здесь.
  • addresslim=число - лимит на число возвращаемых вариантов распознавания адреса, в случае, если адрес является многозначным. Если в запросе данный лимит не установлен, то в качестве лимита будет выступать значение параметра "Максимальное количество вариантов для неоднозначных адресов", указанное в разделе "Профиль" личного кабинета пользователя.
  • mode=forcezip|search|weak - опции обработки почтового адреса. Можно указать одну или сразу несколько опций, разделив их вертикальной чертой. Опции имеют следующее назначение.
    • mode=forcezip - опция включает фильтрацию распознанных адресов по почтовому индексу при условии, что почтовый индекс указан в исходной адресной строке. В данном режиме сервис не будет возвращать варианты распознавания адреса, индексы которых не соответствуют индексу, указанному в исходном адресе.
    • mode=search - опция указывает на то, что при обработке адресов будут задействованы алгоритмы смарт-поиска. В данном режиме адреса обрабатываются менее строго, что позволяет выполнять исправления с достаточно сильными искажениями исходных данных. Данный режим следует использовать с осторожностью, т.к. нечеткая обработка адресных данных может привести к появлению неправильно исправленных адресов.
    • mode=weak - опция снимает некоторые ограничения, используемые по умолчанию в работе распознавателя. Например, в данном режиме сервис может распознавать адресные объекты, в именах которых в исходном обрабатываемом тексте пропущены цифры.
  • output=acover|ageo |acodes|adict|afiasall |aqual|apretty|status |ainabr|astations|apostoffice |timezone|acountry|agar|aprop - опции, включающие в ответ сервиса дополнительную информацию об обработанном адресе. Можно указать одну или сразу несколько опций, разделив их вертикальной чертой. Опции имеют следующее назначение.
    • 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-ответах блок со статусом результата обработки, объясняющим причину отбраковки адреса".
    • output=ainabr - при использовании данной опции сервис возвращает адрес в формате АБР классификатора, совместимого с классификатором ФИАС. В противном случае адрес будет возвращаться в формате КЛАДР. Кроме этого в составе ответа сервиса будут возвращаться дополнительные коды по классификаторам АБР и ФИАС. Данную опцию можно не указывать, если в личном кабинете пользователя в разделе "Профиль" установить флажок "В API и реестрах приводить почтовые адреса к структуре АБР/ФИАС, а не КЛАДР".
    • output=aareas - при использовании данной опции для успешно обработанного адреса сервис будет возвращать информацию о принадлежности адреса району и административному округу города, а также окружной кольцевой дороге. Данная информация возвращается только при условии, что город, в котором находится адрес, допускает деление на районы и/или округа. Информация о кольцевой дороге возвращается, если адрес находится внутри или рядом с городом, вокруг которого имеется кольцевая дорога. Данную опцию можно не указывать, если в личном кабинете пользователя в разделе "Профиль" установить флажок "Возвращать в API-ответах блок с городским районом и округом адреса".
    • output=astations - при использовании данного параметра для успешно обработанного адреса сервис возвращает ближайшие станции метро и станции скоростного легкорельсового транспорта. Данную опцию можно не указывать, если в личном кабинете пользователя в разделе "Профиль" установить флажок "Возвращать в API-ответах блок с ближайшими до адреса станциями".
    • output=apostoffice – данный параметр сообщает сервису, что для обработанного адресе нужно найти ближайшее почтовое отделение и включить информацию о нём в ответ сервиса. Данную опцию можно не указывать, если в личном кабинете пользователя в разделе "Профиль" установить флажок "Возвращать в API-ответах информацию о почтовом отделении адреса".
    • output=timezone – опция сообщает сервису, что при обработке адреса или телефона нужно определить его часовую зону и вернуть эту информацию в ответе сервиса. Данную опцию можно не указывать, если в личном кабинете пользователя в разделе "Профиль" установить флажок "Возвращать в API-ответах информацию о часовой зоне адреса/телефона".
    • output=acountry – опция включает в выдачу с результатом обработки адреса информацию о стране, которой он принадлежит. Данную опцию можно не указывать, если в личном кабинете пользователя в разделе "Профиль" установить флажок "Возвращать в API-ответах информацию о стране, которой принадлежит адрес".
    • output=agar – данную опцию следует использовать только совместно с опцией acodes, она позволяет включить в состав возвращаемых классификационных кодов дополнительные идентификаторы адреса по Государственному Адресному Реестру (ГАР) и кадастровые номера объектов недвижимости.
    • output=aprop – опция включает вывод в результат обработки адреса информацию с дополнительными свойствами адреса, например, сведения о количестве квартир или помещений в доме.

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

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

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;country=rus

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

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

Поиск адреса по координатам - обратное геокодирование

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

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

Например, чтобы найти адреса в радиусе 50 метров вокруг Исторического музея на Красной площади в Москве, необходимо сформировать следующий запрос.

query=55.7553225 37.6177266 50

Здесь число 55.7553225 задаёт широту искомого адреса, а число 37.6177266 - его долготу. Число 50 задаёт радиус окрестности, в пределах которой ведётся поиск. Значение радиуса не может превышать лимита, заданного администратором сервиса. На текущий момент этот лимит составляет 1000 метров.

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

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

Данный ответ получен при всех включенных флажках в "Профиле" в секции "Настройка API ответов". Также при формировании этого ответа использовалась опция output=adict, чтобы сервис вернул расширенную информацию о кодах адреса по справочникам.

    {
      "addresses" : [
        {
          "areas" : {
            "admin_area" : {
              "name" : "Соколиная Гора",
              "type" : "район"
            },
            "admin_okrug" : {
              "name" : "Восточный",
              "type" : "административный округ"
            },
            "ring_road" : {
              "in_ring" : true,
              "name" : "Московская кольцевая автомобильная дорога",
              "short" : "МКАД"
            }
          },
          "codes" : {
            "abr_actual_code" : "77s2908",
            "abr_detected_code" : "77s2908",
            "fias_actual_code" : "7700000000000002908",
            "fias_house" : "ffd3eaa6-0731-413f-b2e3-c4111e999ca5",
            "fias_house_precise" : false,
            "fias_object" : "e998a78a-bd5a-44f4-81ce-cb2b78f2997b",
            "fias_object_level" : "Street",
            "gar_Region" : "1405113",
            "gar_house" : "67493396",
            "gar_object" : "1403234",
            "ifns_fl" : "7719",
            "ifns_ul" : "7719",
            "kladr_actual_code" : "770000000002908",
            "okato" : "45263588000",
            "oktmo" : "45314000",
            "sign" : "77s2908htдомhv5"
          },
          "country" : {
            "code" : "643",
            "name" : "РОССИЯ",
            "sign" : "RUS"
          },
          "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"
            },
            {
              "level" : "Site"
            },
            {
              "c" : "2908",
              "cover" : "ул. ткацкая",
              "level" : "Street",
              "name" : "Ткацкая",
              "ns" : 1.00,
              "ts" : 1.00,
              "type" : "ул"
            },
            {
              "c" : "1",
              "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
          },
          "post_office" : {
            "dist" : 0.59,
            "lat" : 55.7829912,
            "lon" : 37.7302626,
            "pretty" : "г Москва, ул Щербаковская, дом 35",
            "sign" : "77s3172hдом:35"
          },
          "stations" : [
            {
              "dist" : 0.32,
              "lat" : 55.7834195,
              "line" : "Арбатско-Покровская",
              "lon" : 37.7212469,
              "name" : "Семёновская",
              "net" : "ГУП Московский метрополитен",
              "type" : "Subway"
            },
            {
              "dist" : 1.22,
              "lat" : 55.7964038,
              "line" : "Сокольническая",
              "lon" : 7.7155476,
              "name" : "Преображенская площадь",
              "net" : "ГУП Московский метрополитен",
              "type" : "Subway"
            },
            {
              "dist" : 1.28,
              "lat" : 55.7818157,
              "line" : "Арбатско-Покровская",
              "lon" : 37.7036976,
              "name" : "Электрозаводская",
              "net" : "ГУП Московский метрополитен",
              "type" : "Subway"
            },
            {
              "dist" : 1.34,
              "lat" : 55.7897913,
              "line" : "",
              "lon" : 37.7432130,
              "name" : "Измайлово",
              "net" : "МЦК",
              "type" : "LightRail"
            },
            {
              "dist" : 2.16,
              "lat" : 55.7713304,
              "line" : "",
              "lon" : 37.7450661,
              "name" : "Соколиная Гора",
              "net" : "МЦК",
              "type" : "LightRail"
            },
            {
              "dist" : 2.47,
              "lat" : 55.8041340,
              "line" : "",
              "lon" : 37.7460048,
              "name" : "Локомотив",
              "net" : "МЦК",
              "type" : "LightRail"
            }
          ],
          "time_zone" : {
            "msk_zone" : "MSK+0",
            "name" : "Московское время",
            "utc_zone" : "UTC+3"
          },
          "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-ответах информацию о кодах адреса по справочникам (например, КЛАДР)".
  • country - JSON-объект, с помощью которого сервис возвращает информацию о стране, которой принадлежит обработанный адрес. Данный объект возвращается, если в исходном запросе предварительно указан параметр output=acountry, либо если в "Профиле" личного кабинета выставлен флажок "Возвращать в API-ответах информацию о стране, которой принадлежит адрес".
  • areas - JSON-объект, в котором приведена информация о принадлежности адреса району и административному округу города, а также окружной кольцевой дороге. Данный объект возвращается, если в исходном запросе предварительно указан параметр output=aareas, либо если в "Профиле" личного кабинета выставлен флажок "Возвращать в API-ответах блок с городским районом и округом адреса". Данный объект не возвращается в случае, если обработанный адрес принадлежит небольшому населённому пункту без внутреннего деления на районы или округа. Информация о кольцевой дороге возвращается, только если адрес находится внутри или рядом с городом, вокруг которого имеется кольцевая дорога.
  • stations – JSON-массив, элементы которого содержат информацию о ближайших станциях метро и станциях скоростного легкорельсового транспорта. Данный массив возвращается, если в исходном запросе предварительно указан параметр output=astations, либо если в "Профиле" личного кабинета установлен флажок "Возвращать в API-ответах блок с ближайшими до адреса станциями". Данный массив не возвращается в случае, если обработанный адрес принадлежит населённому пункту, в котором не представлены данные виды транспорта.
  • post_office – JSON-объект, содержащий информацию о ближайшем до адреса почтовом отделении. Данный объект возвращается, если в запросе указан параметр output=apostoffice, либо если в "Профиле" личного кабинета выставлен флажок "Возвращать в API-ответах информацию о почтовом отделении адреса". Данный объект не возвращается в случае, если для обработанного адреса не удалось найти информацию о ближайшем почтовом отделении.
  • time_zone – JSON-объект, содержащий информацию о часовой зоне, которой принадлежит адрес. Данный объект возвращается, если в запросе указан параметр output=timezone, либо если в "Профиле" личного кабинета выставлен флажок "Возвращать в 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 - поле соответствует уровню населенных пунктов.
    • Site - поле соответствует уровню территорий, таких как садоводческие товарищества, промышленные зоны, кварталы и гаражные кооперативы.
    • 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 - строка, отражающая уникальный код адресного объекта в пределах его родителя по классификатору адресов АБР/ФИАС. Данный элемент не выводится для незаполненных адресных полей. Для номера дома в это поле выводится значение 1, если дом успешно найден в ФИАС. Если дом не найден в ФИАС, то для него данный элемент не выводится.
  • 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-объект areas: городской район и округ адреса

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

    "areas" : {
      "admin_area" : {
        "name" : "Южное Бутово",
        "type" : "район"
      },
      "admin_okrug" : {
        "name" : "Юго-Западный",
        "type" : "административный округ"
      },
      "ring_road" : {
        "dist" : 3.80,
        "in_ring" : false,
        "name" : "Московская кольцевая автомобильная дорога",
        "short" : "МКАД"
      }
    }

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

  • admin_okrug - JSON-объект с информацией об административном округе города, которому принадлежит адрес. Данный объект заполняется для городов с двухуровневым административно-территориальным делением. В настоящий момент такое деление предусмотрено только для г Москвы. Для остальных городов данный объект не выводится.
  • admin_area - JSON-объект с информацией о внутригородском районе, которому принадлежит адрес. Данный объект заполняется для всех крупных городов, у которых предусмотрено деление на районы.
  • ring_road – JSON-объект с информацией о ближайшей к адресу городской кольцевой дороге и о том, располагается ли адрес в пределах её кольца. На данный момент сервис поддерживает данные о кольцевой дороге вокруг Москвы (МКАД) и Санкт-Петербурга (КАД). Объект содержит следующие элементы.
    • name - строка, содержащая полное название кольцевой дороги.
    • short - строка, содержащая краткое название кольцевой дороги, например, МКАД.
    • in_ring - элемент булевского типа, значение true указывает на то, что обработанный адрес находится в пределах кольцевой дороги.
    • dist - расстояние в километрах от обработанного адреса до кольцевой дороги, данный элемент возвращается только если адрес лежит за пределами кольца, т.е. имеет место in_ring = false.

Оба JSON-объекта admin_okrug и admin_area содержат название и тип городского района или округа. Для этого используются следующие элементы этих объектов.

  • name - строка, содержащая название округа или района города.
  • type - строка, содержащее название типа округа или района города, например: территориальный округ, административный округ, район и др.

JSON-массив stations: ближайшие станции метро

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

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

  "stations" : [
    {
      "dist" : 0.32,
      "lat" : 55.7834195,
      "line" : "Арбатско-Покровская",
      "lon" : 37.7212469,
      "name" : "Семёновская",
      "net" : "ГУП Московский метрополитен",
      "type" : "Subway"
    },
    {
      "dist" : 1.22,
      "lat" : 55.7964038,
      "line" : "Сокольническая",
      "lon" : 7.7155476,
      "name" : "Преображенская площадь",
      "net" : "ГУП Московский метрополитен",
      "type" : "Subway"
    },
    {
      "dist" : 1.28,
      "lat" : 55.7818157,
      "line" : "Арбатско-Покровская",
      "lon" : 37.7036976,
      "name" : "Электрозаводская",
      "net" : "ГУП Московский метрополитен",
      "type" : "Subway"
    },
    {
      "dist" : 1.34,
      "lat" : 55.7897913,
      "line" : "",
      "lon" : 37.7432130,
      "name" : "Измайлово",
      "net" : "МЦК",
      "type" : "LightRail"
    },
    {
      "dist" : 2.16,
      "lat" : 55.7713304,
      "line" : "",
      "lon" : 37.7450661,
      "name" : "Соколиная Гора",
      "net" : "МЦК",
      "type" : "LightRail"
    },
    {
      "dist" : 2.47,
      "lat" : 55.8041340,
      "line" : "",
      "lon" : 37.7460048,
      "name" : "Локомотив",
      "net" : "МЦК",
      "type" : "LightRail"
    }
  ]

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

  • type – тип транспорта, к которому относится данная станция. Элемент может принимать одно из следующих значений.
    • Subway – станция метро.
    • LightRail – станция скоростного легкорельсового транспорта.
  • name – название станции.
  • line – названии линии или ветки, которой принадлежит станция в рамках транспортной сети. Может быть пустым, если транспортная сеть не предусматривает деления на линии.
  • net – название транспортной сети, которой принадлежит станция.
  • lat – географическая широта станции.
  • lon – географическая долгота станции.
  • dist – расстояние в километрах от адреса до станции.

JSON-объект post_office: ближайшее к адресу почтовое отделение

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

"post_office" : {
    "dist" : 0.51,
    "lat" : 55.5481112,
    "lon" : 37.5455371,
    "pretty" : "г Москва, ул Венёвская, дом 3А",
    "sign" : "77s3982hдом:3А"
  }

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

  • pretty – строковое представление адреса почтового отделения.
  • sign – сигнатура адреса почтового отделения. Данную сигнатуру можно использовать в рамках команды fetch/address, чтобы получить полную информацию об адресе почтового отделения.
  • dist – расстояние в километрах от обработанного адреса до почтового отделения.
  • lat и lon – географические координаты (широта и долгота) почтового отделения.

JSON-объект time_zone: часовая зона почтового адреса

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

"time_zone" : {
    "msk_zone" : "MSK-1",
    "name" : "Калининградское время",
    "utc_zone" : "UTC+2"
  }

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

  • name – неофициальное название часовой зоны, которой принадлежит адрес.
  • msk_zone – часовая зона адреса, заданная относительно московского времени. Записывается в формате MSK+N или MSK-N, где N – количество часов, на которые местное время адреса сдвинуто относительно московского времени.
  • utc_zone – часовая зона адреса, заданная относительно всемирного координатного времени (UTC). Записывается в формате UTC+N или UTC-N, где N – количество часов, на которые местное время адреса сдвинуто относительно UTC.

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

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

    "codes" : {
      "abr_actual_code" : "77s2908",
      "abr_detected_code" : "77s2908",
      "cad_flat" : "77:03:0003016:7600",
      "cad_house" : "77:03:0003017:1114",
      "fias_Region" : "0c5b2444-70a0-4932-980c-b4dc0d3f02b5",
      "fias_actual_code" : "7700000000000002908",
      "fias_flat" : "0356fd88-f317-4e8f-8012-8fb090589ed1",
      "fias_house" : "45379b10-20c1-4a8b-9374-1789ca7aff17",
      "fias_house_class" : "House",
      "fias_house_precise" : true,
      "fias_object" : "e998a78a-bd5a-44f4-81ce-cb2b78f2997b",
      "fias_object_level" : "Street",
      "gar_Region" : "1405113",
      "gar_flat" : "67615114",
      "gar_house" : "67612378",
      "gar_object" : "1403234",
      "ifns_fl" : "7719",
      "ifns_ul" : "7719",
      "kladr_actual_code" : "770000000002908",
      "okato" : "45263588000",
      "oktmo" : "45314000",
      "sign" : "77s2908hдом:1fпомещение:1П"
    }

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

  • abr_actual_code – классификационный АБР-код актуальной версии адреса, указывающий на объект, принадлежащий самому нижнему полю адреса, например, улице.
  • abr_detected_code – классификационный АБР-код распознанной версии адреса. Данный код может отличаться от кода, приведенного в элементе abr_actual_code в случае, если в исходном запросе был указан устаревший адрес. В этом случае в abr_detected_code будет записан код устаревшего адреса, а в элемент abr_actual_code будет записан код адреса, являющегося его настоящей актуальной версией.
  • cad_flat – кадастровый номер квартиры или помещения. Возвращается в случае, если в исходном адресе присутствует квартира или помещение и при этом для данной квартиры удалось найти информацию о её кадастровом номере в базе сервиса. Данный элемент возвращается сервисом только в случае использования в запросе опции output=agar.
  • cad_house – кадастровый номер дома или земельного участка. Возвращается в случае, если в исходном адресе присутствует номер дома или земельного участка и при этом для данного дома удалось найти информацию о его кадастровом номере в базе сервиса. Данный элемент возвращается сервисом только в случае использования в запросе опции output=agar.
  • fias_actual_code – классификационный ФИАС-код актуальной версии адреса до уровня улиц включительно.
  • kladr_actual_code - строка, содержащая актуальный классификационный КЛАДР-код адреса до улицы включительно.
  • fias_object – строка, содержащая код ФИАС для адресного объекта самого нижнего заполненного нечислового поля адреса, например, для улицы.
  • fias_object_level – строка содержит название уровня, которому принадлежит объект адреса, код которого возвращен в рамках fias_object. Данный элемент может принимать значения от Region до Street, описание которых приводилось ранее для значений элемента level JSON-объекта, описывающего отдельное адресное поле.
  • fias_flat – строка, содержащая идентификатор номера квартиры или офиса по классификатору ФИАС, если квартира присутствует в адресе. Если в адресе отсутствует номер квартиры, либо если указанный в адресе номер не найден в ФИАС, то данный элемент не будет выводиться в ответе сервиса.
  • fias_house – строка, содержащая идентификатор номера дома по классификатору ФИАС, если дом присутствует в адресе. Если в адресе отсутствует номер дома, либо если указанный в адресе номер дома не найден в ФИАС, то данный элемент не будет выводиться в ответе сервиса.
  • fias_house_class – строка, сообщающая класс, к которому принадлежит номер дома данного адреса. Может принимать одно из следующих значений:
    • House - обычный дом.
    • Stead - земельный участок.
  • fias_house_precise – элемент булевского типа принимает значение true, если номер дома и квартиры точно найден в ФИАС. Если номер дома и/или квартиры найден неточно, то элемент примет значение false. Дом может быть найден неточно, например, если в ФИАС указан не конкретный номер, а диапазон домов, в который попадает дом из обработанного адреса. Также дом может быть найден неточно, если между его записью в исходном адресе и записью дома в ФИАС будет выявлено одно из следующих отличий:
    • отличие в буквенной части, например, "дом 5" и "дом 5А".
    • отличие в дробной части, например, "дом 5" и "дом 5/3".
    • отличие в строении, например, "дом 5" и "дом 5 стр 3".
    • отличие в корпусе, например, "дом 5" и "дом 5 корп 3".
  • fias_Region, fias_District, fias_City, fias_Place, fias_Site – строки, содержащие идентификаторы ФИАС для полей адреса на уровне региона, района, города, населённого пункта и территории соответственно. Данные элементы возвращаются сервисом только в случае использования в запросе опции output=afiasall, а также только при фактическом наличии соответствующих полей в обработанном адресе.
  • gar_object – строка, содержащая ГАР-идентификатор для адресного объекта самого нижнего заполненного нечислового поля адреса, например, для улицы. Данный элемент возвращается сервисом только в случае использования в запросе опции output=agar.
  • gar_flat – строка, содержащая ГАР-идентификатор номера квартиры, если квартира присутствует в адресе. Если в адресе отсутствует номер квартиры, либо если указанный в адресе номер не найден в ГАР, то данный элемент не будет выводиться в ответе сервиса. Данный элемент возвращается сервисом только в случае использования в запросе опции output=agar.
  • gar_house – строка, содержащая ГАР-идентификатор номера дома, если дом присутствует в адресе. Если в адресе отсутствует номер дома, либо если указанный в адресе номер дома не найден в ГАР, то данный элемент не будет выводиться в ответе сервиса. Данный элемент возвращается сервисом только в случае использования в запросе опции output=agar.
  • gar_Region, gar_District, gar_City, gar_Place, gar_Site – строки, содержащие идентификаторы по Государственному Адресному Реестру (ГАР) для полей адреса на уровне региона, района, города, населённого пункта и территории соответственно. Данные элементы возвращаются сервисом только в случае использования в запросе опций output=afiasall|agar, а также только при фактическом наличии соответствующих полей в обработанном адресе.
  • ifns_fl – строка содержит код ИФНС, обслуживающей физических лиц по данному адресу.
  • ifns_ul – строка содержит код ИФНС, обслуживающей юридических лиц по данному адресу.
  • okato – строка, содержащая код ОКАТО, указывающий на объект административно-территориального деления, которому принадлежит адрес.
  • oktmo – строка, содержащая код ОКТМО, указывающий на территорию муниципального образования, на которой находится обработанный адрес.
  • sign – строка с уникальной сигнатурой адреса. Сигнатура однозначно идентифицирует данный адрес в рамках сервиса, также её можно использовать в дальнейшем в качестве запроса в команде fetch/address для повторного получения информации об адресе.

JSON-объект country: страна, которой принадлежит адрес

Объект addresses[i].country содержит информацию о стране, которой принадлежит i-ый адрес массива addresses. Пример JSON-объекта country приведен ниже.

    "country" : {
        "code" : "398",
        "name" : "КАЗАХСТАН",
        "sign" : "KAZ"
      }

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

  • code – цифровой код страны по справочнику ОКСМ.
  • name – краткое название страны.
  • sign – трёхбуквенный латинский код страны.

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-объект property: дополнительные свойства адреса

Объект addresses[i].property содержит дополнительные свойства i-ого адреса массива addresses. Пример JSON-объекта property приведен ниже.

    "property" : {
        "house_flats_amount" : 123
    }

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

  • house_flats_amount - количество квартир в доме, если в обработанном адресе указан существующий номер дома.

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 - исходный адрес был распознан по некоторому фрагменту исходного запроса, при этом в процессе обработки сервис обнаружил другие важные адресные фрагменты, которые не удалось использовать при распознавании, в результате адрес был отбракован. Данный случай соответствует, например, ситуации, когда в адресе указано по ошибке название региона, не соответствующее остальной части адреса.
    • FilteredByZip - признак присваивается адресу, если он был отбракован из-за того, что исходный почтовый индекс, присутствующий в обработанном адресе, не соответствует индексу адреса, полученному в результате стандартизации.
    • FilteredUnstableDetection - признак присваивается адресу, если адрес был отбракован из-за того, что некоторые его поля (как правило, улица или населённый пункт) не удаётся распознать достаточно уверенно. Например, в адресе может быть указано неточное название промзоны без явного указания на то, что имеется в виду именно территория такого типа, а не одноимённая улица. В таком случае адрес будет отбракован и помечен данным признаком.
    • FilteredByUser - признак присваивается адресу, если он был отбракован в результате применения пользовательского фильтра, заданного в разделе "Фильтры адресов" личного кабинета, либо полученного непосредственно в рамках API-запроса.
    • AbnormalDetection - признак присваивается адресу, если он был отбракован из-за того, что его распознавание было выполнено только с привлечением вспомогательной информации, такой как почтовый индекс, без которой распознавание было бы невозможным. При этом даже в результате использования такой информации результат распознавания оказался неоднозначным, в результате чего адрес был отбракован.
  • 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="Site" 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>
    <Areas>
      <AdminOkrug name="Восточный" type="административный округ"/>
      <AdminArea name="Соколиная Гора" type="район"/>
      <RingRoad name="Московская кольцевая автомобильная дорога"
                short="МКАД" in_ring="1"/>
    </Areas>
    <Stations>
      <Subway name="Семёновская" line="Арбатско-Покровская" 
              net="ГУП Московский метрополитен" 
              lat="55.7834195" lon="37.7212469" dist="0.32"/>
      <Subway name="Преображенская площадь" line="Сокольническая" 
              net="ГУП Московский метрополитен" 
              lat="55.7964038" lon="37.7155476" dist="1.22"/>
      <Subway name="Электрозаводская" line="Арбатско-Покровская" 
              net="ГУП Московский метрополитен" 
              lat="55.7818157" lon="37.7036976" dist="1.28"/>
      <LightRail name="Измайлово" line="" net="МЦК" 
                 lat="55.7897913" lon="37.7432130" dist="1.34"/>
      <LightRail name="Соколиная Гора" line="" net="МЦК" 
                 lat="55.7713304" lon="37.7450661" dist="2.16"/>
      <LightRail name="Локомотив" line="" net="МЦК" 
                 lat="55.8041340" lon="37.7460048" dist="2.47"/>
    </Stations>
    <PostOffice sign="77s3172hдом:35" 
                pretty="г Москва, ул Щербаковская, дом 35" 
                dist="0.59" lat="55.7829912" lon="37.7302626"/>
    <TimeZone utc_zone="UTC+3" msk_zone="MSK+0" 
              name="Московское время"/>
    <Codes>
      <ABR actual="77s2908" detected="77s2908"/>
      <Sign val="77s2908htдомhv5"/>
      <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"/>
      <GAR object="1403234" house="67493396" Region="1405113"/>
    </Codes>
    <Country name="КАЗАХСТАН" code="398" sign="KAZ"/>
    <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.
  • Areas – содержит информацию о городском районе и округе, а также окружной кольцевой дороге, которым принадлежит обработанный адрес. Данный элемент является аналогом JSON-объекта areas, возвращаемого в ответе сервиса в формате JSON.
  • Stations – содержит список ближайших станций метро и станций скоростного легкорельсового транспорта. Данный элемент является аналогом JSON-объекта stations, возвращаемого в ответе сервиса в формате JSON.
  • PostOffice – содержит информацию о ближайшем до адреса почтовом отделении. Данный элемент является аналогом JSON-объекта post_office, возвращаемого в ответе сервиса в формате JSON.
  • TimeZone – содержит информацию о часовой зоне почтового адреса. Данный элемент является аналогом JSON-объекта time_zone, возвращаемого в ответе сервиса в формате JSON.
  • Codes - предоставляет информацию о кодах, приписанных адресу различными справочниками, например, классификатором КЛАДР и ФИАС. Данный элемент является аналогом JSON-объекта codes, возвращаемого в ответе сервиса в формате JSON.
  • Country - предоставляет информацию о стране, которой принадлежит адрес. Данный элемент является аналогом JSON-объекта country, возвращаемого в ответе сервиса в формате 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 - число, отражающее уникальный код адресного объекта в пределах его родителя по АБР-классификатору адресов. Для адресного поля с номером дома данный атрибут принимает значение 1, если номер дома удалось найти в ФИАС. В противном случае для номера дома данный атрибут не возвращается.
  • 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-элемент Areas: район и округ города

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

<Areas>
  <AdminOkrug name="Юго-Западный" type="административный округ"/>
  <AdminArea name="Южное Бутово" type="район"/>
  <RingRoad name="Московская кольцевая автомобильная дорога"
            short="МКАД" in_ring="0" dist="3.80"/>
</Areas>

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

  • AdminOkrug – содержит информацию об административном округе города, которому принадлежит адрес. Данный объект заполняется для городов с двухуровневым административно-территориальным делением. В настоящий момент такое деление предусмотрено только для г Москвы. Для остальных городов данный объект не выводится. Название административного округа выводится с помощью атрибута name, а его тип – с помощью атрибута type. Информация, выводимая в данном элементе, аналогична информации, выводимой в JSON-объекте admin_okrug.
  • AdminArea – содержит информацию о внутригородском районе, которому принадлежит адрес. Данный объект заполняется для всех крупных городов, у которых предусмотрено деление на районы. Название района выводится с помощью атрибута name, а его тип – с помощью атрибута type. Информация, выводимая в данном элементе, аналогична информации, выводимой в JSON-объекте admin_area.
  • RingRoad – содержит информацию о ближайшей к адресу городской кольцевой дороге и о том, располагается ли адрес в пределах её кольца. Вся информация о кольцевой передаётся посредством следующих атрибутов.
    • name – полное название кольцевой дороги;
    • short – краткое название кольцевой дороги, например, МКАД;
    • in_ring – атрибут принимает значение 1, если обработанный адрес находится в пределах кольцевой дороги;
    • dist – расстояние в километрах от обработанного адреса до кольцевой дороги, данный элемент возвращается только если адрес лежит за пределами кольца, т.е. имеет место in_ring = "0".

    XML-элемент Stations: ближайшие станции метро

    Данный элемент является дочерним по отношению к элементу Address и содержит информацию о ближайших к адресу станциях метро и станциях скоростного легкорельсового транспорта. При разработке веб-приложения, использующего информацию данного XML-элемента, необходимо учитывать, что состав его дочерних элементов в будущем может быть расширен, если сервис начнет поддерживать дополнительные разновидности транспорта. Данный элемент возвращается сервисом, если в исходном запросе предварительно указан параметр output=astations, либо если в "Профиле" личного кабинета установлен флажок "Возвращать в API-ответах блок с ближайшими до адреса станциями".

    Информация, выводимая в рамках данного элемента, аналогична информации, выводимой в JSON-массиве stations. Пример XML-элемента Stations приведен ниже.

    <Stations>
      <Subway name="Семёновская" line="Арбатско-Покровская" 
              net="ГУП Московский метрополитен" 
              lat="55.7834195" lon="37.7212469" dist="0.32"/>
      <Subway name="Преображенская площадь" line="Сокольническая" 
              net="ГУП Московский метрополитен" 
              lat="55.7964038" lon="37.7155476" dist="1.22"/>
      <Subway name="Электрозаводская" line="Арбатско-Покровская" 
              net="ГУП Московский метрополитен" 
              lat="55.7818157" lon="37.7036976" dist="1.28"/>
      <LightRail name="Измайлово" line="" net="МЦК" 
                 lat="55.7897913" lon="37.7432130" dist="1.34"/>
      <LightRail name="Соколиная Гора" line="" net="МЦК" 
                 lat="55.7713304" lon="37.7450661" dist="2.16"/>
      <LightRail name="Локомотив" line="" net="МЦК" 
                 lat="55.8041340" lon="37.7460048" dist="2.47"/>
    </Stations>

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

    • Subway – элемент содержит информацию о станции метро.
    • LightRail - элемент содержит информацию о станции скоростного легкорельсового транспорта.

    Вся информация о станции передаётся посредством следующих атрибутов этих элементов.

    • name – название станции.
    • line – названии линии или ветки, которой принадлежит станция в рамках транспортной сети. Может быть пустым, если транспортная сеть не предусматривает деления на линии.
    • net – название транспортной сети, которой принадлежит станция.
    • lat – географическая широта станции.
    • lon – географическая долгота станции.
    • dist – расстояние в километрах от адреса до станции.

    XML-элемент PostOffice: ближайшее к адресу почтовое отделение

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

    <PostOffice sign="77s3982hдом:3А" 
                pretty="г Москва, ул Венёвская, дом 3А" 
                dist="0.51" lat="55.5481112" lon="37.5455371"/>

    Информация о почтовом отделении передаётся с помощью следующих атрибутов элемента PostOffice.

    • pretty – строковое представление адреса почтового отделения.
    • sign – сигнатура адреса почтового отделения. Данную сигнатуру можно использовать в рамках команды fetch/address, чтобы получить полную информацию об адресе почтового отделения.
    • dist – расстояние в километрах от обработанного адреса до почтового отделения.
    • lat и lon – географические координаты (широта и долгота) почтового отделения.

    XML-элемент TimeZone: часовая зона почтового адреса

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

    <TimeZone utc_zone="UTC+2" msk_zone="MSK-1" name="Калининградское время"/>

    Информация о часовой зоне передаётся с помощью следующих атрибутов элемента TimeZone.

    • name – неофициальное название часовой зоны, которой принадлежит адрес.
    • msk_zone – часовая зона адреса, заданная относительно московского времени. Записывается в формате MSK+N или MSK-N, где N – количество часов, на которые местное время адреса сдвинуто относительно московского времени.
    • utc_zone – часовая зона адреса, заданная относительно всемирного координатного времени (UTC). Записывается в формате UTC+N или UTC-N, где N – количество часов, на которые местное время адреса сдвинуто относительно UTC.

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

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

    <Codes>
      <ABR actual="77s2908" detected="77s2908"/>
      <Sign val="77s2908hдом:1fпомещение:1П"/>
      <KLADR val="770000000002908"/>
      <FIAS object="e998a78a-bd5a-44f4-81ce-cb2b78f2997b" 
            object_level="Street" 
            house="45379b10-20c1-4a8b-9374-1789ca7aff17" 
            house_precise="1" 
            house_class="House" 
            flat="0356fd88-f317-4e8f-8012-8fb090589ed1" 
            Region="0c5b2444-70a0-4932-980c-b4dc0d3f02b5" 
            code="7700000000000002908"/>
      <OKATO val="45263588000"/>
      <OKTMO val="45314000"/>
      <IFNS_FL val="7719"/>
      <IFNS_UL val="7719"/>
      <GAR object="1403234" house="67612378" flat="67615114" Region="1405113"/>
      <CAD house="77:03:0003017:1114" flat="77:03:0003016:7600"/>
    </Codes>

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

    • ABR - содержит информацию о классификационных АБР-кодах актуальной и распознанной версий адреса. Значение актуального АБР-кода возвращается посредством атрибута actual. Информация, выводимая в данном атрибуте, аналогична информации, выводимой в JSON-элементе abr_actual_code. Значение АБР-кода распознанной версии адреса возвращается посредством атрибута detected, оно эквивалентно информации, выводимой в JSON-элементе abr_detected_code.
    • KLADR - содержит информацию об актуальном коде КЛАДР обработанного адреса до уровня улиц включительно. Значение кода КЛАДР возвращается посредством атрибута val данного XML-элемента. Информация, выводимая в данном элементе, аналогична информации, выводимой в JSON-объекте kladr_actual_code.
    • FIAS - содержит информацию о кодах ФИАС для обработанного адреса. Данный элемент может иметь следующие атрибуты.
      • object – содержит код ФИАС для адресного объекта самого нижнего заполненного нечислового поля адреса, например, для улицы. Данный атрибут аналогичен элементу fias_object JSON-объекта codes.
      • object_level - содержит название уровня, которому принадлежит объект адреса, код которого возвращен в рамках атрибута object. Данный атрибут аналогичен элементу fias_object_level JSON-объекта codes.
      • flat – содержит идентификатор номера квартиры по классификатору ФИАС, если квартира присутствует в адресе. Данный атрибут аналогичен элементу fias_flat JSON-объекта codes.
      • house – содержит идентификатор номера дома по классификатору ФИАС, если дом присутствует в адресе. Данный атрибут аналогичен элементу fias_house JSON-объекта codes.
      • house_precise - принимает значение 1, если номер дома и квартиры (при её наличии) точно найден в ФИАС. Если номер дома и/или квартиры найден неточно, то атрибут примет значение 0. Данный атрибут аналогичен элементу fias_house_precise JSON-объекта codes.
      • house_class - содержит класс, которому принадлежит номер дома данного адреса. Данный атрибут принимает значения эквивалентные значению элемента fias_house_class JSON-объекта codes.
      • Region, District, City, Place, Site - содержат идентификаторы ФИАС для полей адреса на уровне региона, района, города, населённого пункта и территории соответственно. Данные атрибуты возвращаются сервисом только в случае использования в запросе опции output=afiasall, а также только при фактическом наличии соответствующих полей в обработанном адресе. Данные атрибуты аналогичны элементам fias_Region, fias_District, fias_City, fias_Place и fias_Site JSON-объекта codes.
      • code - содержит классификационный ФИАС-код актуальной версии адреса до уровня улиц включительно. Значение данного атрибута аналогично элементу fias_actual_code JSON-объекта codes.
    • OKATO - содержит код ОКАТО, указывающий на объект административно-территориального деления, которому принадлежит адрес. Значение кода возвращается посредством атрибута val данного XML-элемента.
    • OKTMO - содержит код ОКТМО, указывающий на территорию муниципального образования, на которой находится обработанный адрес. Значение кода возвращается посредством атрибута val данного XML-элемента.
    • IFNS_FL - содержит код ИФНС, обслуживающей физических лиц по данному адресу. Значение кода возвращается посредством атрибута val данного XML-элемента.
    • IFNS_UL - содержит код ИФНС, обслуживающей юридических лиц по данному адресу. Значение кода возвращается посредством атрибута val данного XML-элемента.
    • Sign – содержит уникальную сигнатуру адреса. Сигнатура однозначно идентифицирует данный адрес в рамках сервиса, также её можно использовать в дальнейшем в качестве запроса в команде fetch/address для повторного получения информации об адресе. Значение сигнатуры возвращается посредством атрибута val данного XML-элемента.
    • GAR - содержит информацию о ГАР-идентификаторах для обработанного адреса. Данный элемент может иметь следующие атрибуты.
      • object – содержит ГАР-идентификатор для адресного объекта самого нижнего заполненного нечислового поля адреса, например, для улицы. Данный атрибут аналогичен JSON-элементу codes.gar_object.
      • flat – содержит ГАР-идентификатор номера квартиры, если квартира присутствует в адресе. Данный атрибут аналогичен JSON-элементу codes.gar_flat.
      • house – содержит ГАР-идентификатор дома, если дом присутствует в адресе. Данный атрибут аналогичен JSON-элементу codes.gar_house.
      • Region, District, City, Place, Site - содержат ГАР-идентификаторы для полей адреса на уровне региона, района, города, населённого пункта и территории соответственно. Данные атрибуты возвращаются сервисом только в случае использования в запросе опции output=afiasall, а также только при фактическом наличии соответствующих полей в обработанном адресе. Данные атрибуты аналогичны элементам gar_Region, gar_District, gar_City, gar_Place и gar_Site JSON-объекта codes.
    • CAD - содержит информацию о кадастровом номере объекта недвижимости для обработанного адреса. Данный элемент может иметь следующие атрибуты.
      • flat – содержит кадастровый номера квартиры или помещения, если квартира присутствует в адресе. Данный атрибут аналогичен элементу JSON-элементу codes.cad_flat.
      • house – содержит кадастровый номера дома или земельного, если дом присутствует в адресе. Данный атрибут аналогичен JSON-элементу codes.cad_house.

    XML-элемент Country: страна, которой принадлежит адрес

    Данный элемент является дочерним по отношению к элементу Address и содержит информацию о стране, которой принадлежит обработанный адрес. Информация, выводимая в рамках данного элемента, аналогична информации, выводимой в JSON-объекте address[i].country. Пример XML-элемента Country приведен ниже.

    <Country name="КАЗАХСТАН" code="398" sign="KAZ"/>

    Элемент Country содержит следующие атрибуты.

    • code – цифровой код страны по справочнику ОКСМ.
    • name – краткое название страны.
    • sign – трёхбуквенный латинский код страны.

    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-элемент Property: дополнительные свойства адреса

    Данный элемент является дочерним по отношению к элементу Address и содержит информацию с дополнительными свойствами обработанного адреса. Информация, выводимая в рамках данного элемента, аналогична информации, выводимой в JSON-объекте address[i].property. Пример XML-элемента Property приведен ниже.

    <Property>
      <HouseFlatsAmount val="123"/>
    </Property>
    

    Элемент Property включает в себя следующие дочерние элементы.

    • HouseFlatsAmount - содержит количество квартир в доме, который указан в адресе, при условии, что данный дом существует и по нему имеется информация о квартирах в базе данных сервиса. Значение свойства передается посредством атрибута val данного XML-элемента.

    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.
версия сервиса:
обработано за 2 (мс)