API стандартизации

REST-сервис стандартизует почтовые адреса, телефоны, паспорта, ФИО, email, даты и модели автомобилей.
Принимает данные в формате JSON.

Что делаем:

  • Исправляем опечатки в ФИО. Транслитерируем. Проставляем пол.
  • Склоняем ФИО по падежам (кого? кому? кем?)
  • Разбиваем адрес по КЛАДР/ФИАС. Достаем коды КЛАДР, ФИАС, ОКАТО, ОКТМО и ИФНС.
    Определяем округ и район города, геокоординаты, площадь и стоимость квартиры.
    Возвращаем корректный индекс по данным Почты России.
  • Проверяем телефон. Проставляем актуальный код города / DEF-код. Восстанавливаем оператора, регион и часовой пояс.
  • Проверяем корректность email и даты рождения.
  • Проверяем серию и номер паспорта по справочнику недействительных паспортов ФМС.
  • Распознаем марки и модели автомобилей.

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

Как вызвать

  1. Зарегистрируйтесь и получите ключ
  2. Вызовите REST-метод, как в примере:
curl -X POST \
    -H "Content-Type: application/json" \
    -H "Authorization: Token ${API_KEY}" \
    -H "X-Secret: ${SECRET_KEY}" \
    -d '[ "мск сухонска 11/-89" ]' \
    https://dadata.ru/api/v2/clean/address
curl -X POST \
    -H "Content-Type: application/json" \
    -H "Authorization: Token ${API_KEY}" \
    -H "X-Secret: ${SECRET_KEY}" \
    -d '[ "тел 7165219 доб139" ]' \
    https://dadata.ru/api/v2/clean/phone
curl -X POST \
    -H "Content-Type: application/json" \
    -H "Authorization: Token ${API_KEY}" \
    -H "X-Secret: ${SECRET_KEY}" \
    -d '[ "4509 235857" ]' \
    https://dadata.ru/api/v2/clean/passport
curl -X POST \
     -H "Content-Type: application/json" \
     -H "Authorization: Token ${API_KEY}" \
     -H "X-Secret: ${SECRET_KEY}" \
     -d '[ "Срегей владимерович иванов" ]' \
     https://dadata.ru/api/v2/clean/name
curl -X POST \
    -H "Content-Type: application/json" \
    -H "Authorization: Token ${API_KEY}" \
    -H "X-Secret: ${SECRET_KEY}" \
    -d '[ "serega@yandex/ru" ]' \
    https://dadata.ru/api/v2/clean/email
curl -X POST \
    -H "Content-Type: application/json" \
    -H "Authorization: Token ${API_KEY}" \
    -H "X-Secret: ${SECRET_KEY}" \
    -d '[ "24/3/12" ]' \
    https://dadata.ru/api/v2/clean/birthdate
curl -X POST \
    -H "Content-Type: application/json" \
    -H "Authorization: Token ${API_KEY}" \
    -H "X-Secret: ${SECRET_KEY}" \
    -d '[ "форд фокус" ]' \
    https://dadata.ru/api/v2/clean/vehicle
cat > ./request.json <<EOF
{
  "structure": [
    "AS_IS",
    "NAME",
    "ADDRESS",
    "PHONE" ],
  "data": [
    [ "1",
      "Федотов Алексей",
      "Москва, Сухонская улица, 11 кв 89",
      "8 916 823 3454"
    ],
    [ ["2"],
      ["Иванов", "Сергей Владимирович"],
      ["мск", "улица свободы", "65", "12"],
      ["495 663-12-53"]
    ],
    [ "3",
      ["Ольга Павловна", "Ященко"],
      ["", "Спб, ул Петрозаводская 8", "", ""],
      "457 07 25"
    ]
  ]
}
EOF

curl -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Token ${API_KEY}" \
  -H "X-Secret: ${SECRET_KEY}" \
  -d @request.json \
  https://dadata.ru/api/v2/clean

