Стандартизация ФИО

Команда по стандартизации ФИО предназначена для приведения ФИО персоны, заданного в виде сплошной строки в произвольной форме, к стандартному виду. При этом выполняется разделение ФИО на отдельные компоненты (то есть, выделение фамилии, имени и отчества персоны) и исправление ошибок и опечаток для каждого компонента.

Необходимость в такой обработке возникает, например, в CRM-системах, если данные об именах клиентов вводятся в виде сплошной строки с отсутствием жесткого требования к порядку следования компонентов ФИО. Один оператор может ввести "Пётр Фёдорович Семенов", а другой – "семенов петр федорович". В данном случае отсутствует информация о том, какая часть строки является именем персоны, какая – фамилией, а какая – отчеством. Это усложняет поиск дубликатов среди клиентов, а также затрудняет организацию персонифицированной рассылки писем.

Эту проблему позволяет решить функция стандартизации ФИО, выполняющая распознавание компонентов ФИО и приведение их к стандартному виду (для вышеприведенного примера – фамилия "Семёнов", имя "Пётр" и отчество "Фёдорович").

Стандартизация сопровождается обогащением ФИО дополнительной информацией о поле персоны и её национальности.

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

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

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

Пример простого запроса по обработке ФИО

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

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

• 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 вариантам, то данное значение будет принудительно уменьшено до этого допустимого порога. Если в запросе данный лимит не установлен, то в качестве ограничения будет выступать значение параметра "Максимальное количество вариантов для распознанных ФИО", указанное в разделе "Профиль" личного кабинета пользователя.

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

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

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

• 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 включительно. Чем он больше, тем выше совместимость компонентов.