Стандартизация контактных данных, объединенных в одну запись

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

Для выполнения стандартизации каждого элемента данной записи можно было бы использовать API-команды сервиса, предназначенные для обработки соответствующего типа данных: для стандартизации двух адресов - команду cleanse/address, для стандартизации двух телефонов - команду cleanse/phone, а для стандартизации ФИО - команду cleanse/person. Однако такой подход имеет два существенных недостатка.

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

Наличие семантической связи между элементами записи позволяет сервису выполнять их перекрестную обработку. Например, сервис может уточнить рабочий адрес человека на основе его мобильного телефона, или наоборот - уточнить номер домашнего телефона на основе информации о домашнем адресе. Такое возможно лишь в случае, если почтовые адреса и телефоны человека будут объединены в единую запись. Именно в этом заключается основное назначение API-команды cleanse/record.

Принципы использования команды cleanse/record

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

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

Чтобы подсказать сервису, в каком именно формате (JSON или XML) ему передается на обработку запись, нужно использовать параметр input со значениями input=json или input=xml.

Запрос на обработку контактных данных в формате JSON

Ниже приведен пример запроса при передаче на обработку записи в формате JSON.

{
  "id": "1",
  "items": 
  [
    { 
      "type": "address", 
      "role": "рабочий адрес", 
      "body": "ивановка, ул. строителей д. 1" 
    },
    { 
      "type": "address", 
      "role": "домашний адрес", 
      "body": "Москва ул. ткацкая д. 5" 
    },
    { 
      "type": "phone", 
      "role": "рабочий телефон", 
      "body": "533-61-00" 
    },
    { 
      "type": "phone", 
      "role": "мобильный телефон", 
      "body": "8(913) 832-11-11" 
    },
    { 
      "type": "person", 
      "role": "ФИО", 
      "body": "Иванов Иван Иванович" 
    },
    { 
      "type": "text", 
      "role": "Комментарий", 
      "body": "Не обрабатывается сервисом" 
    }
  ]
}

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

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

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

• type - строка с именем типа элемента записи. От типа элемента зависит, как именно будет интерпретировать его данные сервис при обработке - как адрес, телефон или как ФИО. Возможны следующие значения данного элемента.
  • text - элемент записи содержит простой текст, который сервис должен вернуть в ответе без выполнения обработки. Приложение пользователя может использовать элементы данного типа для своих внутренних нужд, например, для передачи комментариев по записи в целом, как это проиллюстрировано в приведенном выше примере.
  • address - элемент записи содержит почтовый адрес, применительно к которому сервис должен выполнить стандартизацию, по аналогии с тем, как это выполняется командой cleanse/address.
  • phone - элемент записи содержит номер телефона, который сервис должен обработать алгоритмами стандартизации телефонных номеров, по аналогии с тем, как это выполняется командой cleanse/phone.
  • person - элемент записи содержит ФИО, которое сервис должен обработать алгоритмами стандартизации ФИО, по аналогии с тем, как это выполняется командой cleanse/person.
• role - строка, с помощью которой пользовательское приложение может обозначить роль элемента в записи. Целесообразно для каждого элемента записи назначать его собственную уникальную в пределах записи роль. Роль может быть записана в виде произвольной строки, в приведенном примере используются такие роли как, "домашний адрес", "рабочий адрес" и пр. В своем ответе сервис использует роли в качестве ссылок на элементы записи для представления результатов их перекрестной обработки. Например, в ответе сервис может сообщить о том, что наилучшим образом элементу с ролью "рабочий адрес" соответствует элемент с ролью "рабочий телефон". В простейшем случае пользовательское приложение может записывать в поле role порядковый номер элемента в рамках записи.
• body - строка, посредством которой приложение передает тело элемента записи. Тело элемента содержит собственно сами данные, которые сервис должен обработать.

Запрос на обработку контактных данных в формате XML

Информация, передаваемая в запросе в формате XML, семантически эквивалента информации, передаваемой в формате JSON. Пример запроса в формате XML приведен ниже.

