SDK Pullenti Address предназначено для выделения из текстов адресов, заданных в свободной форме, их нормализации, привязки выделяемых адресов к объектам ГАР ФИАС, а также поиск по названиям, Guid и другим атрибутам объектов ГАР. Дополнительно реализован адресный индекс (Адрессарий), куда можно записывать адреса, которым система назначает уникальные числовые идентификаторы, совпадающие для эквивалентных адресов.

Продукт Non-Commercial Freeware & Commercial Software, то есть бесплатен для некоммерческого использования и небесплатен для коммерческого. Для некоммерческого варианта привязка ограничивается объектами 77-го региона (Москва), для коммерческого - объекты всех регионов России.

Объекты ГАР берутся из xml-файлов выгрузки с сайта https://fias.nalog.ru/Frontend и преобразуются во внутренний индекс посредством специальной утилиты (входит в коммерческую версию). SDK Address работает с внутренним индексом, который представляет собой набор из файлов внутреннего формата, оптимизированного для поисковых задач. Тем самым обеспечивается независимость использующих SDK Address систем от внешних сервисов - работа идёт с файлами локальной папки. Само SDK для своей работы не требует никаких дополнительных установок или внешнего ПО, а ограничивается стандартными библиотеками используемого языка программирования.

SDK предлагает 2 основные функции обработки. Первая функция на вход получает текст одного адреса (например, из поля ввода), и разбирает его структуру, привязывая элементы к объектам ГАР. Вторая функция обрабатывает произвольные тексты, находя в них адреса, которые также разбираются на элементы, привязываемые к ГАР. В первой функции действуют более сложные алгоритмы, которые понимают сокращения, нижний регистр имён, пропуск ключевых слов и пр. Вторая функция ориентирована на другую задачу, поэтому и алгоритмы немного другие.

Помимо этого, SDK содержит ряд полезных функций по работе с объектами ГАР:

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

Хотя изначально в ГАР для объектов отсутствуют GPS-координаты, мы их туда добавляем для домов и земельных участков, как дополнительный реквизит. Процесс пополнения осуществляется из различных источников (позже опишем из каких).

Независимо от наличия или отсутствия ГАР, в SDK есть адресный индекс, названный Адрессарием. Его задача - сохранять внутри себя адреса, отождествляя эквивалентные с точностью до вариации написания, присваивая им числовые идентификаторы. Внешеняя система может использовать данную возможность для "уникализации" своих адресов, то есть присваивая через Адрессарий идентификаторы своим адресам. Адрессарий - это набор файлов проприетарного формата в одной директории. Одновременно можно работать с любым количеством Адрессариев.

SDK представлено функционально эквивалентным кодом на различных языках программирования: C#, Java, Python и Javascript. Исходный код вместе с этой документацией генерируется автоматически из исходного кода C# с помощью специально разработанного конвертера UniSharping. SDK работает на всех операционных системах и платформах, где поддержаны вышеуказанные языки. Свежую версию SDK можно скачать с сайта Garfias. Там же на сайте выкладываются свежие версии индекса для 77 региона.

Для использования SDK нужно добавить в своё решение (solution) проект Address.Net.csproj для .NET Framework 4+ или Address.Core.csproj для .NET Core 2+ в зависимости от платформы, а в своём конечном проекте поставить ссылку на данный проект.

Для демо-примера необходимо скачать с сайта Pullenti архив Gar77.zip с индексом, распаковать его в папку Bin\Debug\Gar77 для Framework или Bin\Debug\netcoreapp2.0\Gar77 для Core.

Основным является статический класс AddressService, содержащий ключевые функции. В самом начале работы необходимо вызвать метод инициализации Initialize и указать папку с индексом ГАР методом SetGarIndexPath. Только после этого SDK готово к работе (в многопоточном режиме). Отметим, что если ГАР-индекс не указать, то всё будет работать, но без привязки выделяемых из текста адресов к объектам ГАР.

AddressService.Initialize();
AddressService.SetGarIndexPath("../Gar77");

Анализ текста производится двумя методами: ProcessText и ProcessSingleAddressText.

В первом случае анализу подлежит любой текст с произвольным количеством адресов. Например, договор. Функция ProcessText ищет все адреса и возвращает список найденных объектов типа TextAddress, каждый соответствует одному найденному адресу. Этот адрес содержит список элементов адреса Items типа AddrObject, которые и привязываются к ГАР-объектам через их список Gars (список потому, что в принципе возможны несколько подходящих объектов ГАР).

List<TextAddress> addrs = AddressService.ProcessText(text, null);
foreach (var addr in addrs)
{
    Console.WriteLine("Address: {0}", addr.GetFullPath(", "));
    /// детализируем элементы адреса
    foreach (AddrObject item in addr.Items)
    {
         Console.WriteLine("  {0}: {1}", item.Level, item.ToString());
         if (item.Gars.Count > 0)
             /// привязанных объектов ГАР в принципе может быть несколько
             foreach (var gar in item.Gars)
                 Console.WriteLine("   Gar: {0} ({1})", gar.ToString(), gar.Guid);
     }
}

