↑ Все API

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

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

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

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

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

Не умеет:

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

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

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

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

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

Как вызвать

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

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

            
                POST http://suggestions.dadata.ru/suggestions/api/4_1/rs/suggest/fio
            
            
{ "query": "Викт" }

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

  • Content-Type: application/json.
  • Accept: application/json.
  • ${API_KEY} — API-ключ.

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

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

НазваниеТипОбяз.? По умолч. Описание
querystringТекст запроса
countnumber 10 Количество результатов (максимум — 20)
genderstringПол (UNKNOWN / MALE / FEMALE)
partsarray [string] Подсказки по части ФИО

Что в ответе

Объект с массивом подсказок в поле 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 символов.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Стоимость

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