Русский · English
Готовые примеры работы с API «Профиль IP» на шести языках: Python, TypeScript (Node.js), Go, Java, C#, PHP. Определить страну и город по IP, получить координаты и часовой пояс, узнать владельца сети (ASN), а в расширенном режиме — обнаружить VPN, прокси, Tor и резидентный прокси и проверить репутацию адреса.
Каждый пример запускается сразу — без регистрации, без ключа, без карты. В коде зашит публичный демо-ключ.
git clone https://github.com/atlorium-api/ip-geolocation-api-client
cd ip-geolocation-api-client/python && pip install -r requirements.txt && python main.py8.8.8.8
Местоположение: Челябинск, Курганская область, SG
Координаты: 4.58673, -87.687 (±104 км)
Часовой пояс: Europe/Berlin
Hostname: ксения.макар.info
Сеть: AS20751 Баранов Сбыт · 32.114.83.0/24 · тип isp
Риск-флагов не обнаружено.
[i] Часовой пояс: Europe/Berlin — локализуйте время и окно уведомлений
[i] Страна: SG — язык, валюта и ближайший регион обслуживания
[i] Координаты приблизительные: радиус ±104 км — не опирайтесь на город
[i] Контакт для жалоб: abuse@макар.info
Уровень профиля: Extended.
Демо-ключ отвечает правдоподобными моками, а не реальными геоданными — поэтому в примере выше у 8.8.8.8 оказался «Челябинск» и вымышленный провайдер. Так и задумано: интеграцию можно написать и протестировать до оплаты. Подставьте боевой ключ — тот же код начнёт возвращать настоящие данные.
Антифрод и оценка риска платежа, гео-роутинг (отдать ближайший регион обслуживания, подставить язык и валюту), локализация времени и рассылок, блокировка ботов и скриптов, гео-ограничения контента, обогащение логов и аналитики.
Примеры не просто печатают JSON, а применяют данные: в каждом есть функция assessVisitorRisk(), которая по профилю IP выносит вердикт — не скрывает ли посетитель настоящее местоположение (VPN, прокси, Tor, relay), не сидит ли он на резидентном прокси (такие сети покупают ровно ради обхода антифрода), не отмечен ли адрес в базах жалоб и не датацентр ли это вместо домашнего провайдера (тогда за адресом скорее бот, чем человек). Заодно оттуда же берутся часовой пояс и страна — для локализации и выбора региона обслуживания.
Проверить API вообще без клонирования:
curl -H "Authorization: Bearer ak_sandbox_demo_mockdata_v1" \
"https://atlorium.com/api/ipinfo/8.8.8.8?extended=true"| Язык | Запуск | Требуется |
|---|---|---|
| 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+ |
Передать свой IP аргументом: python main.py 1.1.1.1
Ключ передаётся в заголовке Authorization:
Authorization: Bearer ВАШ_КЛЮЧ
| Ключ | Что делает |
|---|---|
ak_sandbox_demo_mockdata_v1 |
Демо-ключ. Публичный, один на всех. Возвращает моки, денег не списывает, регистрации не требует. Ответы детерминированы — на них можно писать стабильные тесты. |
| Боевой ключ | Реальные геоданные. Получить в личном кабинете: atlorium.com |
Переход на боевой ключ не требует правок в коде — все примеры читают переменную окружения:
export ATLORIUM_API_KEY="ak_ваш_боевой_ключ"Каждый ответ песочницы помечен заголовком X-Atlorium-Sandbox: true — перепутать мок с реальными данными невозможно.
Базовый адрес: https://atlorium.com
| Метод | Путь | Назначение |
|---|---|---|
GET |
/api/ipinfo/{ip} |
Профиль IP-адреса: геолокация, а при extended=true — ASN, признаки анонимизации и репутация |
| Параметр | Где | Тип | Описание |
|---|---|---|---|
ip |
путь | string | IPv4 или IPv6. Например, 8.8.8.8 или 2606:4700:4700::1111. Приватные и зарезервированные диапазоны отклоняются с 400 |
extended |
query | bool | Расширенный профиль: владелец сети (ASN/организация), hostname, признаки анонимизации (VPN, прокси, Tor, relay, резидентный прокси), контакт для жалоб, отметка о репутации. По умолчанию false. Тарифицируется отдельно и отвечает медленнее |
| Поле | Тип | Что содержит |
|---|---|---|
ip |
string | Адрес, по которому построен профиль |
tier |
string | Basic — только геолокация; Extended — полный профиль |
isBogon |
bool | Признак риска. Адрес не маршрутизируется в публичном интернете (подделанный или внутренний) |
hostname |
string | Обратная DNS-запись адреса (при extended=true) |
geo |
object | Геолокация — см. таблицу ниже |
asn |
object | Владелец сети (при extended=true): { asn, name, domain, route, type, rpkiValid }. type — isp, hosting, business, education, government |
company |
object | Организация, за которой закреплён адрес: { name, domain, route, type } |
flags |
object | Характеристики сети: { isAnonymous, isAnycast, isHosting, isMobile, isSatellite } |
carrier |
object | Мобильный оператор для адресов сотовых сетей: { name, mcc, mnc } |
privacy |
object | Признаки анонимизации — см. таблицу ниже |
abuse |
object | Контакт для жалоб: { name, email, phone, address, country, network } |
hostedDomains |
object | Сколько доменов размещено на адресе: { total } |
abuseReports |
object | Репутация адреса: { flagged, detailsUrl } — фигурирует ли IP в базах жалоб |
| Поле | Тип | Что содержит |
|---|---|---|
city / region / regionCode |
string | Город и регион |
country / countryCode |
string | Страна и её код по ISO 3166-1 alpha-2 |
continent / continentCode |
string | Континент |
latitude / longitude |
number | Координаты — центр области, а не точка нахождения устройства |
accuracyRadiusKm |
int | Радиус, в пределах которого координаты можно считать верными |
postal |
string | Почтовый индекс |
timezone |
string | Часовой пояс в формате IANA, например Europe/Moscow |
dmaCode / geonameId |
string | Коды справочников GeoNames и DMA |
| Поле | Тип | Что содержит |
|---|---|---|
isVpn |
bool | Адрес принадлежит VPN-сервису |
isProxy |
bool | Открытый или коммерческий прокси |
isTor |
bool | Выходной узел сети Tor |
isRelay |
bool | Приватный relay (iCloud Private Relay и подобные) |
isHosting |
bool | Датацентр, а не домашний провайдер |
isResidentialProxy |
bool | Самый весомый флаг фрода. Чужой домашний IP, перепроданный как «чистый» |
serviceName |
string | Имя сервиса-анонимайзера, если он опознан |
lastSeen / percentDaysSeen |
string / int | Когда и как часто адрес наблюдался в этой роли |
| Код | Причина | Что делать |
|---|---|---|
400 |
Неверный IP-адрес | Проверьте формат. Приватные (192.168.0.0/16, 10.0.0.0/8) и зарезервированные диапазоны не принимаются |
401 |
Ключ отсутствует, просрочен или недействителен | Проверьте заголовок Authorization |
402 |
Недостаточно кредитов на балансе | Пополнить на atlorium.com |
429 |
Превышен rate-limit | Повторить с задержкой |
503 |
Источник геоданных временно недоступен | Повторить позже. За сбой на нашей стороне деньги не списываются |
Во всех шести примерах коды разложены в человекочитаемые причины — смотрите класс AtloriumError.
Оплата pay-as-you-go, без подписки: платите только за выполненные запросы. Расширенный профиль (extended=true) тарифицируется отдельно от базового.
Актуальные цены и лимиты: atlorium.com/pricing
Насколько точна геолокация по IP? Это оценка, а не координаты устройства. Ответ честно отдаёт accuracyRadiusKm — радиус достоверности; в примере выше он равен 104 км, и опираться на «город» в таком случае нельзя. Страна определяется надёжно почти всегда, регион — обычно, конкретный город — далеко не всегда. Для экстренных служб и юридически значимых решений IP-геолокация не годится.
Детект VPN и прокси работает на 100 %? Нет, и никто такого не даёт. Новые VPN-сети и свежие прокси попадают в базы с задержкой, а isVpn = true сам по себе не означает мошенника: люди пользуются VPN и по совершенно законным причинам. Правильное применение — не блокировка по одному флагу, а повышение веса риска в общем скоринге, как в assessVisitorRisk().
Чем это отличается от бесплатных сервисов вроде «узнать свой IP»? Бесплатные обычно дают только страну и город. Здесь в одном ответе — геолокация, владелец сети (ASN и его тип), обратная DNS-запись, признаки анонимизации, контакт для жалоб и отметка о репутации, то есть ровно то, из чего собирается антифрод-правило.
Обязательна ли регистрация, чтобы попробовать? Нет. Демо-ключ публичный и работает без аккаунта — но возвращает моки, а не реальные данные.
Что даёт extended=true? Всё, кроме базовой геолокации: asn, company, hostname, flags, privacy, abuse, abuseReports. Без него оценивать риск нечем — поэтому во всех шести примерах assessVisitorRisk() вызывается именно с расширенным профилем. Тарифицируется отдельно.
Поддерживается ли IPv6? Да, эндпоинт принимает и IPv4, и IPv6 — например, 2606:4700:4700::1111.
Можно ли отдать в API адрес из X-Forwarded-For? Да, но проверяйте флаг isBogon: если клиент подставил в заголовок приватный или зарезервированный адрес, профиль это покажет.
Оценка риска редко упирается в один IP. Из того же аккаунта и тем же ключом доступны:
- CIDR-калькулятор — разбиение сети на подсети и проверка вхождения IP
- AML-скоринг криптокошелька — риск-балл, санкции, PEP
- DNS Lookup — записи домена, MX, SPF, DMARC
- Проверка BIN карты — банк-эмитент, страна и тип карты для антифрода на чекауте
- Проверка SSL-сертификата — срок действия, SAN, цепочка доверия
- SWIFT/BIC — разбор кода по ISO-9362 и сверка перед международным переводом
Полный каталог — atlorium.com
- Документация API (Swagger): atlorium.com/ipinfoAPI
- Описание сервиса: atlorium.com/ipinfoDescription
- Веб-интерфейс: atlorium.com/ipinfoGUI
- OpenAPI-спецификация: ipinfo_ru.json
- Поддержка: support@atlorium.com
MIT — берите код и используйте как хотите, в том числе в коммерческих проектах.