structureструктура записи, содержит четыре поля:

  • AS_IS — оставить как есть (не стандартизировать),
  • NAME — разобрать как ФИО,
  • ADDRESS — разобрать как адрес,
  • PHONE — разобрать как телефон.

data — три записи (Федотов, Иванов и Ольга Павловна), каждая из которых содержит четыре поля. Поле — либо одно значение ("Федотов Алексей"), либо массив значений (["мск", "улица свободы", "65", "12"]).

Укажите при вызове:

  • Content-Type: application/json.
  • ${API_KEY} — API-ключ.
  • ${SECRET_KEY} — секретный ключ.
  • Тело запроса передавайте в кодировке UTF-8.

Что в ответе

Возвращаем стандартизованные объекты:

[
    {
    "source": "мск сухонска 11/-89", 
    "result": "г Москва, ул Сухонская, д 11, кв 89", 
    "postal_code": "127642", 
    "country": "Россия", 
    "region_fias_id": "0c5b2444-70a0-4932-980c-b4dc0d3f02b5", 
    "region_kladr_id": "7700000000000", 
    "region_with_type": "г Москва", 
    "region_type": "г", 
    "region_type_full": "город", 
    "region": "Москва", 
    "area_fias_id": null, 
    "area_kladr_id": null, 
    "area_with_type": null, 
    "area_type": null, 
    "area_type_full": null, 
    "area": null, 
    "city_fias_id": null, 
    "city_kladr_id": null, 
    "city_with_type": null, 
    "city_type": null, 
    "city_type_full": null, 
    "city": null, 
    "city_area": "Северо-восточный", 
    "city_district_fias_id": null, 
    "city_district_kladr_id": null, 
    "city_district_with_type": "р-н Северное Медведково", 
    "city_district_type": "р-н", 
    "city_district_type_full": "район", 
    "city_district": "Северное Медведково", 
    "settlement_fias_id": null, 
    "settlement_kladr_id": null, 
    "settlement_with_type": null, 
    "settlement_type": null, 
    "settlement_type_full": null, 
    "settlement": null, 
    "street_fias_id": "95dbf7fb-0dd4-4a04-8100-4f6c847564b5", 
    "street_kladr_id": "77000000000283600", 
    "street_with_type": "ул Сухонская", 
    "street_type": "ул", 
    "street_type_full": "улица", 
    "street": "Сухонская", 
    "house_fias_id": "5ee84ac0-eb9a-4b42-b814-2f5f7c27c255", 
    "house_kladr_id": "7700000000028360004", 
    "house_type": "д", 
    "house_type_full": "дом", 
    "house": "11", 
    "block_type": null, 
    "block_type_full": null, 
    "block": null, 
    "flat_type": "кв", 
    "flat_type_full": "квартира", 
    "flat": "89", 
    "flat_area": "34.6", 
    "square_meter_price": "198113", 
    "flat_price": "6854710", 
    "postal_box": null, 
    "fias_id": "5ee84ac0-eb9a-4b42-b814-2f5f7c27c255", 
    "fias_level": "8", 
    "kladr_id": "7700000000028360004", 
    "capital_marker": "0", 
    "okato": "45280583000", 
    "oktmo": "45362000", 
    "tax_office": "7715", 
    "tax_office_legal": null, 
    "timezone": "UTC+3", 
    "geo_lat": "55.8782606", 
    "geo_lon": "37.6536639", 
    "beltway_hit": "IN_MKAD", 
    "beltway_distance": null, 
    "qc_geo": 0, 
    "qc_complete": 0, 
    "qc_house": 2, 
    "qc": 0, 
    "unparsed_parts": null
}
]
НазваниеДлинаОписание
source 250 Исходный адрес одной строкой
result 500 Стандартизованный адрес одной строкой
postal_code 6 Индекс
country 120 Страна
region_fias_id 36 Код ФИАС региона
region_kladr_id 19 Код КЛАДР региона
region_with_type 131 Регион с типом
region_type 10 Тип региона (сокращенный)
region_type_full 50 Тип региона
region 120 Регион
area_fias_id 36 Код ФИАС района в регионе
area_kladr_id 19 Код КЛАДР района в регионе
area_with_type 131 Район в регионе с типом
area_type 10 Тип района в регионе (сокращенный)
area_type_full 50 Тип района в регионе
area 120 Район в регионе
city_fias_id 36 Код ФИАС города
city_kladr_id 19 Код КЛАДР города
city_with_type 131 Город с типом
city_type 10 Тип города (сокращенный)
city_type_full 50 Тип города
city 120 Город
city_area 120 Административный округ (только для Москвы)
city_district_fias_id 36 Код ФИАС района города (заполняется, только если район есть в ФИАС)
city_district_kladr_id 19 Код КЛАДР района города (не заполняется)
city_district_with_type 131 Район города с типом
city_district_type 10 Тип района города (сокращенный)
city_district_type_full 50 Тип района города
city_district 120 Район города
settlement_fias_id 36 Код ФИАС нас. пункта
settlement_kladr_id 19 Код КЛАДР нас. пункта
settlement_with_type 131 Населенный пункт с типом
settlement_type 10 Тип населенного пункта (сокращенный)
settlement_type_full 50 Тип населенного пункта
settlement 120 Населенный пункт
street_fias_id 36 Код ФИАС улицы
street_kladr_id 19 Код КЛАДР улицы
street_with_type 131 Улица с типом
street_type 10 Тип улицы (сокращенный)
street_type_full 50 Тип улицы
street 120 Улица
house_fias_id 36 Код ФИАС дома
house_kladr_id 19 Код КЛАДР дома
house_type 10 Тип дома (сокращенный)
house_type_full 50 Тип дома
house 50 Дом
block_type 10 Тип корпуса/строения (сокращенный)
block_type_full 50 Тип корпуса/строения
block 50 Корпус/строение
flat_type 10 Тип квартиры (сокращенный)
flat_type_full 50 Тип квартиры
flat 50 Квартира
flat_area 50 Площадь квартиры
square_meter_price 50 Рыночная стоимость м²
flat_price 50 Рыночная стоимость квартиры
postal_box 50 Абонентский ящик
fias_id 36 Код ФИАС
  • HOUSE.HOUSEGUID — если дом найден в ФИАС по точному совпадению;
  • HOUSEINT.INTGUID — если дом найден в ФИАС как часть интервала;
  • ADDROBJ.AOGUID — в противном случае;
