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
.
Параметры запроса
Название | Тип | Обяз.? | По умолч. | Описание |
---|---|---|---|---|
query | string | ✓ | Текст запроса | |
count | number | 10 | Количество результатов (максимум — 20) | |
gender | string | Пол (UNKNOWN / MALE / FEMALE ) | ||
parts | array [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 | Произошла внутренняя ошибка сервиса |
Примеры вызова
Гранулярные подсказки (отдельно фамилия, отдельно имя, отдельно отчество)
- Angular
- C# / .NET
- Excel VBA
- Go
- Java (Spring)
- Laravel
- Node.js
- PHP
- PHP (одним файлом)
- Python
- R
- React
- WinHttpRequest
- iOS
- Symfony
- 1С: ФИО
Ограничения
Длина запроса (параметр query
) — не более 300 символов.
Количество запросов в день — в соответствии с тарифным планом.
Максимальная частота запросов — 30 в секунду с одного IP-адреса.
Максимальная частота создания новых соединений — 60 в минуту с одного IP-адреса.
Частые вопросы
Как сделать отдельные подсказки по имени?
Пример: подсказки по имени
Пример: подсказки по имени и отчеству
Пример: подсказки по имени и фамилии
Как сделать гранулярные подсказки по ФИО? Чтобы отдельно фамилия, имя, отчество?
Пример: гранулярные подсказки ФИО
Подсказки не работают: ошибка 403 Forbidden (Feature SUGGESTIONS disabled for token)
Возможные причины:
- Не подтверждён адрес эл. почты. Проверьте в личном кабинете. Если почта не подтверждена — посмотрите почтовый ящик и папку «спам», там должно быть письмо от «Дадаты».
- В запросе указан неправильный API-ключ. Проверьте в личном кабинете
- Исчерпан лимит запросов на день. Проверьте в личном кабинете
Что будет, если превысить 10 000 бесплатных запросов в день?
Подсказки перестанут подсказывать ツ До начала нового дня, затем снова заработают.
10 000 запросов считаются суммарно по всем видам подсказок: адреса, ФИО, организации, банки, емейлы...
Стоимость
Бесплатно до 10 тысяч запросов в день. Больше — в составе годовой подписки.