Функция ProcessSingleAddressText предназначена для обработки текста, который заведомо содержит один адрес в свободном виде, и ничего кроме. Например, текст из поля ввода адреса. Вместо списка адресов, функция всегда возвращает один адрес TextAddress. Даже если адрес не выделен вообще, то список элементов Items будет пустым. Вычисляется коэффициент качества выделения Coef: значение 100 соответствует идеальному качеству, когда в тексте отсутствуют лишние символы (неизвестные конструкции) и все элементы однозначно привязались к ГАР-объектам.

text = "Москва, ул. 16-я Парковая д.2 кв.3 и какой-то мусор";
TextAddress saddr = AddressService.ProcessSingleAddressText(text, null);
Console.WriteLine("\nAnalyze single address: {0}", text);
Console.WriteLine("Coefficient: {0}", saddr.Coef);
if (saddr.ErrorMessage != null)
    Console.WriteLine("Message: {0}", saddr.ErrorMessage);
foreach (var item in saddr.Items)
{
    Console.Write("Item: {0}", item.ToString());
    if (item.Gars.Count > 0)
       foreach (var gar in item.Gars)
           Console.Write(" (Gar: {0}, GUID={1})", gar.ToString(), gar.Guid);
     Console.WriteLine("");
}

У обработки ProcessSingleAddressText есть большое преимущество по сравнению с результатом через ProcessText. Происходит более точный и качественный анализ в случае ошибок, сокращений, пропуска ключевых слов, использования нижнего регистра и т.п. Например, Ряз.обл,рязанский, рязань, пужкина,18 во втором случае обработает правильно, а в первом не поймёт никакой из элементов этого адреса. Но если нужно выделять адреса из произвольных текстов, то второй способ не сработает в отличие от первого.

Метод GetChildrenObjects возвращает список дочерних ГАР-объектов по идентификатору родительского объекта (если null, то возвращает список самого верхнего уровня, то есть регионы). Метод GetObject вернёт ГАР-объект по его идентификатору, что пригодится для движения по иерархии вверх.

Поиск по тексту наименований ГАР-объектов и по реквизитам производится через функцию SearchObjects, параметры поиска оформляются классом SearchParams, результатом является класс SearchResult с ограниченным списком найденных объектов (их в принципе может быть много) и общим количеством подходящих объектов.

Если в тексте адреса не задан населённый пункт, а только улица с домами, или задан населённый пункт без региона, то можно вторым параметром у этих функций ProcessTextParams передать информацию о дефолтовых объектах или регионах:

• DefaultRegions - номера возможных регионов;
• DefaultObject - город или населённый пункт (ссылку на него можно найти поиском);

Адрес состоит из нескольких элементов, упорядоченных по уровню в порядке убывания. На верхнем уровне находятся страны и регионы, на нижнем - дома и помещения. ГАР предлагает свою систему уровней, которая оформляется перечислением GarLevel и взята за основу уровней AddrLevel для адресов из текста. Приведём соотношение этих уровней и их описание.

Адресный уровень AddrLevel	ГАР уровень GarLevel	Описание
Country	Нет	Страна
RegionCity	Region	Город регионального значения (Москва, Санкт-Петербург, Севастополь)
RegionArea		Регион (область, республика, край)
District	AdminArea	Административный район
	MunicipalArea	Муниципальный район
Settlement	Settlement	Сельское/городское поселение
City	City	Город
CityDistrict	District	Район города (устарело в ГАР)
Locality	Locality	Населенный пункт
Territory	Area	Элемент планировочной структуры (кварталы, территории)
Street	Street	Элемент улично-дорожной сети (улицы)
Plot	Plot	Земельный участок
Building	Building	Здание (сооружение)
Apartment	Room	Помещение, квартира
Room		Комната
	Carplace	Машино-место

В зависимости от уровня, элемент может иметь свой набор атрибутов. Базовый класс наборов атрибутов - пустой. Наследными являются классы AreaAttributes, HouseAttributes и RoomAttributes. Общая диаграмма представлена на рисунке.

Атрибуты объектов уровней с верхнего до улиц оформляются классом AreaAttributes. Они имеют один или несколько типов Types, несколько имён Names (в том числе могут их и не иметь), а также может быть номер Number. Могут быть ещё дополнительные строки Miscs, в которые помещаются имена, атрибуты персон (фамилия попадает в Names) и другие второстепенные значения.

Для уровней "земельный участок" и "здание" - класс HouseAttributes. Здание в общем случае имеет номер Number, корпус BuildNumber и строение StroenNumber. Дом и строение имеют дополнительные типы Typ и StroenTyp. У участка есть номер PlotNumber. Но участок может иметь и атрибуты здания, если он не имеет своего номера, а связан с расположенным на нём зданием (уч. дома №5).

Для помещений и комнат класс для атрибутов RoomAttributes содержит номер Number, тип Typ и, возможно, дополнительный атрибут Misc.

Объекты ГАР реализованы классом GarObject, имеющим поля:

• Attrs - атрибуты одного из наследных от BaseAttributes класса
• Level - уровень (см. GarLevel)
• Expired - признак утраты актуальности
• Guid - уникальный GUID (например, 0c5b2444-70a0-4932-980c-b4dc0d3f02b5 для Москвы)
• Id - идентификатор внутри нашего индекса
• ParentIds - идентификаторы родительских объектов (в ГАР две разные иерархии - муниципальная и административная, и в принципе один объект может принадлежать разным родителям в этих иерархиях, дополнительно объект может принадлежать устаревшему объекту)
• ChildrenCount - количество дочерних объектов в иерархии
• SourceText - исходный текст из ГАР