fias_level 2 Уровень детализации, до которого адрес найден в ФИАС
  • 0 — страна;
  • 1 — регион;
  • 3 — район;
  • 4 — город;
  • 5 — район города;
  • 6 — населенный пункт;
  • 7 — улица;
  • 8 — дом;
  • 65 — планировочная структура;
  • 90 — доп. территория;
  • 91 — улица в доп. территории;
  • -1 — иностранный или пустой;
kladr_id 19 Код КЛАДР
capital_marker 1 Признак центра района или региона
  • 1 — центр района (Московская обл, Одинцовский р-н, г Одинцово);
  • 2 — центр региона (Новосибирская обл, г Новосибирск);
  • 3 — центр района и региона (Томская обл, г Томск);
  • 4 — центральный район региона (Тюменская обл, Тюменский р-н);
  • 0 — ничего из перечисленного (Московская обл, г Балашиха);
okato 11 Код ОКАТО
oktmo 11 Код ОКТМО
tax_office 4 Код ИФНС для физических лиц
tax_office_legal 4 Код ИФНС для организаций (не заполняется)
timezone 10 Часовой пояс
geo_lat 12 Координаты: широта
geo_lon 12 Координаты: долгота
beltway_hit 8 Внутри кольцевой?
  • IN_MKAD — внутри МКАД (Москва);
  • OUT_MKAD — за МКАД (Москва или Московская область);
  • IN_KAD — внутри КАД (Санкт-Петербург);
  • OUT_KAD — за КАД (Санкт-Петербург или Ленинградская область);
  • пусто — в остальных случаях;