<record id="1">
  <item type="address" role="рабочий адрес">
    ивановка, ул. строителей д. 1
  </item>
  <item type="address" role="домашний адрес">
    Москва ул. ткацкая д. 5
  </item>
  <item type="phone" role="рабочий телефон">533-61-00</item>
  <item type="phone" role="мобильный телефон">8(913) 832-11-11</item>
  <item type="person" role="ФИО">Иванов Иван Иванович</item>
  <item type="text" role="Комментарий">Не обрабатывается сервисом</item>
</record>

Запрос в формате XML представляет собой документ со следующими XML-элементами.

• record - корневой XML-элемент запроса. В рамках атрибута id данного элемента передается идентификатор обрабатываемой записи. Данный атрибут эквивалентен JSON-элементу id при использовании запроса в формате JSON.
• item - XML-элемент, соответствующий одному элементу обрабатываемой записи. Список из всех XML-элементов item эквивалентен JSON-массиву items при использовании запроса в формате JSON.

Каждый XML-элемент item содержит следующие атрибуты.

• type - используется, чтобы сообщить сервису тип элемента (адрес, телефон или ФИО). Данный атрибут может принимать одно из предопределенных значений, аналогично JSON-элементу type.
• role - используется для передачи сервису информации о роли элемента в рамках записи. Данный атрибут эквивалентен JSON-элементу role при использовании запроса в формате JSON.

Информация элемента, подлежащая непосредственно обработке и стандартизации, передается в рамках текстовой части XML-элемента item. В этом отношении текстовое содержимое XML-элемента item эквивалентно содержимому JSON-элемента body.

Передача запроса

Запрос в виде JSON-строки или XML-сообщения передается сервису в рамках параметра query. Данный параметр может передаваться как методом GET в рамках URL запроса, так и методом POST в рамках HTTP-тела запроса. В обоих случаях строка с запросом должна быть закодирована с использованием URL-encoding.

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

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

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

• user=demotoken - сообщает сервису API-токен пользователя. При отправке реального запроса вместо значения demotoken нужно подставить токен из личного кабинета.
• output=json - сообщает сервису о том, что необходимо вернуть ответ в формате JSON.
• input=json - сообщает сервису, что исходный запрос передается в формате JSON.
• query={%22id%22:%20 ... %BC%22%20}]} - закодированный с использованием URL-encoding исходный JSON-текст обрабатываемой записи. Для компактности здесь приведено только начало и конец тела запроса, остальная часть запроса заменена многоточием.

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

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

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

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

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

• output=pretty - опция применима только в случае использования JSON формата ответа сервиса. Данная опция требует, чтобы сервис выполнил "красивое" форматирование возвращаемого JSON текста, расставив в нем переносы строк, отступы и пробельное прореживание. Опция может быть полезна при отладке взаимодействия пользовательского приложения с сервисом.
• output=cp1251 - опция применима только в случае использования XML формата ответа сервиса. Данная опция требует, чтобы сервис вернул XML-ответ в кодировке windows-1251.
• addresslim=число - лимит на число возвращаемых вариантов распознавания по каждому почтовому адресу записи, в случае если какой-то из адресов записи подразумевает многозначное толкование. Если в запросе данный лимит не установлен, то в качестве лимита будет выступать значение параметра "Максимальное количество вариантов для неоднозначных адресов", указанное в разделе "Профиль" личного кабинета пользователя.
• phonelim=число - лимит на число возвращаемых вариантов распознавания по каждому телефонному номеру записи, в случае если какой-то из телефонов записи подразумевает многозначное толкование. Если в запросе данный лимит не установлен, то в качестве лимита будет выступать значение параметра "Максимальное количество вариантов для неоднозначных телефонов", указанное в разделе "Профиль" личного кабинета пользователя.
• personlim=число - лимит на число возвращаемых вариантов распознавания по каждой ФИО исходной записи, в случае если какая-то из ФИО исходной записи подразумевает многозначное толкование. Если в запросе данный лимит не установлен, то в качестве лимита будет выступать значение параметра "Максимальное количество вариантов для распознанных ФИО", указанное в разделе "Профиль" личного кабинета пользователя.
• afilter=адресный фильтр - строка с описанием адресного фильтра, который следует применить к результату обработки почтовых адресов, присутствующих в записи. Подробнее об адресных фильтрах и способах их описания можно ознакомиться здесь.
• mode=forcezip|search|weak - опции обработки почтового адреса. Можно указать одну или сразу несколько опций, разделив их вертикальной чертой. Назначение данных опций описано в документации к API-команде cleanse/address.
• output=acover|ageo|acodes|aqual|apretty|status - опции, включающие в ответ сервиса дополнительную информацию об обработанном адресе. Можно указать одну или сразу несколько опций, разделив их вертикальной чертой. Назначение данных опций описано в документации к API-команде cleanse/address.

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

