Стандартизация ФИО
Команда по стандартизации ФИО предназначена для приведения ФИО персоны, заданного в виде сплошной строки в произвольной форме, к
стандартному виду. При этом выполняется разделение ФИО на отдельные компоненты (то есть, выделение фамилии, имени и отчества
персоны) и исправление ошибок и опечаток для каждого компонента.
Необходимость в такой обработке возникает, например, в CRM-системах, если данные об именах клиентов вводятся в виде сплошной
строки с отсутствием жесткого требования к порядку следования компонентов ФИО. Один оператор может ввести
"Пётр Фёдорович Семенов", а другой – "семенов петр федорович".
В данном случае отсутствует информация о том, какая часть строки является именем персоны, какая – фамилией, а какая – отчеством.
Это усложняет поиск дубликатов среди клиентов, а также затрудняет организацию персонифицированной рассылки писем.
Эту проблему позволяет решить функция стандартизации ФИО, выполняющая распознавание компонентов ФИО и приведение их к
стандартному виду (для вышеприведенного примера – фамилия "Семёнов", имя
"Пётр" и отчество "Фёдорович").
Стандартизация сопровождается обогащением ФИО дополнительной информацией о поле персоны и её национальности.
Информация о поле персоны может быть использована при организации персонифицированной рассылки писем клиентам.
Формирование текста письма с учетом пола получателя позволит сделать письмо более дружественным по отношению к адресату.
Информация о вероятной национальности или этнической группе, к которой принадлежит персона, также может быть использована
для адаптации текста письма для конкретного клиента. Кроме того, организации, осуществляющие выдачу кредитов и микрозаймов,
могут использовать эту информацию для более точной настройки скоринговой модели.
Определение пола и национальности персоны позволяет также оценить, насколько сочетаются её фамилия, имя и отчество с точки
зрения этих параметров. Информация о сочетаемости компонентов ФИО важна для оценки правдивости и правильности данных, предоставленных клиентом.
В частности, она может быть использована для выявления покупателей, указывающих в заявках или заказах некорректную информацию, например,
мужское имя в сочетании с женским отчеством или немецкое имя в сочетании с русской фамилией.
Пример простого запроса по обработке ФИО
Приведенный ниже запрос отсылает сервису на обработку строку "Иван Семенович Петров". При этом используется минимальное количество параметров и опций.
https://ahunter.ru/site/cleanse/person?user=demotoken;output=json;query=%D0%98%D0%B2%D0%B0%D0%BD%20%D0%A1%D0%B5%D0%BC%D0%B5%D0%BD%D0%BE%D0%B2%D0%B8%D1%87%20%D0%9F%D0%B5%D1%82%D1%80%D0%BE%D0%B2
В данном запросе используются следующие параметры.
-
user=demotoken – сообщает сервису API-токен пользователя.
При отправке реального запроса в качестве значения этого параметра нужно подставить токен из личного кабинета.
-
output=json – сообщает сервису о том, что необходимо вернуть ответ в формате JSON.
-
query=%D0%98%D0 ... %BE%D0%B2 – закодированное с
использованием URL-encoding введенное пользователем ФИО "Иван Семенович Петров"
в кодировке UTF-8, которое подвергается стандартизации.
Рассмотрим более подробно все параметры, которые сервис может получать в рамках данной команды.
Параметры команды
Обязательные параметры для выполнения запроса.
-
https://ahunter.ru/site/cleanse/person - URL-команды.
-
user=API-токен - API-токен пользователя из личного кабинета.
-
output=json или output=xml – формат, в котором требуется вернуть результат обработки.
-
query=строка запроса – строка, содержащая обрабатываемое ФИО.
Опциональные параметры.
-
output=pretty – опция, применимая только в случае использования JSON
формата ответа сервиса. Данная опция требует, чтобы сервис выполнил "красивое" форматирование возвращаемого JSON-текста, расставив в нем
переносы строк, отступы и пробельное прореживание. Опция может быть полезна при отладке взаимодействия пользовательского приложения с сервисом.
Если этот параметр не задан, JSON-ответ будет возвращен в виде сплошной строки.
-
output=cp1251 – опция, применимая только в случае использования XML
формата ответа сервиса. Данная опция требует, чтобы сервис вернул XML-ответ в кодировке windows-1251. Если этот параметр не задан, данные
возвращаются в кодировке UTF-8.
-
input=utf8 или input=cp1251
– кодировка UTF-8 или windows-1251, в которой представлены входные данные в параметре query. Если этот параметр не задан,
полагается, что данные получены в кодировке UTF-8.
-
personlim=число - лимит на число возвращаемых вариантов стандартизации ФИО,
в случае, если ФИО в исходном запросе может быть распознано несколькими способами. Если данное значение превышает установленный администратором
сервиса порог, равный 5 вариантам, то данное значение будет принудительно уменьшено до этого допустимого порога. Если в запросе данный лимит
не установлен, то в качестве ограничения будет выступать значение параметра "Максимальное количество вариантов для распознанных ФИО", указанное
в разделе "Профиль" личного кабинета пользователя.
Пример запроса по обработке ФИО с дополнительными опциями
Приведенный ниже запрос отсылает сервису на обработку строку "Иван Семенович Петров" с дополнительными параметрами.
http://ahunter.ru/site/cleanse/person?user=demotoken;input=utf8;output=json|pretty;
personlim=3;query=%D0%98%D0%B2%D0%B0%D0%BD%20%D0%A1%D0%B5%D0%BC%D0%B5%D0%BD%D0%BE%D0%B2%D0%B8%D1%87%20%D0%9F%D0%B5%D1%82%D1%80%D0%BE%D0%B2
В данном запросе используются следующие параметры.
-
user=demotoken – сообщает сервису API-токен пользователя.
-
input=utf8 – сообщает сервису о том, что обрабатываемая строка представлена в кодировке UTF-8.
-
output=json|pretty – сообщает сервису
о том, что необходимо вернуть ответ в формате JSON, отформатировав его "красиво".
-
query=%D0%98%D0 ... %BE%D0%B2 – закодированное с использованием
URL-encoding введенное пользователем ФИО "Иван Семенович Петров" в кодировке UTF-8, которое подвергается стандартизации.
-
personlim=3 – сообщает сервису, что в случае многозначного
распознавания ФИО следует вернуть только три наиболее подходящих варианта.
Результат запроса: стандартизованные фамилия, имя и отчество в формате JSON
Ниже приведен ответ сервиса с результатом обработки ФИО "Андрес Бради". Результирующий JSON-ответ
получен с использованием опции output=json|pretty, позволяющей
выполнить "красивое" форматирование JSON-текста, а также с использованием параметра personlim=3,
сообщающим сервису о необходимости вернуть три наиболее подходящих варианта распознавания.
{
"check_info" : {
"alts" : 3,
"query" : "Андрес Бради",
"time" : 31
},
"persons" : [
{
"compatibility" : 1.000,
"domain" : "испанский",
"first_name" : "Андрес",
"full_name" : "Бради Андрес",
"gender" : "MALE",
"last_name" : "Бради",
"patronym" : ""
},
{
"compatibility" : 0.157,
"domain" : "индоевропейский",
"first_name" : "Андрес",
"full_name" : "Барди Андрес",
"gender" : "MALE",
"last_name" : "Барди",
"patronym" : ""
},
{
"compatibility" : 1.000,
"domain" : "шведский",
"first_name" : "Андерс",
"full_name" : "Барди Андерс",
"gender" : "MALE",
"last_name" : "Барди",
"patronym" : ""
}
],
"request_process_time" : 31
}
Результатом стандартизации ФИО является JSON-объект со следующими элементами.
-
persons – массив с вариантами стандартизации имени персоны. Если ФИО может быть распознано
несколькими способами (как в приведенном примере), то данный массив будет содержать более одного элемента.
-
check_info – объект со сводной информацией о результате обработки. Структура и назначение
данного объекта аналогичны одноименному JSON-объекту, возвращаемому в результате стандартизации почтового адреса с помощью
команды cleanse/address. Описание данного элемента доступно по следующей ссылке:
cleanse/address#JSON-check_info.
-
request_process_time – время обработки всего запроса в целом в миллисекундах.
Ниже приведено детальное описание этих элементов.
JSON-массив persons: варианты стандартизации ФИО
Обрабатываемое ФИО может содержать ошибки и опечатки, и при выполнении стандартизации предпринимается попытка их исправления.
Для некоторых имён возможны различные способы исправления ошибок, и в этих случаях сервис вернет несколько вариантов интерпретации
ФИО. Каждому предлагаемому сервисом варианту соответствует отдельный элемент JSON-массива persons.
Количество возвращаемых в данном массиве вариантов лимитируется с помощью необязательного параметра personlim.
Пример JSON-объекта, соответствующего одному варианту интерпретации обрабатываемого ФИО, приведен ниже.
{
"compatibility" : 1.000,
"domain" : "испанский",
"first_name" : "Андрес",
"full_name" : "Бради Андрес",
"gender" : "MALE",
"last_name" : "Бради",
"patronym" : ""
}
Каждый элемент массива persons представляет собой JSON-объект со следующими элементами.
-
last_name – строка, содержащая фамилию персоны, выделенную при разбиении исходной строки на компоненты и приведенную к стандартному виду.
-
first_name – строка, содержащая имя персоны, выделенное при разбиении исходной строки на компоненты и приведенное к стандартному виду.
-
patronym – строка, содержащая отчество персоны, выделенное при разбиении исходной строки на компоненты и приведенное к стандартному виду.
-
full_name – строка, содержащая полное имя персоны, приведенное к стандартному виду.
Полное имя содержит стандартизованные компоненты ФИО, расположенные в порядке "фамилия-имя-отчество".
-
gender – строка с полом персоны. Содержит одно из двух значений – MALE или
FEMALE. Значение MALE указывает на мужской пол персоны, а
значение FEMALE – на женский.
-
domain – строка с вероятной национальностью или этнической группой, к которой относится человек, имеющий указанное ФИО.
-
compatibility – числовой коэффициент совместимости компонентов ФИО с точки зрения
национальности и пола. Коэффициент принимает значения от 0 до 1
включительно. Чем он больше, тем выше совместимость компонентов.
Результат запроса: стандартизованные фамилия, имя и отчество в формате XML
Здесь и далее приводится описание ответа сервиса в случае использования формата XML. По существу, возвращаемые в XML-ответе
элементы имеют аналогичное назначение JSON-элементам, описанным выше. Для получения ответа в формате XML необходимо в исходном
запросе использовать значение параметра output=xml.
XML-ответ сервиса в результате обработки ФИО "Андрес Бради" имеет следующий вид.
<ProcessCheckResult>
<Person>
<LastName val="Бради"/>
<FirstName val="Андрес"/>
<Patronym val=""/>
<FullName val="Бради Андрес"/>
<Gender val="MALE"/>
<Domain val="испанский"/>
<Compatibility val="1.000"/>
</Person>
<Person>
<LastName val="Барди"/>
<FirstName val="Андрес"/>
<Patronym val=""/>
<FullName val="Барди Андрес"/>
<Gender val="MALE"/>
<Domain val="индоевропейский"/>
<Compatibility val="0.157"/>
</Person>
<Person>
<LastName val="Барди"/>
<FirstName val="Андерс"/>
<Patronym val=""/>
<FullName val="Барди Андерс"/>
<Gender val="MALE"/>
<Domain val="шведский"/>
<Compatibility val="1.000"/>
</Person>
<CheckInfo>
<String>
<![CDATA[ Андрес Бради ]]>
</String>
<Time>15</Time>
<Alts>3</Alts>
</CheckInfo>
</ProcessCheckResult>
Результатом стандартизации ФИО является XML-документ со следующими дочерними элементами.
-
Person – данный XML-элемент соответствует одному из вариантов стандартизации обрабатываемого
ФИО. Поскольку в результате обработки ФИО может возникнуть несколько вариантов его распознавания, в XML-ответе может присутствовать
несколько элементов Person, каждый из которых соответствует одному из предложенных сервисом вариантов.
Список из всех XML-элементов Person является аналогом JSON-массива persons, возвращаемого в JSON-ответе сервиса.
-
CheckInfo – данный XML-элемент содержит сводную информацию о результате обработки. Данный элемент является
полным аналогом JSON-объекта check_info, возвращаемого в JSON-ответе сервиса. Аналогичный одноименный элемент
возвращается в ответе сервиса при выполнении команды cleanse/address, его описание доступно по следующей ссылке
cleanse/address#XML-CheckInfo.
Ниже приведено детальное описание этих XML-элементов.
XML-элемент Person: вариант стандартизации ФИО
Элемент Person содержит информацию об одном из вариантов стандартизации. Пример данного элемента приведен ниже.
<Person>
<LastName val="Бради"/>
<FirstName val="Андрес"/>
<Patronym val=""/>
<FullName val="Бради Андрес"/>
<Gender val="MALE"/>
<Domain val="испанский"/>
<Compatibility val="1.000"/>
</Person>
В рамках элемента Person могут присутствовать следующие дочерние элементы.
-
LastName – данный XML-элемент содержит строку, представляющую собой фамилию персоны,
выделенную при разбиении исходной строки на компоненты и приведенную к стандартному виду. Эта строка передается с помощью
атрибута val данного XML-элемента.
-
FirstName – данный XML-элемент содержит строку, представляющую собой имя персоны, выделенное
при разбиении исходной строки на компоненты и приведенное к стандартному виду. Эта строка передается с помощью атрибута
val данного XML-элемента.
-
Patronym – данный XML-элемент содержит строку, представляющую собой отчество персоны,
выделенное при разбиении исходной строки на компоненты и приведенное к стандартному виду. Эта строка передается с помощью
атрибута val данного XML-элемента.
-
FullName – данный XML-элемент содержит строку, представляющую собой полное имя персоны,
приведенное к стандартному виду. Эта строка передается с помощью атрибута val данного XML-элемента.
Полное имя содержит стандартизованные компоненты ФИО, расположенные в порядке "фамилия-имя-отчество".
-
Gender – данный XML-элемент содержит строку с полом персоны. Пол может иметь одно из двух
значений – MALE или FEMALE. Значение MALE
указывает на мужской пол персоны, а значение FEMALE – на женский. Это значение передается с помощью
атрибута val данного XML-элемента.
-
Domain – данный XML-элемент содержит название вероятной национальности или этнической группы,
к которой относится человек, имеющий указанное ФИО. Это название передается с помощью атрибута val данного XML-элемента.
-
Compatibility – данный XML-элемент содержит числовой коэффициент совместимости компонентов ФИО
с точки зрения национальности и пола. Этот коэффициент передается с помощью атрибута val данного
XML-элемента. Коэффициент принимает значения от 0 до 1 включительно.
Чем он больше, тем выше совместимость компонентов.