У каждого ГАР-объекта есть словарь, в котором находятся различные реквизиты типа почтового индекса, кадастрового номера, GPS-координат и др. - список типов параметров определятся перечислением GarParam. Получить такой словарь можно фунцией GetParams, либо получить конкретный реквизит функцией GetParamValue.

Предвосхищаем вопрос: а почему нельзя было вместо Id использовать Guid? Потому, что с ними очень неэффективно работать в условии, когда частой операцией является получение объекта по его Id, например, при построении иерархии вверх. Пришлось вводить внутренние Id для осуществления быстрого доступа. ВНИМАНИЕ! Внешним системам не следует привязываться к этим идентификаторам, так как в очередной версии индекса они вообще говоря изменяются - для внешней идентификации следует использовать Guid.

Объект по его идентификатору Id (не Guid!) можно получить функцией GetObject, список дочерних объектов извлекается функцией GetChildrenObjects, передавая на вход идентификатор родителя или null для верхнего уровня иерархии (регионов). Это сделано намеренно, так как такое получение связано с обращением к индексу ГАР и, вообще говоря, требует некоторых вычислительных ресурсов.

Поиск ГАР-объектов производится функцией SearchObjects, на вход подаются параметры поиска, оформленные классом SearchParams, на выходе возвращается объект SearchResult:

Возможны 2 вида поиска:

1. По реквизиту: тип реквизита GarParam задать в ParamTyp, само значение поместить в ParamValue, причём значение задавать ПОЛНОСТЬЮ, так как поиск идёт по строгому совпадению. В результате вернёт список подходящих ГАР-объектов, содержащих искомый реквизит.
2. По названиям: комбинация из кода региона Region, названия района Area, населённого пункта City и улицы Street. Здесь можно указывать не полные имена, а начала имён. Также для составных названий допустимы сокращения стандартных прилагательных. Например, для улицы "Большая Каретная" можно "Б карет" или "каретн бол". Подстроки не с начала названия недопустимы. Возможна одна ошибка в написании - пропуск\вставка буквы и замена одной буквы кроме первой и последней, но при этом имя должно быть написано целиком. Например, "моск", "масква", "мосва" привяжет к Москве, а "маскв" уже нет.

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

Адрес, выделяемый из текста, оформляется классом TextAddress. Он содержит список адресных элементов Items класса AddrObject, упорядоченный по убыванию уровня, а также ряд дополнительных атрибутов. Такие адреса формируются либо функцией ProcessText, возвращающей список TextAddress, либо функцией ProcessSingleAddressText, возвращающей один адрес.

Элемент адреса AddrObject имеет набор атрибутов Attrs - экземпляр от наследного класса от BaseAttributes, уровень Level и список привязанных ГАР-объектов Gars, которых в общем случае может быть несколько или вообще не быть. Взаимосвязь классов дана на диаграмме.

Класс адреса TextAddress содержит ещё и такие атрибуты:

• Coef - общий коэффициент качества, учитывающий правильность адреса и его привязка к ГАР (100 означает идеальное распознавание и привязку, >= 90 - нормальное, от 80 и ниже лучше не использовать для дальнейшей обработки)
• ErrorMessage - детализация ошибки или неточности, если есть (даже при Coef = 100 возможны сообщения)
• Alpha2 - код страны, если удалось определить (RU, EN, US ...)
• BeginChar .. EndChar - начальная и конечная позиция, занимаемая адресом в исходном тексте (пригодится для позиционирования, когда выделяется множество адресов из текста)
• Milliseconds - миллисекунд обработки (устанавливается только для единичного адреса)

Независимо от ГАР, у текстовых объектов AddrObject можно использовать функцию ToString() для получения нормализованного представления. Отметим, что это только один из нормальных вариантов, которого для практических задач может вполне хватить. Но функция ToString() выводит только текущий объект. Для нормального вывода всего адреса целиком можно вызвать GetFullPath, параметром задавая разделитель.

У объектов AddrObject есть ещё одно поле - ссылка на другой объект CrossObject, которым оформляются случаи задания объектов на пересечении улиц. Например, гор.Тула ул.Кауля/Р.Лозинского д.82/35. В этом случае объект для улицы оформляется для "ул.Рауля", а CrossObject - для "ул.Р.Лозинского", и каждый из них привязывается к своим объектам ГАР. Также и на уровне домов объект для "д.82" и CrossObject для "д.35" с привязкой к ГАР-объектам по своим улицам каждый.

Также бывают ситуации, когда в адресе указываются несколько домов или квартир, через запятую, союз и\или диапазоном. В этом случае в список Items попадает только первый из них, а остальные заносятся в список AdditionalItems. Например, "... дом 10 кв.1,2 и 3-6" в основной список попадёт квартира 1, а квартиры 2, 3, 4, 5 и 6 в дополнительный список, причём эти объекты также будут привязываться к ГАР.

В реальных адресах встречаются указатели относительно ориентиров, в которых задаётся направление и, возможно, расстояние. Для этого у AddrObject есть поле DetailTyp для типа DetailType и DetailParam для возможного параметра (обычно расстояние, которое приводится в метры). Значения типов:

