API: подсказки по email
Что умеет и не умеет
✔️ Подсказывает локальную часть (до «собачки»).
✔️ Подсказывает доменную часть (после «собачки»).
✔️ Исправляет опечатки (yadex.ru → yandex.ru).
Не умеет:
❌ Автоматически (без участия человека) проверить адреса из базы или файла.
❌ Классифицировать адреса на личные (@mail.ru, @yandex.ru), корпоративные (@myshop.ru) и «ролевые» (info@, support@).
Подсказки не подходят для автоматической обработки email. Они предлагают варианты, но не гарантируют, что угадали правильно. Поэтому окончательное решение всегда должен принимать человек.
Для автоматической обработки и классификации адресов используйте API Стандартизации
Как вызвать
Чтобы вызвать метод, и подтвердите почту.
Пример запроса:
POST https://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 тысяч запросов в день. Больше — в составе годовой подписки.