beltway_distance 3 Расстояние от кольцевой в км.
Заполнено, только если beltway_hit = OUT_MKAD или OUT_KAD, иначе пустое
qc_geo 5 Код точности координат
qc_complete 5 Код пригодности к рассылке
qc_house 5 Признак наличия дома в ФИАС
qc 5 Код проверки адреса
unparsed_parts 250 Нераспознанная часть адреса. Для адреса
Москва, Митинская улица, 40к2с2 кв 12, просил доставку после обеда — утром похмелье вернем
ПРОСИЛ, ДОСТАВКУ, ПОСЛЕ, ОБЕДА, УТРОМ, ПОХМЕЛЬЕ

Коды качества

Код проверки (qc) — нужно ли вручную проверить распознанный адрес:

Код qc Описание Нужно проверить вручную?
0 Адрес распознан уверенно Нет
2 Адрес пустой или заведомо «мусорный» Нет
1 Адрес распознан с допущениями или не распознан Да

Код пригодности к рассылке (qc_complete) — годится ли адрес для доставки корреспонденции:

Код qc_complete Подходит для рассылки? Описание
0 Да Пригоден для почтовой рассылки
10 Под вопросом Дома нет в ФИАС
5 Под вопросом Нет квартиры. Подходит для юридических лиц или частных владений
8 Под вопросом До почтового отделения — абонентский ящик или адрес до востребования. Подходит для писем, но не для курьерской доставки.
9 Под вопросом Сначала проверьте, правильно ли Дадата разобрала исходный адрес
1 Нет Нет региона
2 Нет Нет города
3 Нет Нет улицы
4 Нет Нет дома
6 Нет Адрес неполный
7 Нет Иностранный адрес

Признак наличия дома в ФИАС (qc_house) — уточняет вероятность успешной доставки письма:

Код qc_house Вероятность доставки Описание
2 Высокая Дом найден в ФИАС по точному совпадению
3 Средняя В ФИАС найден похожий дом; различие в литере, корпусе или строении
4 Средняя Дом найден в ФИАС по диапазону
10 Низкая Дом не найден в ФИАС

Код точности координат qc_geo — точность координат адреса для курьерской доставки:

Код qc_geo Описание
0 Точные координаты
1 Ближайший дом
2 Улица
3 Населенный пункт
4 Город
5 Координаты не определены
[
    {
    "source": "тел 7165219 доб139", 
    "type": "Рабочий", 
    "phone": "+7 495 716-52-19 доб. 139", 
    "country_code": "7", 
    "city_code": "495", 
    "number": "7165219", 
    "extension": "139", 
    "provider": "ОАО \"МГТС\"", 
    "region": "Москва", 
    "timezone": "UTC+3", 
    "qc_conflict": 0, 
    "qc": 1
}
]
НазваниеДлинаОписание
source 100 Исходный телефон одной строкой
type 50 Тип телефона
phone 50 Стандартизованный телефон одной строкой
country_code 5 Код страны
city_code 5 Код города / DEF-код
number 10 Локальный номер телефона
extension 10 Добавочный номер
provider 100 Оператор связи
region 100 Регион
timezone 10 Часовой пояс
qc_conflict 5 Признак конфликта телефона с адресом
qc 5 Код проверки

Коды качества

Код проверки (qc) — нужно ли вручную проверить распознанный телефон:

Код qc Описание Нужно проверить вручную?
0 Телефон распознан уверенно Нет
2 Телефон пустой или заведомо «мусорный» Нет
1 Телефон распознан с допущениями или не распознан Да
3 Обнаружено несколько телефонов, распознан первый Да