• направления: North, East, South, West, NorthWest, NorthEast, SouthWest и SouthEast, значением может быть расстояние в метрах, null или слово "часть";
• стороны: Left, Right, Central, значение null;
• вблизи Near, значение null;
• диапазон километров KmRange, значение - диапазон, например, км.455+990-км.456+830
• организация [[DetailType.Organization]], значение - нормализованное название организации, например, д.10 универсам "Пятерочка"

Например, Московская область, Можайский район, примерно в 0,1 км по направлению на юг от ориентира середина д.Бараново для деревни Бараново оформит детализацию с типом South и значением "100м" (приводится в метры). Или Московская область, Шаховской район, сельское поселение Серединское, у д. Пахомово, кадастрового квартала 50:05:0040211 в западной части для квартала детализация типа West и значением "часть".

Адрес может содержать различные второстепенные элементы, не вписывающиеся в общую стройную модель. Например, этажи, генпланы, а/я и пр. Такие элементы записываются в словарь Params, ключом является перечисление ParamType, а значение записывается в строковом виде. Сейчас поддержаны такие типы элементов:

• часть Part, значение - номер части (бывает, что для домов указывают части);
• этаж Floor, значение - номер этажа;
• генплан Genplan, значение - номер генплана(например, дер.Хлюпино, уч.23 г.п.-2 (д.66));
• очередь Order, значение - номер очереди (например, в ГСК);
• индекс Zip;
• доставочный участок DeliveryArea;
• абоненчкий ящик SubscriberBox;

У TextAddress устанавливается Coef коэффициент качества, принимающий значение от 100 до 0, при этом 100 означает "идеальное выделение". Опишем здесь примерные принципы его формирования, что влияет на его уменьшение и что не влияет. Отметим, что даже если коэффициент = 100, всё-равно возможны комментарии в ErrorMessage.

На уменьшение этого коэффициента влияет следующее:

• Наличие в строке адреса посторонних элементов, не понимаемых алгоритмом (при обработке одиночного адреса);
• Непривязка некоторых объектов к ГАР. При этом непривязка участков, домов и квартир не уменьшает коэффициент, так как ГАР очень неполный в этом отношении. Не уменьшает, если объект принадлежит объекту, который в ГАР устарел, а также если адрес не российский;
• Нарушение иерархии. Например, "Владимирская область, ул. Цветочная дом 10". Или вообще неуказание верхнего в иерархии объекта, приводящее к большому числу вариантов. Например, "дер. Сосновка, уч2". Допустима ситуация, когда верхним объектом является город, но его имя должно быть уникальным в РФ. Например, для "г.Борзя Бульварная 2" Забайкальский край можно не указывать - он будет восстановлен из ГАР.
• Если привязались несколько объектов ГАР с разными родителями. Это встречается, когда задаётся регион и населённый пункт без указания района, при этом в регионе несколько таких локаций с одинаковыми именами. Однако если несколько объектов ГАР с одним и тем же родителем, то это "нормально" (в ГАР нередко встречается дублирование);
• Указан некорректный объект, нарушающий иерархию ГАР. Например, для населённого пункта указан другой район;

Для дома или земельного участка можно получить координаты GPS, если этот элемент привязался к объекту ГАР. У объекта ГАР среди параметров могут быть координаты, значения которых можно получить функцией GetParamValue по следующему ключу:

• Gps - координаты lat lon, разделённые пробелом, дробная часть через точку (например, 55.2995 37.37641)
• AreaGps - прямоугольник lat_min-lat_max lon_min-lon_max (например, 63.20693-63.20765 75.50244-75.50382)

Если есть прямоугольник, то точка GPS в параметрах вычисляется как его центр.

В настоящий момент не все регионы загружены (только треть), к началу лета надеемся догрузить GPS для остальных. Тогда же опишем и источники получения данных, а также результат сопоставления координат из разных источников. Фактически идёт дополнение параметров ГАР-объектов данными, которые отсутствуют в исходном варианте.

Адресный индекс (Адрессарий) предназначен для хранения адресов и отождествления похожих. Для работы с ним есть класс AddressRepository. После создания экземпляра, нужно вызвать функцию Open, передав параметром имя локальной папки (если не существует, то будет создана), в конце работы нужно вызвать Dispose.

Добавляются адреса функцией Add, где параметром является не текст адреса, а уже разобранный адрес TextAddress. Добавлению подлежат все его элементы AddrObject. При этом у добавляемых элементов AddrObject в случае успеха устанавливается ссылка RepObject на экземпляр репозиторного объекта RepaddrObject, который либо создаётся и добавляется в Адрессарий, либо берётся существующий в случае отождествления. Если нужно только искать существующие элементы без добавления, то используется функция Search.

Если поле RepObject у адресного элемента получилось null, то по каким-то причинам адресный элемент не может быть добавлен. Например, при нарушении принципа иерархии - указана квартира без дома, для адреса "Москва, дом 10" дом не будет добавлен. Также объект самого верхнего уровня должен быть город, регион или страна, иначе это не считается полноценным адресом.

Замечание: мы не рекомендуем добавлять адреса с коэффициентом Coef меньше 80, так как качество таких адресов - сомнительное.

При добавлении некоторой порции адресов (500-1000) и в конце добавления нужно вызывать функцию Commit, чтобы несохранённые данные записались на диск. Если этого не сделать, то индекс может испортиться и не работать корректно. В конце загрузки большого количества адресов (сотен тысяч) не обязательно, но желательно вызвать Optimize, которая уменьшит общий объём файлов индекса и оптимизирует его для функций поиска.