Приведенный ниже запрос отсылает сервису на обработку запись, представленную ранее в формате XML, с дополнительными параметрами.

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

• user=demotoken - сообщает сервису API-токен пользователя.
• output=json|pretty|ageo - сообщает сервису о том, что необходимо вернуть ответ в формате JSON, отформатировав его "красиво". При этом у сервиса дополнительно запрашиваются географические координаты для каждого почтового адреса обработанной записи.
• input=xml - сообщает сервису о том, что запись, передаваемая для обработки, представлена в формате XML.
• addresslim=3 - сообщает сервису, что в случае многозначного распознавания элементов записи, содержащих почтовый адрес, следует вернуть первые три варианта, наиболее соответствующие обработанному элементу.
• phonelim=1 - сообщает сервису, что в случае многозначного распознавания элементов записи, содержащих телефонный номер, следует вернуть только один вариант, наиболее соответствующий обработанному элементу.
• personlim=1 - сообщает сервису, что в случае многозначного распознавания элементов записи, содержащих ФИО, следует вернуть только один вариант, наиболее соответствующий обработанному элементу.
• afilter=7 - сообщает сервису, что при обработке почтовых адресов записи к результатам стандартизации следует применять пользовательский фильтр с идентификатором 7. Полагается, что такой фильтр настроен в разделе "Фильтры адресов" в личном кабинете. Подробнее об адресных фильтрах и способах их описания можно ознакомиться здесь.
• query=%3Crecord%20id=%22 ... %3E%3C/record%3E - закодированный с использованием URL-encoding исходный XML-текст записи, подлежащей обработке. Для компактности здесь приведено только начало и конец тела запроса, остальная часть запроса заменена многоточием.

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

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

{
  "id" : "1",
  "items" : [
    {
      "body" : "ивановка, ул. строителей д. 1",
      "result" : {
        "addresses" : [ ... варианты стандартизации адреса ... ],
        "check_info" : { ... сводная информация о результате ...},
        "best_phone" : {
          "item" : 2,
          "role" : "рабочий телефон"
        }
      },
      "role" : "рабочий адрес",
      "type" : "address"
    },
    {
      "body" : "Москва ул. ткацкая д. 5",
      "result" : {
        "addresses" : [ ... варианты стандартизации адреса ...],
        "check_info" : { ... сводная информация о результате ...},
        "best_phone" : {
          "item" : 2,
          "role" : "рабочий телефон"
        }
      },
      "role" : "домашний адрес",
      "type" : "address"
    },
    {
      "body" : "533-61-00",
      "result" : {
        "phones" : [... варианты стандартизации телефона ...],
        "check_info" : {... сводная информация о результате ...},
        "best_address" : {
          "item" : 0,
          "role" : "рабочий адрес"
        }
      },
      "role" : "рабочий телефон",
      "type" : "phone"
    },
    {
      "body" : "8(913) 832-11-11",
      "result" : {
        "phones" : [... варианты стандартизации телефона ...],
        "check_info" : {... сводная информация о результате ...},
        "best_address" : {
          "item" : 0,
          "role" : "рабочий адрес"
        }
      },
      "role" : "мобильный телефон",
      "type" : "phone"
    },
    {
      "body" : "Иванов Иван Иванович",
      "result" : {
        "persons" : [... варианты стандартизации ФИО ...],
        "check_info" : {... сводная информация о результате ...}
      },
      "role" : "ФИО",
      "type" : "person"
    },
    {
      "body" : "Данная информация не обрабатывается сервисом",
      "role" : "Комментарий",
      "type" : "text"
    }
  ],
  "request_process_time" : 0
} 