Признак конфликта телефона с адресом (qc_conflict) — указал ли клиент телефон, соответствующий его адресу. Удобно для проверки уровня риска:

Код qc_conflict Описание
0 Телефон соответствует адресу
2 Города адреса и телефона отличаются
3 Регионы адреса и телефона отличаются
[
    {
    "source": "4509 235857", 
    "series": "45 09", 
    "number": "235857", 
    "qc": 0
}
]
НазваниеДлинаОписание
source 100 Исходная серия и номер одной строкой
series 20 Серия
number 20 Номер
qc 5 Код проверки

Код качества

Код проверки (qc) — действует паспорт или нет, по данным Федеральной миграционной службы:

Код qc Описание Нужно проверить вручную?
0 Действующий паспорт Нет
2 Исходное значение пустое Нет
1 Неправильный формат серии или номера Да
10 Недействительный паспорт Да
[
    {
    "source": "Срегей владимерович иванов", 
    "result": "Иванов Сергей Владимирович", 
    "result_genitive": "Иванова Сергея Владимировича", 
    "result_dative": "Иванову Сергею Владимировичу", 
    "result_ablative": "Ивановым Сергеем Владимировичем", 
    "surname": "Иванов", 
    "name": "Сергей", 
    "patronymic": "Владимирович", 
    "gender": "М", 
    "qc": 1
}
]
НазваниеДлинаОписание
source 100 Исходное ФИО одной строкой
result 150 Стандартизованное ФИО одной строкой
result_genitive 150 ФИО в родительном падеже (кого?)
result_dative 150 ФИО в дательном падеже (кому?)
result_ablative 150 ФИО в творительном падеже (кем?)
surname 50 Фамилия
name 50 Имя
patronymic 50 Отчество
gender 10 Пол
  • М — мужской;
  • Ж — женский;
  • НД — не удалось однозначно определить;
qc 5 Код проверки

Код качества

Код проверки (qc) — требуется ли вручную проверить распознанное значение:

Код qc Описание Нужно проверить вручную?
0 Исходное значение распознано уверенно Нет
2 Исходное значение пустое или заведомо «мусорное» Нет
1 Исходное значение распознано с допущениями или не распознано Да
[
    {
    "source": "serega@yandex/ru", 
    "email": "serega@yandex.ru", 
    "qc": 4
}
]
НазваниеДлинаОписание
source 100 Исходный email
email 100 Стандартизованный email
qc 5 Код проверки

Код качества

Код проверки (qc) — подходит ли email для маркетинговой рассылки:

Код qc Описание Нужно проверить вручную?
0 Корректное значение
Соответствует общепринятым правилам,
реальное существование адреса не проверяется
Нет
2 Пустое или заведомо «мусорное» значение Нет
3 «Одноразовый» адрес
Домены 10minutemail.com, getairmail.com, temp-mail.ru и аналогичные
Нет
1 Некорректное значение
Не соответствует общепринятым правилам
Да
4 Исправлены опечатки Да
[
    {
    "source": "24/3/12", 
    "birthdate": "24.03.2012", 
    "qc": 1
}
]
НазваниеДлинаОписание
source 100 Исходная дата
birthdate 100 Стандартизованная дата
qc 5 Код проверки

Код качества

Код проверки (qc) — требуется ли вручную проверить распознанное значение:

Код qc Описание Нужно проверить вручную?
0 Исходное значение распознано уверенно Нет
2 Исходное значение пустое или заведомо «мусорное» Нет
1 Исходное значение распознано с допущениями или не распознано Да
[
    {
    "source": "форд фокус", 
    "result": "FORD FOCUS", 
    "brand": "FORD", 
    "model": "FOCUS", 
    "qc": 0
}
]
НазваниеДлинаОписание
source 100 Исходное значение
result 100 Стандартизованное значение
brand 50 Марка
model 50 Модель
qc 5 Код проверки