Объект Адрессария представлен классом RepaddrObject. Он имеет:

• Id - уникальный числовой идентификатор
• Parents - список идентификаторов родительских объектов (м.б. несколько)
• Children - список идентификаторов дочерних объектов, если есть
• Spelling - вариант текстовой нормализации
• Level - уровень типа GarLevel
• GarGuids - идентификаторы ГАР-объектов в случае привязки (здесь именно Guid, а не Id)

Внутри Адрессария объекты образуют иерархию, но не жёсткую, так как в принципе объект иерархически может законно относиться к разным элементам. Например, в ГАР ФИАС подобное можно наблюдать из-за несовпадающей административной и муниципальной иерархий. В адресе могут какие-то второстепенные элементы опускать, или наоборот - вставлять. Поэтому у объекта может быть несколько потенциальных родительских объекта.

Для получения объекта по идентификатору используйте функцию GetObject(id), для списка дочерних элементов GetObjects.

А как связан Адрессарий с ГАР? Дело в том, что адрессарий для добавляемых элементов использует не только разные формы записи наименований, чтобы отождествлять с точностью до таких вариаций, но и Guid объектов ГАР, если таковая привязка имела место, то есть идентификатор ГАР используется как дополнительный вариант наименования. Это повышает качество привязки. Например, в случае переименования улицы её Guid-сохранится, хотя наименование изменится. Так что ГАР не обязателен, но желателен (для российских адресов).

ВНИМАНИЕ! В текущей реализации работа с экземпляром Адрессария однопоточная, то есть нельзя из разных потоков добавлять и из других искать. Если потребуется, в будущем поддержим многопоточность.

Исходные данные ГАР ФИАС выкладываются на сайте ФНС, и представляют собой zip-архив около 36Гб (280Гб после распаковки) с файлами формата xml, в которых и находится вся информация.

Для преобразования в индекс, используемый в SDK Address, разработана специальная утилита gar2pullenti.exe, преобразующая xml-файлы в несколько десятков файлов проприетарного формата, оптимизированного для решения поисковых задач. Эта утилита входит в коммерческую версию SDK. Поскольку процесс трансформации занимает около 11 часов (плюс несколько часов на скачивание архива и около часа на разархивирование), то планируется ежемесячное обновления преобразованного индекса ГАР, чтобы пользователи не тратили на это свои ресурсы. Полный индекс ГАР доступен для коммерческой версии, для бесплатной выкладывается индекс 77-го региона (Москва).

Утилита запускается в пакетном режиме и управляется следующими аргументами командной строки:

• -input имя_входной_папки : директория с xml-файлами из распакованного архива;
• -output имя_выходной_папки : директория для результирубщего индекса ГАР;
• -ignoreHouses : не загружать объекты уровня домов, участков, квартир и комнат;
• -ignoreRooms : не загружать объекты уровня квартир и комнат;
• -regions ...: список номеров регионов через запятую, если all, то все, по умолчанию 50,77;
• -kladr имя_папки: директория с dbf-файлами;

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

К сожалению, эти xml не содержат информацию о переименованиях населённых пунктов и улиц, однако там же на сайте ФНС на вкладке "Формат КЛАДР 4.0" есть данные, в которых эта инфомация есть! Рекомендуется скачать свежую версию архива base.7z, распаковать его и указать папку ключом -kladr утилите, и тогда старые наименования также будут добавлены в объекты и учитываться при привязке.

А будет ли выделение адресов и их нормализация без индекса ГАР? Да, будет. Индекс ГАР не является необходимым для работы системы, и если его нет, то просто функцию AddressService.SetGarIndexPath(...) не надо вызывать - и всё будет работать.

Однако наличие индекса ГАР улучшает качество выделения, так как информация из него используется не только для привязки, но и для восполнения отсутствующих в тексте адреса уровней и разрешения различных неоднозначностей. Например, ... ул. Цветочная 1/10 здесь 1/10 может быть как дом с таким номером, так и "дом 1 кв. 10", что можно понять только при наличии соответствующей информации (если она есть в ГАР, разумеется). Или забывают указать населённый пункт, но при этом задают почтовый индекс. Или различные опечатки в названиях исправляются через правильные наименования ГАР.

Короче, довольно много случаев, когда ГАР помогает при распознавании улучшать качество, поэтому хотя без него можно обойтись, но качество в общем случае получится ниже.

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

Если нужно обрабатывать тексты, которые содержат только адреса (например, из полей ввода), то используйте функцию ProcessSingleAddressText. Примерная скорость обработки на компьютере средней мощности: 100-200 адресов в секунду при использовании SDK C# и Java.

Если у вас в файле много адресов в заранее известном структурированном виде (например, CSV-файл или текстовой файла с адресом в каждой строке), то нужно самим разбить текст на фрагменты с адресами и обрабатывать каждый через ProcessSingleAddressText, а не пытаться прогнать всё через ProcessText. Во втором случае адреса будут выделены, но качество может оказаться хуже, так как в первом случае используются дополнительные алгоритмы коррекции и анализа. ProcessText следует использовать только для неструктурированных текстов, в которых заранее неизвестны места расположения адресов, например, для Html-страниц или договоров.

