↑ API подсказок

API подсказок по ФИО

Что умеет и не умеет

✔️ Подсказывает ФИО одной строкой или отдельно фамилию, имя, отчество.

✔️ Исправляет клавиатурную раскладку («fynjy» → «Антон»).

✔️ Определяет пол.

Не умеет:

❌ Автоматически (без участия человека) обработать ФИО из базы или файла.

❌ Транслитерировать (Juliia Somova → Юлия Сомова).

❌ Склонять по падежам (кого? кому? кем?).

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

Для автоматической обработки, транслитерации и склонения по падежам используйте API Стандартизации

Как вызвать

Чтобы вызвать метод, зарегистрируйтесь и подтвердите почту.

Пример запроса:

curl -X POST \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -H "Authorization: Token ${API_KEY}" \
    -d '{ "query": "Викт" }' \
    https://suggestions.dadata.ru/suggestions/api/4_1/rs/suggest/fio

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

  • Content-Type: application/json или application/xml.
  • Accept — аналогично.
  • ${API_KEY} — API-ключ.

Тело запроса передавайте в кодировке UTF-8.

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

Название Обязательный? По умолчанию Описание
query Текст запроса
count 10 Количество результатов (максимум — 20)
gender Пол (UNKNOWN / MALE / FEMALE)
parts Подсказки по части ФИО

Что в ответе

Объект с массивом подсказок в поле suggestions:

Пример ответа
{
"suggestions": [
        {
            "value": "Виктор",
            "unrestricted_value": "Виктор",
            "data": {
                "surname": null,
                "name": "Виктор",
                "patronymic": null,
                "gender": "MALE",
                "source": null,
                "qc": "0"
            }
        },
        ...
    ]
}
Название Описание
value ФИО одной строкой
unrestricted_value = value
data.surname Фамилия
data.name Имя
data.patronymic Отчество
data.gender Пол
  MALE    — мужской
  FEMALE  — женский
  UNKNOWN — не удалось однозначно определить
data.qc Код проверки
  0 — все части ФИО известны
  1 — в ФИО есть неизвестная часть
Не используется
data.source

Источники данных: собственные справочники имен, фамилий и отчеств.

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

HTTP-код ответа Описание
200 Запрос успешно обработан
400 Некорректный запрос (невалидный JSON или XML)
401 В запросе отсутствует API-ключ
403 В запросе указан несуществующий API-ключ
Или не подтверждена почта
Или исчерпан дневной лимит по количеству запросов
405 Запрос сделан с методом, отличным от POST
413 Слишком большая длина запроса или слишком много условий
429 Слишком много запросов в секунду или новых соединений в минуту
5xx Произошла внутренняя ошибка сервиса

Примеры вызова

Заголовки и параметры

Гранулярные подсказки (отдельно фамилия, отдельно имя, отдельно отчество)

Ограничения

Длина запроса (параметр query) — не более 300 символов.

Количество запросов в день — в соответствии с тарифным планом.

Максимальная частота запросов — 20 в секунду.

Максимальная частота создания новых соединений — 60 в минуту.

Частые вопросы

Как сделать отдельные подсказки по имени?

Пример: подсказки по имени

Пример: подсказки по имени и отчеству

Пример: подсказки по имени и фамилии

Как сделать гранулярные подсказки по ФИО? Чтобы отдельно фамилия, имя, отчество?

Пример: гранулярные подсказки ФИО

Подсказки не работают: ошибка 403 Forbidden (Feature SUGGESTIONS disabled for token)

Возможные причины:

  • Не подтверждён адрес эл. почты. Проверьте в личном кабинете. Если почта не подтверждена — посмотрите почтовый ящик и папку «спам», там должно быть письмо от «Дадаты».
  • В запросе указан неправильный API-ключ. Проверьте в личном кабинете
  • Исчерпан лимит запросов на день. Проверьте в личном кабинете
  • Вы делаете запросы с сервера, при этом настроена привязка к домену. Отключите привязку к домену, либо делайте запросы из браузера.
Что будет, если превысить 10 000 бесплатных запросов в день?

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

10 000 запросов считаются суммарно по всем видам подсказок: адреса, ФИО, организации, банки, емейлы...

Как защитить API-ключ от злоумышленников?

Если вы используете jQuery-плагин Подсказок, то API-ключ можно посмотреть в исходном коде страниц вашего сайта. Чтобы злоумышленник не мог воспользоваться вашим ключом, можно привязать его к конкретному домену в личном кабинете.

Если вы подключили Подсказки не через jQuery-плагин, а из программы через API, злоумышленник не сможет подсмотреть ключ. В этом случае привязка к домену не требуется.

Если вы используете и jQuery-плагин, и работу через API — привязку к домену придётся отключить (иначе она «не пропустит» API-запросы). Мы рекомендуем использовать что-то одно — или плагин, или API — но не оба способа одновременно.

Стоимость

Бесплатно до 10 тысяч запросов в день. Больше — в составе годовой подписки.

ajax-spinner

Зарегистрируйтесь, чтобы подключить подсказки

до 10 тыс. запросов бесплатно

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

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

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