API: подсказки по email
Что умеет и не умеет
✔️ Подсказывает локальную часть (до «собачки»).
✔️ Подсказывает доменную часть (после «собачки»).
✔️ Исправляет опечатки (yadex.ru → yandex.ru).
Не умеет:
❌ Автоматически (без участия человека) проверить адреса из базы или файла.
❌ Классифицировать адреса на личные (@mail.ru, @yandex.ru), корпоративные (@myshop.ru) и «ролевые» (info@, support@).
Подсказки не подходят для автоматической обработки email. Они предлагают варианты, но не гарантируют, что угадали правильно. Поэтому окончательное решение всегда должен принимать человек.
Для автоматической обработки и классификации адресов используйте API Стандартизации
Как вызвать
Чтобы вызвать метод, и подтвердите почту.
Пример запроса:
POST http://suggestions.dadata.ru/suggestions/api/4_1/rs/suggest/email{ "query": "anton@" }
Укажите при вызове:
Content-Type: application/json
.Accept: application/json
.${API_KEY}
— API-ключ.
Тело запроса передавайте в кодировке UTF-8
.
Параметры запроса
Название | Тип | Обяз.? | По умолч. | Описание |
---|---|---|---|---|
query | string | ✓ | Текст запроса | |
count | number | 10 | Количество результатов (максимум — 20) |
Что в ответе
Объект с массивом подсказок в поле suggestions
:
Пример ответа
{
"suggestions": [
{
"value": "anton@mail.ru",
"unrestricted_value": "anton@mail.ru",
"data": {
"local": "anton",
"domain": "mail.ru",
"type": null,
"source": null,
"qc": null
}
},
...
]
}
Название | Описание |
---|---|
value | Email одной строкой |
unrestricted_value | = value |
data.local | Локальная часть адреса (то, что до «собачки») |
data.domain | Домен (то, что после «собачки») |
Зарезервированы для автоматической обработки адресов через API стандартизации | |
data.type | |
data.source | |
data.qc |
Источники данных: собственные справочники.
Коды ответа на запрос
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
- Symfony
Ограничения
Длина запроса (параметр query
) — не более 300 символов.
Количество запросов в день — в соответствии с тарифным планом.
Максимальная частота запросов — 30 в секунду с одного IP-адреса.
Максимальная частота создания новых соединений — 60 в минуту с одного IP-адреса.
Частые вопросы
Подсказки не работают: ошибка 403 Forbidden (Feature SUGGESTIONS disabled for token)
Возможные причины:
- Не подтверждён адрес эл. почты. Проверьте в личном кабинете. Если почта не подтверждена — посмотрите почтовый ящик и папку «спам», там должно быть письмо от «Дадаты».
- В запросе указан неправильный API-ключ. Проверьте в личном кабинете
- Исчерпан лимит запросов на день. Проверьте в личном кабинете
Что будет, если превысить 10 000 бесплатных запросов в день?
Подсказки перестанут подсказывать ツ До начала нового дня, затем снова заработают.
10 000 запросов считаются суммарно по всем видам подсказок: адреса, ФИО, организации, банки, емейлы...
Стоимость
Бесплатно до 10 тысяч запросов в день. Больше — в составе годовой подписки.