Для SDK Python скорость раз в 20 ниже, но здесь поможет сервер Address.Server.dll, реализованный на .NET Core. Он запускается в локальной сети или на том же компьютере, а SDK взаимодействует с ним по TCP-IP. Если вызвать функцию SetServerConnection, подав на вход uri сервера (по умолчанию, http://localhost:2222), то все функции AddressService будут отрабатывать не через логику текущего приложения, а отправляться на сервер для обработки. Это может на порядок улучшить производительность. В данном случае вместо ProcessSingleAddressText лучше использовать ProcessSingleAddressTexts, обрабатывая адреса порциями по 200-300 штук. Кстати, при работе через сервер не нужно инициализировать Initialize.

Для SDK Javascript скорость раз в 5 ниже, чем для C# и Java, и здесь также можно использовать сервер для ускорения.

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

Если нужно быстро обработать адреса из какого-нибудь поля CSV-файла, то для пользователей Windows в стенде Address.Textdesk есть такая возможность на вкладке "Обработка CSV" (см. далее).

SDK Address в своём составе не содержит никаких средств визуализации, так как является кросс-платформенной и мультиязычной. Некоторая визуализация обработанных данных есть на сайте Pullenti Address в разделе Online-demo. Для пользователей Windows есть стенд, в котором можно провести анализ и получить результаты в наглядном виде, а также поработать с объектами ГАР.

Архив стенда Address.TestDesk нужно скачать с сайта, распаковать в директорию и запустить исполняемый файл Address.Testdesk.exe. Также нужно скачать и распаковать предлагаемый индекс gar77.zip, указав эту папку в стенде через кнопку "Открыть индекс". На вкладке "Индекс ГАР" выводится иерархия объектов, в правом окне отображаются реквизиты и параметры текущего объекта. Фактически это дерево реализовано через функцию GetChildrenObjects.

В поисковом окне слева фактически задаётся экземпляр SearchParams, поиск проводится через SearchObjects, а список GarObject выводится в таблице ниже, причём в первом столбце объект самого нижнего уровня, во втором - его родитель и т.д. Нажатие мышью на ячейке этой таблицы делает объект выделенным в дереве.

На вкладке "Обработка текста" демонстрируется функция ProcessText и визуализация результата:

В левом верхнем окне задаётся текст, после нажатия на кнопку "Обработать" в таблице выводятся текстовые объекты AddrObject, в разрезе уровней ГАР (серым подсвечены непривязанный к ГАР элементы). Выделенные адреса выделяются жирным шрифтом в обработанном тексте. В правом окне выводятся те объекты ГАР, к которым привязались текстовые элементы (при этом добавляются и все ГАР-объекты вверх по иерархии, даже если они явно не присутствовали в тексте).

На вкладке "Обработка адреса" демонстрируется функция ProcessSingleAddressText и визуализация результата аналогично вкладке "Обработка текста", только выделяемый адрес всегда один и используются более мощные алгоритмы.

На вкладке "Обработка CSV" можно обработать множество адресов из CSV-файла и сохранить результат в CSV, добавив в него поля с новыми данными.

На вход стенд понимает CSV-файл с разделителями ';' в кодировке UTF-8 или Windows-1251. Это также может быть текстовой файл, у которого в каждой строке находится адрес и ничего кроме. Слишком много адресов стенд может не уместить в памяти, поэтому в файле не должно быть более нескольких сотен тысяч адресов. После загрузки файла в случае нескольких полей система пытается найти то, которое содержит адреса, и выводит это поле в выпадающем списке на панели. Если адреса содержит другое поле, то его нужно выбрать из списка. Кстати, xls и xlsx файлы можно преобразовать в CSV утилитой file2csv.exe, входящей в архив со стендом. В архив также добавлен файл demo77.csv с московскими адресами для демонстрации этого функционала.

Обработка производится по нажатию на кнопку "Обработать". Процесс можно прервать кнопкой "Стоп" рядом с бегущей строкой. На панели отображается статистика - сколько адресов имеют коэффициент 100, сколько от 90 до 99, сколько от 80 до 89 и все остальные. В таблице адреса с коэффициентом 100 выделяются зелёным фоном, сам коэффициент выводится в первой колонке. Нажатие на колонку приводит к сортировке по этому значению. Кнопкой "Убрать 100" можно убрать все зелёные адреса, оставив "плохие" (их можно сохранить в файл и отправить разработчику для совершенствования алгоритма).

Сохранить результат можно кнопкой "Сохранить", в результирующий файл попадут все поля из исходного файла, при этом к ним добавятся дополнительные поля:

• Нормализация - GetFullPath с разделителем "запятая"
• Коэффициент - Coef
• Сообщение - ErrorMessage
• Страна; Код страны (alpha2)
• Регион; GUID региона - уровень RegionCity или RegionArea
• Район; GUID района - уровни District
• Поселение; GUID поселения - уровень Settlement
• Город; GUID города - уровень City
• Населенный пункт; GUID населенного пункта - уровень Locality
• Территория; GUID территории - уровень Territory
• Улица; GUID улицы - уровень Street
• Участок; GUID участка - уровень Plot
• Дом; GUID дома - уровень Building
• Помещение; GUID помещения - уровень Room
• Разное - через запятую значения Params

Здесь если элемент некоторого уровня привязался к ГАР-объекту, то в первом поле выводится его (ГАР-объекта) текстовое представление, а во второе поле его GUID. Если привязались несколько объектов, то выводится только первый (случайно взятый). Если ни одного объекта не привязалось, то в первое поле выводится нормализованное значение этого текстового элемента, второе поле пустое. Если для уровня элемент отсутствует, то оба поля пустые.

Дефолтовые регионы можно задать на главной панели в соответствующем поле (несколько разделяются пробелом). Дефолтовый объект (город) устанавливается на вкладке "Индекс ГАР", либо задать его имя на главной панели вместо кодов регионов.

Процедура нормализации - не однократная, а должна периодически повторяться. В идеале она должна повторяться на каждой новой версии ГАР, а также при смене (корректировке) алгоритма.

При реализации хранилища с результатами нормализации нужно учесть ряд факторов. Адрес - это не монолит, а набор адресных элементов (АЭ) разных уровней начиная от страны и заканчивая помещениями и машиноместами. В адресе некоторые уровни могут отсутствовать. На некоторых уровнях может быть сразу несколько разных АЭ одного уровня. Хранить у нормализованного АЭ можно (нужно) следующее:

• нормализованное значение из исходного адреса в виде строки (например, “город Москва”)
• если удалось привязать к объекту ГАР, то хранить его Guid, а также текстовое значение. Причём следует учесть, что привязанных ГАР-объектов может быть несколько (это связано как с дублирование в самом ГАР, так и с возможной неопределенностью в ходе привязки)

Исходное поле адреса может содержать:

• один адрес
• два адреса (если бывает, что в одно поле заносят, например, адрес прописки и адрес проживания)
• мусорный текст

Для одного поля адреса в БД должно быть (и периодически пересчитываться):

• исходный текст (не меняется)
• коэффициент (если адресов 2, то среднее арифметическое)
• по каждому выделенному адресу (их может быть 0, 1 или 2):
  • коэффициент
  • сообщение об ошибках и неточностях
  • полное нормализованное текстовое значение, полученное конкатенацией нормализованных АЭ, разделённые запятой - результат функции GetFullPath или какой-либо своей
  • набор АЭ, по каждому:
    • уровень (страна, регион, район, город, …)
    • нормализованная строка этого АЭ
    • набор привязанных ГАР-объектов (возможно, пустой), из Guid и исходных строковых значений

Пусть имеется таблица БД с адресами, хранящимися в текстовом поле и которые нужно "нормализовать" (если адрес распределён по нескольким полям, то для обработки его можно собрать в одну строку, желательно разделяя запятыми). Результат обработки можно хранить как в той же таблице, добавив в неё новые поля, так и в новой таблице, сохраняя связи с записями исходной таблицы.

Здесь предлагается вариант таких новых полей со значениеми, кототый ориентируется на задачи поиска адресов по разным частям, отождествлении адресов и др., причём такие задачи должны решаться исключительно средствами SQL-запросов (select). Для этого предлагается использовать класс AddressDbRecord, экземпляр которого создаётся функцией CreateFromAddress, на вход которой поступает результат разбора одного адреса TextAddress. То есть берётся исходный текст адреса, нормализуется через ProcessSingleAddressText, а затем по полученному экземпляру TextAddress делается экземпляр AddressDbRecord, поля которого записываются в БД как результат нормализации.

Поля предлагаются такие (названия могут быть свои, понятное дело), значения описываются далее:

• Coef, integer - коэффициент распознавания
• NormalString, varchar - полная нормализованная строка (не обязательно)
• Message, varchar - сообщение об ошибке при нормализации
• Level, integer - уровень самого мелкого адресеого элемента (1 - страна, 2 - регион, 3 - город, 4 - район, 5 - нас.пункт, 6 - территория, 7 - улица, 8 - дом-зем.уч., 9 - помещ., маш.место)
• CountryCode, varchar - двухбуквенный код страны (уровень 1)
• RegionMnem, varchar - поисковая мнемоника региона (уровень 2)
• RegionGuid, varchar - guid объекта(ов) ГАР региона (в случае привязки)
• CityMnem, varchar - поисковая мнемоника города (уровень 3)
• CityGuid, varchar - guid объекта(ов) ГАР города (в случае привязки)
• DistrictMnem, varchar - поисковая мнемоника района (уровень 4)
• DistrictGuid, varchar - guid объекта(ов) ГАР района (в случае привязки)
• LocationMnem, varchar - поисковая мнемоника населенного пункта (уровень 5)
• LocationGuid, varchar - guid объекта(ов) ГАР населенного пункта (в случае привязки)
• TerritoryMnem, varchar - поисковая мнемоника территории (уровень 6)
• TerritoryTypes, varchar - поисковая мнемоника типов территории
• TerritoryGuid, varchar - guid объекта(ов) ГАР территории (в случае привязки)
• StreetMnem, varchar - поисковая мнемоника улиц (уровень 7)
• StreetTypes, varchar - поисковая мнемоника типов улиц
• StreetGuid, varchar - guid объекта(ов) ГАР улиц (в случае привязки)
• HouseMnem, varchar - поисковая мнемоника дома, участка (уровень 8)
• HouseGuid, varchar - guid объекта(ов) ГАР дома, участки (в случае привязки)
• ApartmentMnem, varchar - поисковая мнемоника помещения, квартиры, машиноместа (уровень 8)
• ApartmentGuid, varchar - guid объекта(ов) ГАР (в случае привязки)
• GpsLat, real - GSP широта объекта уровня 8 (если есть)
• GpsLong, real - GSP долгота объекта уровня 8 (если есть)

Поисковые мнемоники задаются для именованных объектов по их именам, причём тип отбрасывается. Поисковые мнемоники составляются таким образом, чтобы в случае поиска по ним использовать в SQL условиях точные сравнения, а не менее производительные операторы like. Исходя из этого, при составлении таких мнемоник применяются следующие правила преобразования:

• перевод к верхнему регистру, замена Ё на Е, Щ на Ш, замена рядом стоящих одинаковых букв на одну;
• удаление твердых и мягких знаков, удаление в конце гласных и букв Й, если получается слово не короче 3-х знаков;
• из ФИО оставляется только фамилия, также отбрасываются разные атрибуты персон, звания, профессии и пр.
• каждое слово обрамляется квадратными кавычками [...];
• если имя состоит из нескольких слов, то каждое слово преобразуется вышеуказанным способом, они сортируются по алфавиту и конкатенируются;
• если имя содержит цифры, то они как слово помещаются в кавычках на последнюю позицию;
• если имя отсутствует совсем, а есть только тип, то он используется в качестве имени;

Например, "Малый Конюшенный переулок" -> [КОНЮШЕН][МАЛ], "пос. им. Юрия Гагарина" -> [ГАГАРИН], "территория фабрики 8 Марта" -> [МАРТ][8], "Пенсильванско-Иллинойский штат" => [ИЛИНОЙСК][ПЕНСИЛВАНСК].

У домов довольно сложная система, состоящая в общем случае из нескольких номеров (до трёх), относящихся к домам, корпусам и строениям (литерам), при этом каждый номер может быть буквенно-цифровым или состоять из нескольких цифр, разделённых дробью. Причём такая комбинация может быть записана сколь угодно причудливо. Например, эквивалентными будут: “д.10/1A” = “д.10/1 корп А” = “д.10/1 лит.А” = “д.10 корп. 1 стр. А” и т.д. Для универсальности предлагаем абстрагироваться от разных корпусов, строений и литер, а использовать последовательность элементарных элементов, каждый из которых либо число, либо буквенная комбинация (бывает в номерах несколько букв подряд, например, “дом 10АБ”). Комбинация начинается с обобщённого типа:

• У - для земельных участков
• К - если первый номер явно задан как корпус (например, в Зеленограде многие дома просто корпуса)
• С - если первый номер явно строение, сооружение, литера
• Д - во всех остальных случаях

Далее через пробел идут элементы. Например, “д.10/1A” => Д10 1 А (как видно, все вышеуказанные варианты дадут такую же поисковую мнемонику), “корп. 567Б” => К567 Б, “уч.25” => У25, “влад. б\н” => Д

Для помещений нумерация подобна домам, но проще, так как в принципе состоит из одного номера (хотя и содержащего цифры и буквы, дроби и дефисы). Мнемоника также начинается с обобщённого типа:

• К - квартира
• М - машиноместо
• П - всё остальное (помещения, комнаты, офисы, павильоны и пр.)

Далее также идут элементы номера через пробел.

Для объектов уровней до 5-го (населённый пункт) вообще не имеет смысла учитывать типы, так как в реальных адресах постоянно путают сёла, поселения, посёлки и пр. друг с другом, с районами аналогично, к тому же есть несколько иерархий (муниципальная и административная), в которой объекты называются обычно одинаково, но имеют разные типы. А вот для территорий и улиц типы учитывать необходимо, и они выносятся в отдельные свои поля. Особенность здесь в том, что это может быть не один тип, поэтому строка составляется из них всех, обрамлённых кавычками [...], а в SQL приходится использовать like '%[...]%' по этому полю. Например, "улица Бунинская аллея" -> [аллея][улица] (а [БУНИНСК] попадает в поисковую мнемонику по имени), "территория ГСК "Колесо" №32" -> [ГСК][гаражи] (здесь "гаражи" добавляется специально, так как только на ГСК ориентировтаться нельзя, ибо написания этих форм собственности может быть различное).

Насчёт полей с GUID объектов ГАР - в них может храниться не один, а вообще говоря от 0 до нескольких идентификаторов, и если их несколько, то они разделяются пробелом. В этом случае поиск по ним идёт через like '%guid%'. Но можно при наличии пробелов не сохранять такие значения, считая такую привязку к ГАР недостоверной, и тогда можно использовать оператор точного сравнения строк.

А как теперь найти какой-либо адрес в нормализованной части БД? А нужно его пропучтить через этот же механизм, получив значения AddressDbRecord, и уже по ним формировать условие where для запроса. Например, если самый низкоуровневый элемент в нём дом, и он привязался к ГАР, то условие будет and HOUSE_GUID='...'. Такой запрос захватит и адреса с таким домом и, возможно, разными квартирами, и если нужно убрать из результата квартиры, то добавить учловие and LEVEL=8. Если же к ГАР элемент не привязался, то запрос идёт по поисковой мнемонику (и типе), при этом нужно добавить также и условие на родителя, которые если без привязки к ГАР, то и на его родителя и т.д. вплоть до страны. Наверное, стоит добавить в AddressDbRecord функцию формирования таких where-условий, которые можно будет вставлять в свои SELECT-ы.