Русский · English
Готовые примеры работы с API валидации телефона на шести языках: Python, TypeScript (Node.js), Go, Java, C#, PHP. Проверка номера телефона любой страны: валиден ли он, как правильно записывается (формат E.164, международный, национальный, RFC 3966), из какой он страны, мобильный это номер или стационарный, какому оператору выделен диапазон и в каких часовых поясах он лежит.
Разбор идёт локально, по встроенному справочнику мировой нумерации: без обращений к оператору, без ожидания сети — ответ за единицы миллисекунд.
Каждый пример запускается сразу — без регистрации, без ключа, без карты. В коде зашит публичный демо-ключ.
git clone https://github.com/atlorium-api/phone-validation-api-client
cd phone-validation-api-client/python && pip install -r requirements.txt && python main.pyДемо-ключ: ответы сгенерированы (моки), не реальные данные.
вход E.164 тип решение
------------------------------------------------------------------------------
+79161234567 +79161234567 Mobile KEEP мобильный
+7 (916) 123-45-67 +79161234567 Mobile DUP дубль '+79161234567'
8 916 123-45-67 +89161234567 Mobile KEEP мобильный
+7 495 785-63-00 +74957856300 Mobile KEEP мобильный
+7 809 123-45-67 +78091234567 Mobile KEEP мобильный
+1 650 253 0000 +16502530000 Mobile KEEP мобильный
12345 — — DROP не распознан как телефонный номер
К отправке SMS: 5
Только для обзвона: 0
Отброшено: 1
Дублей схлопнулось: 1
По странам: FR — 1, GB — 1, RU — 3
По типам: Mobile — 5
К отправке (E.164 — то, что принимают SMS-шлюзы):
+79161234567 МегаФон [Europe/Moscow, Asia/Yekaterinburg, Asia/Novosibirsk]
+89161234567 Orange [Europe/London]
+74957856300 Билайн [Europe/Moscow, Asia/Yekaterinburg, Asia/Novosibirsk]
+78091234567 МТС [Europe/Moscow, Asia/Yekaterinburg, Asia/Novosibirsk]
+16502530000 Verizon [Europe/Berlin]
Демо-ключ отвечает моками, а не реальным разбором номера. Мок не поднимает библиотеку нумерации: он всегда отдаёт
isValid: trueиnumberType: Mobile, аe164собирает из цифр входа как есть. Отсюда все странности вывода выше — и мы их не подкручиваем, а объясняем:
- московский городской
+7 495 785-63-00и премиум-номер+7 809 …не отсеялись, хотя на боевом ключе стали быFixedLineиPremiumRate;8 916 123-45-67не схлопнулся со своим близнецом+7 916 …: мок не знает, что ведущая8— это+7, и вернул несуществующий «+89161234567». На боевом ключе оба номера дают+79161234567и склеиваются в один контакт;- страна в моке определяется по ведущему
+7, остальным она выдаётся случайно — отсюдаFRиGBу номеров, которые ими не являются.Подставьте боевой ключ — тот же код начнёт возвращать настоящий разбор. Логика примера при этом не меняется ни на строку: он уже сейчас умеет обрабатывать все типы номеров, просто песочнице их неоткуда взять.
Проверить телефон в форме регистрации до того, как на него уйдёт SMS с кодом. Почистить базу контактов перед рассылкой. Привести телефоны в CRM к единому виду, чтобы одна и та же запись не лежала в базе трижды. Отличить мобильный от стационарного перед выбором канала связи. Понять, в каком часовом поясе абонент, чтобы не позвонить ему в три часа ночи.
Примеры не просто печатают JSON, а применяют данные: в каждом есть функция normalizeContactList(), которая готовит базу контактов к SMS-рассылке:
| Что на входе | Решение | Почему |
|---|---|---|
isValid: false |
DROP | Номер не попадает в реально выделенный диапазон. SMS уйдёт в никуда, а деньги за неё спишут |
numberType: PremiumRate |
DROP + предупреждение | Премиум-номера тарифицируются по повышенной ставке: случайная отправка бьёт по бюджету |
numberType: FixedLine |
DROP для SMS | Стационарный номер SMS не примет — но это живой контакт, помечаем как годный для голосового обзвона |
numberType: Voip |
FLAG | Виртуальные номера часто используют как одноразовые: повышенный риск фрода при верификации |
numberType: Mobile, isValid: true |
KEEP | Приводим к E.164 — единственному формату, который принимают SMS-шлюзы. Сохраняем timeZones, чтобы не слать сообщения ночью по местному времени |
Плюс дедупликация: «8 916 123-45-67» и «+7 916 123 45 67» — это один и тот же человек, но в базе они лежат как две разные строки. После приведения к E.164 они схлопываются в один контакт. За каждую лишнюю SMS платит отправитель, поэтому дедупликация — это прямая экономия, а не косметика.
В конце — сводка: сколько номеров к отправке, сколько отброшено, сколько дублей схлопнулось, разбивка по странам и типам номеров.
Это важнее, чем список возможностей, поэтому написано до раздела «Быстрый старт», а не мелким шрифтом внизу.
Сервис отвечает на вопрос «может ли такой номер существовать и как он правильно записывается». Он НЕ проверяет, пользуется ли номером живой абонент, и не сообщает никаких сведений о владельце.
- «Валидный номер» не значит «рабочий номер».
isValid: trueозначает ровно одно: номер записан правильно и попадает в диапазон, реально выделенный в его стране. Он может быть не продан никому, отключён за неуплату или лежать в столе выключенным.- Активность в сети, текущий оператор, MNP-перенос, роуминг, MCC/MNC, IMSI — НЕ возвращаются. Это персональные данные конкретного абонента; получить их можно только запросом в сеть оператора, а сервис таких запросов не делает — он работает офлайн.
originalCarrier— это оператор ДИАПАЗОНА, тот, кому диапазон выделен изначально. С 2013 года абонент вправе перенести номер к другому оператору, сохранив его (MNP), и справочник нумерации об этом не знает и знать не может. Перенесённых номеров в России миллионы, поэтому для случайного номера это поле — обоснованная догадка, а не факт. Не стройте на нём тарификацию звонков или выбор SMS-маршрута.location— это привязка диапазона, а не местоположение абонента. Владелец московского номера может пить кофе в Лиссабоне. У мобильных номеров это поле обычно пустое (null) — и это честный ответ, а не потеря данных.Полноценная проверка существования адресата у Atlorium есть только для электронной почты — сервис Проверка почты действительно ходит на почтовый сервер и выясняет, существует ли ящик. Для телефонов такого сервиса нет ни у нас, ни, честно говоря, у большинства тех, кто обещает подобное.
Проверить API вообще без клонирования:
curl -H "Authorization: Bearer ak_sandbox_demo_mockdata_v1" \
"https://atlorium.com/api/Phone/%2B79161234567"Обратите внимание на %2B — так кодируется знак +. Если отправить его как есть, часть веб-серверов и прокси прочитает его как пробел, номер потеряет код страны и разбор развалится. Во всех шести примерах номер кодируется правильно.
| Язык | Запуск | Требуется |
|---|---|---|
| Python | pip install -r requirements.txt && python main.py |
Python 3.10+ |
| TypeScript / Node.js | npm install && npm start |
Node.js 20+ |
| Go | go run . |
Go 1.22+ |
| Java | java Main.java |
JDK 17+ (без зависимостей) |
| C# | dotnet run |
.NET 8+ |
| PHP | php main.php |
PHP 8.1+ |
Передать свои номера списком через запятую:
python main.py "+79161234567,8 495 785-63-00,+1 650 253 0000"Ключ передаётся в заголовке Authorization:
Authorization: Bearer ВАШ_КЛЮЧ
| Ключ | Что делает |
|---|---|
ak_sandbox_demo_mockdata_v1 |
Демо-ключ. Публичный, один на всех. Возвращает моки, денег не списывает, регистрации не требует. Ответы детерминированы — на них можно писать стабильные тесты. |
| Боевой ключ | Настоящий разбор номера. Получить в личном кабинете: atlorium.com |
Переход на боевой ключ не требует правок в коде — все примеры читают переменную окружения:
export ATLORIUM_API_KEY="ak_ваш_боевой_ключ"Каждый ответ песочницы помечен заголовком X-Atlorium-Sandbox: true — перепутать мок с реальными данными невозможно.
Базовый адрес: https://atlorium.com
| Метод | Путь | Назначение |
|---|---|---|
GET |
/api/Phone/{number} |
Разбор номера: валидность, форматы записи, страна, тип, оператор диапазона, часовые пояса |
| Параметр | Где | Тип | Описание |
|---|---|---|---|
number |
путь | string | Обязателен. Номер в международном формате (+79161234567) или национальном (8 916 123-45-67). Пробелы, скобки и дефисы допустимы. Знак + в URL кодируется как %2B. |
countryCode |
query | string | Необязателен. Код страны по ISO-3166 alpha-2 (например, RU) — в какой стране трактовать номер, записанный без +. Для номеров с + не нужен и игнорируется. |
Два эквивалентных запроса:
GET /api/Phone/%2B79161234567
GET /api/Phone/89161234567?countryCode=RU
Если номер записан без + и countryCode не передан, страну определить не из чего — сервис ответит 400.
Полезная нагрузка вложена в объект number — не забудьте про этот уровень при разборе.
| Поле | Тип | Что содержит |
|---|---|---|
input |
string | Номер в том виде, в каком вы его прислали |
number |
object | Результат разбора — все поля ниже лежат внутри него |
elapsedMs |
number | Время разбора в миллисекундах |
Внутри number:
| Поле | Тип | Что содержит |
|---|---|---|
isValid |
bool | Ключевое поле. Номер попадает в реально выделенный диапазон своей страны — а не просто подходит по длине. Не означает, что за номером есть живой абонент |
isPossible |
bool | Номер лишь похож на телефонный: подходящая длина, но диапазон может быть не выделен. Мягче, чем isValid. Если false — это точно не телефон |
e164 |
string | Канонический формат: +79161234567. Именно его стоит хранить в базе и отдавать SMS-шлюзу |
international |
string | Международный формат для показа человеку: +7 916 123-45-67 |
national |
string | Национальный формат, принятый в стране номера: 8 (916) 123-45-67 |
rfc3966 |
string | Формат RFC 3966 — готовая ссылка для набора: tel:+7-916-123-45-67. Удобно подставлять в href |
countryCallingCode |
number | Телефонный код страны без плюса: 7, 1, 44 |
countryCode |
string | Код страны по ISO-3166 alpha-2: RU. Для кодов, общих у нескольких стран (+7 у России и Казахстана, +1 у США и Канады), страна определяется по следующим цифрам |
country |
string | Название страны: Россия |
numberType |
string | Тип номера — см. таблицу ниже |
originalCarrier |
string | Оператор диапазона: МегаФон. Не обязательно текущий оператор абонента — см. раздел «Границы сервиса». null, если неизвестен |
location |
string | Географическая привязка диапазона, а не абонента. У мобильных номеров обычно null |
timeZones |
array | Часовые пояса диапазона в формате IANA: ["Europe/Moscow", "Asia/Yekaterinburg"]. У мобильных номеров больших стран их несколько — абонент может быть в любом из них |
| Значение | Что это |
|---|---|
Mobile |
Мобильный номер |
FixedLine |
Стационарный (городской) |
FixedLineOrMobile |
Страна не разделяет мобильные и стационарные — так устроена нумерация, например, в США |
TollFree |
Бесплатный для звонящего (8-800 и мировые аналоги) |
PremiumRate |
Повышенная тарификация звонка |
SharedCost |
Плата делится между звонящим и принимающим |
Voip |
IP-телефония |
PersonalNumber |
Персональный номер с переадресацией |
Pager |
Пейджер |
Uan |
Универсальный номер доступа, обычно корпоративный |
Voicemail |
Голосовая почта |
Unknown |
Справочник не знает такого диапазона |
| Код | Причина | Что делать |
|---|---|---|
400 |
Строка не является телефонным номером: не тот формат, неподходящая длина, либо номер записан без + и не передан countryCode |
Проверьте номер и наличие countryCode для национальной записи |
401 |
Ключ отсутствует, просрочен или недействителен | Проверьте заголовок Authorization |
402 |
Недостаточно кредитов на балансе | Пополнить на atlorium.com |
429 |
Превышен rate-limit | Повторить с задержкой |
Кода 404 у этого сервиса нет: номер либо разбирается, либо не является номером — и тогда это 400. Кода 503 тоже нет: сервис работает офлайн, внешнему источнику попросту нечему падать.
Строка, которая не является телефоном, не тарифицируется. Она отсекается до резервирования кредита — вы не платите за то, что кто-то ввёл в форму «звонить в офис».
Во всех шести примерах коды разложены в человекочитаемые причины — смотрите класс AtloriumError.
Оплата pay-as-you-go, без подписки: платите только за выполненные запросы. Разбор локальный, поэтому тариф у сервиса один из самых низких.
Актуальные цены и лимиты: atlorium.com/pricing
Как проверить номер телефона на валидность через API? Один GET-запрос на /api/Phone/{number} — и в ответе поле isValid. Оно означает, что номер записан правильно и попадает в реально выделенный диапазон своей страны, а не просто подходит по длине.
Можно ли узнать, что номером реально пользуются? Нет. И это принципиальное ограничение, а не недоделка: активность номера знает только сеть оператора, а такие сведения относятся к конкретному абоненту. Сервис работает офлайн и в сеть оператора не ходит. Если вам нужно проверить, существует ли почтовый ящик, — это умеет Проверка почты.
Точно ли определяется оператор по номеру? originalCarrier — это оператор диапазона, а не фактический. Из-за переносимости номеров (MNP) абонент мог уйти к другому оператору, сохранив номер, и справочник нумерации об этом не знает. Для случайного номера считайте это обоснованной догадкой. Тарификацию звонков и выбор SMS-маршрута на этом поле строить нельзя.
Что такое формат E.164 и зачем приводить к нему номера? E.164 — международный канонический вид: +79161234567, без пробелов, скобок и дефисов. Это единственный формат, который принимают SMS-шлюзы, и единственный, в котором один и тот же номер записывается ровно одним способом. Храните телефоны в базе в E.164 — и дубли «8 916…» / «+7 916…» исчезнут сами.
Как отличить мобильный номер от стационарного? Поле numberType: Mobile или FixedLine. Учтите, что в ряде стран (например, в США) нумерация их не разделяет — там вернётся FixedLineOrMobile, и отличить одно от другого по справочнику невозможно в принципе.
Нужен ли countryCode? Только для номеров без +. Номер 8 916 123-45-67 без указания страны разобрать не из чего — таких национальных форматов в мире десятки. Номер +79161234567 самодостаточен: код страны в нём уже есть.
Обязательна ли регистрация, чтобы попробовать? Нет. Демо-ключ публичный и работает без аккаунта — но возвращает моки, а не настоящий разбор.
Телефон редко проверяют в одиночку — обычно чистят всю карточку контакта разом. Тем же ключом и из того же аккаунта доступны:
- Проверка почты — синтаксис, MX-записи, одноразовые адреса
- Стандартизация адреса — разбор строки на компоненты и оценка качества
- ИИ-чат — модели, сессии, суммаризация текста
- Адреса ГАР/ФИАС — поиск и подсказки по официальному справочнику
- Распознавание текста с картинки — OCR по изображению или Base64
- Погодные данные — текущие условия по координатам
Полный каталог — atlorium.com
- Документация API (Swagger): atlorium.com/phoneAPI
- Описание сервиса: atlorium.com/phoneDescription
- Веб-интерфейс: atlorium.com/phoneGUI
- OpenAPI-спецификация: phone_ru.json
- Поддержка: support@atlorium.com
MIT — берите код и используйте как хотите, в том числе в коммерческих проектах.