API: подсказки по email
Что умеет и не умеет
✔️ Подсказывает локальную часть (до «собачки»).
✔️ Подсказывает доменную часть (после «собачки»).
✔️ Исправляет опечатки (yadex.ru → yandex.ru).
Не умеет:
❌ Автоматически (без участия человека) проверить адреса из базы или файла.
❌ Классифицировать адреса на личные (@mail.ru, @yandex.ru), корпоративные (@myshop.ru) и «ролевые» (info@, support@).
Подсказки не подходят для автоматической обработки email. Они предлагают варианты, но не гарантируют, что угадали правильно. Поэтому окончательное решение всегда должен принимать человек.
Для автоматической обработки и классификации адресов используйте API Стандартизации
Как вызвать
Чтобы вызвать метод, зарегистрируйтесь и подтвердите почту.
Пример запроса:
curl -X POST \ -H "Content-Type: application/json" \ -H "Accept: application/json" \ -H "Authorization: Token ${API_KEY}" \ -d '{ "query": "anton@" }' \ https://suggestions.dadata.ru/suggestions/api/4_1/rs/suggest/email
// https://github.com/hflabs/dadata-csharp var token = "${API_KEY}"; var api = new SuggestClientAsync(token); var result = await api.SuggestEmail("anton@");
// https://github.com/ekomobile/dadata // Использует API-ключ из переменной окружения DADATA_API_KEY import ( "context" dadata "github.com/ekomobile/dadata/v2" "github.com/ekomobile/dadata/v2/api/suggest" ) func main() { api := dadata.NewSuggestApi() params := suggest.RequestParams{Query: "anton@"} result, err := api.Email(context.Background(), ¶ms) }
var url = "https://suggestions.dadata.ru/suggestions/api/4_1/rs/suggest/email"; var token = "${API_KEY}"; var query = "anton@"; var options = { method: "POST", mode: "cors", headers: { "Content-Type": "application/json", "Accept": "application/json", "Authorization": "Token " + token }, body: JSON.stringify({query: query}) } fetch(url, options) .then(response => response.text()) .then(result => console.log(result)) .catch(error => console.log("error", error));
// https://github.com/hflabs/dadata-php $token = "${API_KEY}"; $dadata = new \Dadata\DadataClient($token, null); $result = $dadata->suggest("email", "anton@");
# https://github.com/hflabs/dadata-py from dadata import Dadata token = "${API_KEY}" dadata = Dadata(token) result = dadata.suggest("email", "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 | Произошла внутренняя ошибка сервиса |
Примеры вызова
Ограничения
Длина запроса (параметр query
) — не более 300 символов.
Количество запросов в день — в соответствии с тарифным планом.
Максимальная частота запросов — 30 в секунду с одного IP-адреса.
Максимальная частота создания новых соединений — 60 в минуту с одного IP-адреса.
Частые вопросы
Подсказки не работают: ошибка 403 Forbidden (Feature SUGGESTIONS disabled for token)
Возможные причины:
- Не подтверждён адрес эл. почты. Проверьте в личном кабинете. Если почта не подтверждена — посмотрите почтовый ящик и папку «спам», там должно быть письмо от «Дадаты».
- В запросе указан неправильный API-ключ. Проверьте в личном кабинете
- Исчерпан лимит запросов на день. Проверьте в личном кабинете
Что будет, если превысить 10 000 бесплатных запросов в день?
Подсказки перестанут подсказывать ツ До начала нового дня, затем снова заработают.
10 000 запросов считаются суммарно по всем видам подсказок: адреса, ФИО, организации, банки, емейлы...
Стоимость
Бесплатно до 10 тысяч запросов в день. Больше — в составе годовой подписки.