Код качества

Код проверки (qc) — требуется ли вручную проверить распознанное значение:

Код qc Описание Нужно проверить вручную?
0 Исходное значение распознано уверенно Нет
2 Исходное значение пустое или заведомо «мусорное» Нет
1 Исходное значение распознано с допущениями или не распознано Да
{
    "structure": [
        "AS_IS",
        "NAME",
        "ADDRESS",
        "PHONE"
    ],
    "data": [
        [{
            "source": "1"
        }, {
            "source": "Федотов Алексей",
            "result": "Федотов Алексей",
            ...
            "qc": 0
        }, {
            "source": "Москва, Сухонская улица, 11 кв 89",
            "result": "г Москва, ул Сухонская, д 11, кв 89",
            ...
            "qc": 0,
            "unparsed_parts": null
    }, {
            "source": "8 916 823 3454",
            "type": "Мобильный",
            "phone": "+7 916 823-34-54",
            ...
            "qc": 0
        }],
        [{
            "source": "2"
        }, {
            "source": "Иванов Сергей Владимирович",
            "result": "Иванов Сергей Владимирович",
            ...
            "qc": 0
        }, {
            "source": "мск,улица свободы,65,12",
            "result": "г Москва, ул Свободы, д 65, кв 12",
            ...
            "qc": 0,
            "unparsed_parts": null
        }, {
            "source": "495 663-12-53",
            "type": "Городской",
            "phone": "+7 495 663-12-53",
            ...
            "qc": 0
        }],
        [{
            "source": "3"
        }, {
            "source": "Ольга Павловна Ященко",
            "result": "Ященко Ольга Павловна",
            ...
            "qc": 0
        }, {
            "source": "Спб, ул Петрозаводская 8",
            "result": "Россия, г Санкт-Петербург, ул Петрозаводская, д 8",
            ...
            "qc": 0,
            "unparsed_parts": null
        }, {
            "source": "457 07 25",
            "type": "Городской",
            "phone": "+7 812 457-07-25",
            ...
            "qc": 1
        }]
    ]
}

Структура записи

Обрабатывайте разные типы данных:

Тип Описание
ADDRESS Почтовый адрес
PHONE Телефон
PASSPORT Номер или серия паспорта
NAME ФИО
EMAIL Адрес электронной почты
VEHICLE Марка и модель автомобиля
IGNORE Игнорировать поле (будет отсутствовать в ответе)
AS_IS Скопировать поле в ответ «как есть»

Коды ответа на запрос

HTTP-код ответа Описание
200 Запрос успешно обработан
400 Некорректный запрос:
  • Невалидный JSON.
  • Отсутствуют обязательные параметры structure или data.
  • В structure указан неподдерживаемый тип.
  • Количество полей в записях более указанного в structure.
401 В запросе отсутствует API-ключ или секретный ключ
402 Недостаточно средств для обработки запроса, пополните баланс
403 В запросе указан несуществующий ключ
405 Запрос сделан с методом, отличным от POST
413 Запрос содержит более 10 записей
5xx Произошла внутренняя ошибка сервиса во время обработки

Ограничения

В запросе может быть до 10 записей.

Максимальное количество полей в одной записи:

  • 1 ФИО,
  • 3 адреса,
  • 3 телефона,
  • 3 email.

Максимальная частота запросов:

  • 10 запросов/сек, если в запросе 1 запись;
  • 5 запросов/сек, если в запросе 2 записи;
  • 2 запроса/сек, если в запросе 5 записей;
  • 1 запрос/сек, если в запросе 10 записей.

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

Стоимость

API стандартизации стоит 5–10 копеек за запись.

Примеры вызова API на разных платформах

ajax-spinner

Обрабатывайте файлы, вызывайте API

первые 100 записей — бесплатно

чтобы обращаться к вам в письмах

Регистрируясь, вы принимаете публичную оферту

Уже зарегистрированы? Войти