Стандартизация

Стандартизация приводит уже введённые данные в порядок: разбирает строку на части, исправляет регистр и опечатки, дополняет тем, чего в ней не было. Это пакетный разбор того, что уже лежит в базе или пришло из файла, — для автодополнения при вводе есть подсказки.

У каждого метода два адреса. Первый — наш: ответ приходит в нашем формате, со всеми полями. Второй — совместимый с DaData: тот же метод, но ответ в их формате, чтобы при переезде не переписывать разбор ответа. Оба адреса принимают одинаковое тело запроса.

Стандартизация адреса

Приводит свободную строку адреса к структуре — той же, что в разделе «Адреса». Для разбора выгрузок: на входе список строк, на выходе по одному разобранному адресу на каждую.

Параметры запроса

// к нам — свой формат ответа, пакет в items
POST /v1/clean/address
{ "items": ["мск тверская 7", "спб невский 1"] }

// совместимо с DaData — телом массив строк, ответ в их формате
POST /api/v1/clean/address
["мск тверская 7", "спб невский 1"]

Поля ответа

Поля описаны для записи внутри results — так отвечает наш адрес. По совместимому адресу приходит просто массив таких записей, без обёртки.

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

Разбирает ФИО на части, определяет пол и исправляет регистр. В нашем формате добавляет склонения по падежам — их можно сразу подставлять в документы. Для автодополнения при вводе есть подсказки ФИО.

Параметры запроса

// к нам — свой формат ответа: пол male|female|unknown, падежи, признак транслитерации
POST /v1/clean/fio
{ "items": ["иванова мария сергеевна"] }

// совместимо с DaData — телом массив строк, ответ в их формате (пол М|Ж|НД, без падежей)
POST /api/v1/clean/name
["иванова мария сергеевна"]

Поля ответа

Поля описаны для записи внутри results — так отвечает наш адрес. По совместимому адресу приходит просто массив таких записей, без обёртки.

По совместимому адресу приходят поля source, result, surname, name, patronymic и qc; пол — как М, Ж или НД (нет данных). Полей cases и transliterated в нём нет.

Проверка телефона

Проверка номера и оператора

Проверяет тип номера, регион и часовой пояс по плану нумерации. Текущий оператор, перенос, ИНН и коды MCC/MNC доступны на тарифах «Бизнес» и «Корпоративный» (грант phone_mnp); на остальных тарифах эти поля отсутствуют. Нужен секретный ключ с правом find:phone (в настройках ключа — «Проверка номера»). Метод входит в дневной лимит: каждый номер, в том числе в пакете, считается одним запросом. Совместимого метода DaData для этой проверки нет.

Для query ответ имеет вид {query, suggestions}: один найденный номер или пустой список. Для items ответ {results} содержит карточку на каждую входную строку в том же порядке; нераспознанные строки помечены qc. Поля карточки описаны ниже. ИНН, MCC и MNC передаются строками и могут быть null, если сведений в источнике нет.

Стандартизация номера

Нормализует номера РФ и зарубежных стран: определяет страну, тип (мобильный/городской) и валидность. Для РФ дополнительно — оператор (с учётом переноса номера), регион и часовой пояс.

Формат вывода задаётся полем mask в теле запроса. Допустимые значения: имя пресета из списка ниже ("mask": "intl") или пользовательский шаблон ("mask": "+7 (XXX) XXX-XX-XX"), где плейсхолдер цифры — X, # или 9; остальные символы сохраняются без изменений. Маска накладывается на национальный номер любой страны:

• e164 → +79627302371
• intl → +7 (962) 730-23-71
• national → 8 (962) 730-23-71
• intl_sp → +7 962 730-23-71
• dash → +7-962-730-23-71
• spaces → 8 962 730 23 71
• plain → 9627302371
• plain8 → 89627302371
• свой шаблон, напр. +7 (XXX) XXX-XX-XX

Параметры запроса

// mask — ИМЯ пресета (intl / e164 / national …) ИЛИ свой шаблон "+7 (XXX) XXX-XX-XX"
POST /v1/clean/phone
{ "items": ["89627302371", "+375 29 491-19-11"],
  "mask": "intl" }

// совместимо с DaData — телом массив строк, ответ в их формате
POST /api/v1/clean/phone
["89627302371", "+375 29 491-19-11"]

Поля ответа

Поля описаны для записи внутри results — так отвечает наш адрес. По совместимому адресу приходит просто массив таких записей, без обёртки.

Проверка email

Проверяет синтаксис, исправляет опечатки в домене и определяет тип адреса. По флагу check_mx проверяет ещё, принимает ли домен почту.

Параметры запроса

// к нам — свой формат ответа
POST /v1/clean/email
{ "items": ["maria@hintdata.ru", "info@bad..ru"], "check_mx": true }

// совместимо с DaData — телом массив строк, ответ в их формате
POST /api/v1/clean/email
["maria@hintdata.ru", "info@bad..ru"]

Поля ответа

Поля описаны для записи внутри results — так отвечает наш адрес. По совместимому адресу приходит массив записей DaData без обёртки: source, email, local, domain, type (PERSONAL, CORPORATE, ROLE или DISPOSABLE) и qc с кодами DaData: 0 — корректен, 1 — некорректен, 2 — пусто или мусор, 3 — одноразовый, 4 — исправлены опечатки.

Стандартизация даты рождения

Приводит дату к виду ДД.ММ.ГГГГ, раскладывает на год, месяц и день и считает возраст с признаком совершеннолетия. Понимает запись цифрами и словом. Что не удалось разобрать — видно по коду качества в ответе.

Параметры запроса

// к нам — свой формат ответа
POST /v1/clean/birthdate
{ "items": ["04 февраля 1985 г."] }

// совместимо с DaData — телом массив строк, ответ в их формате
POST /api/v1/clean/birthdate
["04 февраля 1985 г."]

Поля ответа

Поля описаны для записи внутри results — так отвечает наш адрес. По совместимому адресу приходит просто массив таких записей, без обёртки.

Несколько полей одной записью

Стандартизирует сразу несколько полей одной записи — ФИО, адрес, телефон, email и дату рождения — и возвращает результаты в том же порядке. Каждое поле обрабатывается так же, как отдельным методом этой страницы. Метод совместим с DaData, в том числе с их SDK для .NET.

В запросе одна запись. Полей одного типа — не больше: ФИО — 1, адресов — 3, телефонов — 3, email — 3, дат рождения — 1. Паспорт и транспортное средство не поддерживаются. Каждое поле, кроме AS_IS, оплачивается как отдельная стандартизация, а ключу нужен доступ к стандартизации всех типов полей в записи.

Параметры запроса

// совместимо с DaData — одна запись, поля по типам из structure
POST /api/v1/clean
{
  "structure": ["AS_IS", "NAME", "PHONE"],
  "data": [["id-1", "Федотов Алексей", "8 916 823 3454"]]
}

Поля ответа