Для простоты изложения в приведенном примере не отображены реальные результаты стандартизации элементов обработанной записи. Для элементов типа "почтовый адрес" варианты стандартизации заменены фразой "... варианты стандартизации адреса ...". Для элементов типа "телефонный номер" варианты стандартизации заменены фразой "... варианты стандартизации телефона ...". Для элементов типа "ФИО" варианты стандартизации заменены фразой "... варианты стандартизации ФИО ...".

Важной чертой ответа сервиса является полное повторение структуры исходной записи. В ответе сервиса, также как и в исходной записи, присутствуют следующие элементы.

• id - содержит идентификатор обработанной записи, извлеченный из одноименного элемента исходного запроса.
• items - представляет массив элементов записи. Каждый элемент данного массива повторяет информацию соответствующего элемента исходной записи посредством одноименных элементов type, role и body. В дополнение к этому каждый элемент массива items снабжается JSON-объектом result, в котором сервис возвращает результат обработки соответствующего элемента записи. Описание структуры данного объекта приводится далее.
• request_process_time - время обработки всего запроса в целом в миллисекундах.

JSON-объект result: результат стандартизации элемента записи

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

Если исходный элемент является почтовым адресом (в этом случае его элемент type содержит значение address), то результат обработки этого элемента будет содержать результат стандартизации почтового адреса. А именно, в объекте result будут присутствовать следующие элементы.

• addresses - JSON-массив, содержащий варианты распознавания и стандартизации почтового адреса. Описание данного массива приведено в документации к API-команде cleanse/address по следующей ссылке cleanse/address#JSON-addresses.
• check_info - JSON-объект, содержащий сводную информацию о результате обработки данного почтового адреса. Описание этого JSON-объекта приведено в документации к API-команде cleanse/address по следующей ссылке cleanse/address#JSON-check_info.
• best_phone - JSON-объект, содержащий результат перекрестной обработки данного адреса со всеми телефонными номерами, представленными в исходной записи. Назначение и структура данного объекта приведены в следующем подразделе. Если для текущего адреса не удастся подобрать подходящий телефон среди всех телефонов обработанной записи, то данный JSON-объект будет отсутствовать в ответе сервиса.

Если исходный элемент является телефонным номером (в этом случае его элемент type содержит значение phone), то результат обработки этого элемента будет содержать результат стандартизации телефона. А именно, в объекте result будут присутствовать следующие элементы.

• phones - JSON-массив, содержащий варианты распознавания и стандартизации телефонного номера. Описание данного массива приведено в документации к API-команде cleanse/phone по следующей ссылке cleanse/phone#JSON-phones.
• check_info - JSON-объект, содержащий сводную информацию о результате обработки данного телефонного номера. Описание этого JSON-объекта приведено в документации к API-команде cleanse/phone по следующей ссылке cleanse/phone#JSON-check_info.
• best_address - JSON-объект, содержащий результат перекрестной обработки данного телефонного номера со всеми почтовыми адресами, представленными в исходной записи. Назначение и структура данного объекта приведены в следующем подразделе. Если для текущего телефона не удастся подобрать подходящий адрес среди всех адресов обработанной записи, то данный JSON-объект будет отсутствовать в ответе сервиса.

Если исходный элемент содержит информацию о ФИО персоны (в этом случае его элемент type содержит значение person), то результат обработки этого элемента будет содержать результат стандартизации ФИО. А именно, в объекте result будут присутствовать следующие элементы.

• persons - JSON-массив, содержащий варианты распознавания и стандартизации ФИО. Описание данного массива приведено в документации к API-команде cleanse/person по следующей ссылке cleanse/person#JSON-persons.
• check_info - JSON-объект, содержащий сводную информацию о результате обработки данного ФИО. Описание этого JSON-объекта приведено в документации к API-команде cleanse/person по следующей ссылке cleanse/person#JSON-check_info.

JSON-объект best_phone: лучший телефон, соответствующий почтовому адресу

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

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

Пример объекта best_phone приведен ниже.

        "best_phone" : {
          "item" : 2,
          "role" : "рабочий телефон"
        }

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

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

Оба элемента: item и role - могут использоваться в качестве ссылки на элемент записи, содержащий наилучший телефонный номер для обработанного адреса.

JSON-объект best_address: лучший почтовый адрес, соответствующий телефону

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

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

Пример объекта best_address приведен ниже.

        "best_address" : {
          "item" : 0,
          "role" : "рабочий адрес"
        }

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

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

Оба элемента: item и role - могут использоваться в качестве ссылки на элемент записи, содержащий наилучший почтовый адрес для обработанного телефона.

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

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

Ниже приведен XML-ответ сервиса с результатом обработки записи, представленной в начале данной документации.

<record id="1">
  <item type="address" role="рабочий адрес">
    <Address>
      ... вариант стандартизации адреса ...
    </Address>
    <CheckInfo>
      ... сводная информация о результате обработки адреса ...
    </CheckInfo>
    <BestPhone role="рабочий телефон" item="2"/>
  </item>
  <item type="address" role="домашний адрес">
    <Address>
      ... вариант стандартизации адреса ...
    </Address>
    <CheckInfo>
      ... сводная информация о результате обработки адреса ...
    </CheckInfo>
    <BestPhone role="рабочий телефон" item="2"/>
  </item>
  <item type="phone" role="рабочий телефон">
    <Phone type="fixed" verified="1">
      ... вариант стандартизации телефона ...
    </Phone>
    <CheckInfo>
      ... сводная информация о результате обработки телефона ...
    </CheckInfo>
    <BestAddress role="рабочий адрес" item="0"/>
  </item>
  <item type="phone" role="мобильный телефон">
    <Phone type="mobile" verified="1">
      ... вариант стандартизации телефона ...
    </Phone>
    <CheckInfo>
      ... сводная информация о результате обработки телефона ...
    </CheckInfo>
    <BestAddress role="рабочий адрес" item="0"/>
  </item>
  <item type="person" role="ФИО">
    <Person>
      ... вариант стандартизации ФИО ...
    </Person>
    <CheckInfo>
      ... сводная информация о результате обработки ФИО ...
    </CheckInfo>
  </item>
  <item type="text" role="Комментарий">
    <![CDATA[Данная информация не обрабатывается сервисом]]>
  </item>
</record>

Как и при описании JSON-ответа сервиса, в приведенном выше XML-ответе для простоты изложения результаты стандартизации адресов, телефонов и ФИО заменены комментариями типа "...вариант стандартизации...".

XML-ответ, по аналогии с JSON-ответом, полностью повторяет структуру исходной записи. А именно, ответ сервиса представлен XML-элементом record, содержащим следующую информацию.

• Атрибут id - содержит идентификатор обработанной записи, извлеченный из одноименного атрибута исходного запроса.
• XML-элементы item - представляют массив элементов обработанной записи. Каждый элемент item повторяет информацию соответствующего элемента исходной записи: в нем так же, как и в исходной записи, присутствуют атрибуты type и role. Вместо текстового содержимого каждого элемента исходной записи в элементы item XML-ответа вставляются результаты стандартизации обработанных данных в виде соответствующих дочерних XML-элементов. Список XML-элементов item является эквивалентом JSON-массива items в рамках JSON-ответа сервиса.

XML-элемент item: результат стандартизации элемента записи

Содержимое XML-элемента item в XML-ответе сервиса заполняется результатом обработки и стандартизации исходного элемента записи. Содержимое этого элемента зависит от типа, которому принадлежит обработанный элемент.

Если исходный элемент является почтовым адресом (в этом случае его атрибут type содержит значение address), то результат обработки этого элемента будет содержать результат стандартизации почтового адреса. А именно, в нем будут представлены следующие дочерние XML-элементы.

• Address - элемент содержит один вариант распознавания и стандартизации почтового адреса. Если адрес распознан неоднозначно, то таких элементов будет несколько по числу вариантов стандартизации адреса. Описание данного элемента приведено в документации к API-команде cleanse/address по следующей ссылке cleanse/address#XML-Address.
• CheckInfo - содержит сводную информацию о результате обработки данного почтового адреса. Описание этого XML-элемента приведено в документации к API-команде cleanse/address по следующей ссылке cleanse/address#XML-CheckInfo.
• BestPhone - элемент, содержащий результат перекрестной обработки данного адреса со всеми телефонными номерами, представленными в исходной записи. Назначение и структура данного объекта приведены в следующем подразделе. Если для текущего адреса не удастся подобрать подходящий телефон среди всех телефонов обработанной записи, то данный XML-элемент будет отсутствовать в ответе сервиса. Семантически данный элемент эквивалентен JSON-объекту best_phone в JSON-ответе сервиса.

Если исходный элемент является телефонным номером (в этом случае его атрибут type содержит значение phone), то результат обработки этого элемента будет содержать результат стандартизации телефона. А именно, в нем будут представлены следующие дочерние XML-элементы.

• Phone - элемент содержит один вариант распознавания и стандартизации телефонного номера. Если телефон распознан неоднозначно, то таких элементов будет несколько по числу предложенных сервисом вариантов стандартизации. Описание данного элемента приведено в документации к API-команде cleanse/phone по следующей ссылке cleanse/phone#XML-Phone.
• CheckInfo - содержит сводную информацию о результате обработки данного телефонного номера. Описание этого XML-элемента приведено в документации к API-команде cleanse/phone по следующей ссылке cleanse/phone#XML-CheckInfo.
• BestAddress - элемент, содержащий результат перекрестной обработки данного телефонного номера со всеми почтовыми адресами, представленными в исходной записи. Если для текущего телефона не удастся подобрать подходящий адрес среди всех адресов обработанной записи, то данный XML-элемент будет отсутствовать в ответе сервиса. Семантически данный элемент эквивалентен JSON-объекту best_address в JSON-ответе сервиса.

Если исходный элемент содержит информацию о ФИО персоны (в этом случае его атрибут type содержит значение person), то результат обработки этого элемента будет содержать результат стандартизации ФИО. А именно, в нем будут представлены следующие дочерние XML-элементы.

• Person - элемент, содержащий варианты распознавания и стандартизации ФИО. Если ФИО распознано неоднозначно, то таких элементов будет несколько по числу предложенных сервисом вариантов. Описание данного элемента приведено в документации к API-команде cleanse/person по следующей ссылке cleanse/person#XML-Person.
• CheckInfo - содержит сводную информацию о результате обработки данной ФИО. Описание этого XML-элемента приведено в документации к API-команде cleanse/person по следующей ссылке cleanse/person#XML-CheckInfo.

XML-элемент BestPhone: лучший телефон, соответствующий почтовому адресу

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

Семантически XML-элемент BestPhone эквивалентен JSON-объекту best_phone, возвращаемому в ответе сервиса при использовании формата JSON.

Пример XML-элемента BestPhone приведен ниже.

      <BestPhone role="рабочий телефон" item="2"/>

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

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

XML-элемент BestAddress: лучший почтовый адрес, соответствующий телефону

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

Семантически XML-элемент BestAddress эквивалентен JSON-объекту best_address, возвращаемому в ответе сервиса при использовании формата JSON.

Пример XML-элемента BestAddress приведен ниже.

      <BestAddress role="рабочий адрес" item="0"/>

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

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