Skip to main content
GET
API геолокации IP
API работает предельно просто: передайте API-ключ и IP-адрес — вы получите полные данные о местоположении: почтовые индексы, города, регионы, страны и точные координаты широты/долготы.

Начало работы

REST-архитектура

Как и все API Cleariflow, API геолокации IP следует принципам REST: предсказуемые URL, ориентированные на ресурсы, и HTTP-коды статуса для ошибок.

Безопасность HTTPS

Все соединения с API геолокации IP должны быть защищены TLS 1.2 или выше.

Версионирование API

Все API Cleariflow версионируются. API геолокации IP сейчас на версии 1.

Аутентификация с API-ключом

API-ключ — уникальные учётные данные для доступа к API геолокации IP Cleariflow. У каждого API Cleariflow свой ключ, поэтому для IP Geolocation и Email Validation нужны разные ключи. Для аутентификации добавьте ключ к базовому URL.

Базовый URL

Эндпоинт геолокации

API геолокации IP Cleariflow требует только ваш уникальный API-ключ и автоматически определяет IP-адрес клиента, с которого пришёл запрос. Альтернативно можно передать параметр «ip_address» для анализа конкретного IP:
Успешный запрос — ниже IP-адрес и связанные данные:

Параметры запроса

String
обязательно
Ваш уникальный API-ключ. У каждого пользователя уникальные ключи для каждого API Cleariflow, поэтому ключ IP Geolocation не будет работать, например, с API проверки email.
String
IP-адрес для геолокации. Поддерживаются IPv4 и IPv6. Если параметр не указан, сервис геолокализирует IP-адрес, с которого был сделан запрос.
String
Список верхнеуровневых ключей для возврата через запятую (например, ?fields=country,security). Для флагов VPN/прокси используйте security — возвращается весь объект (is_vpn, is_proxy и vpn_provider при наличии). Вложенные ключи вроде только is_vpn не поддерживаются.

Параметры ответа

Ответ API возвращается в универсальном лёгком формате JSON.
String
IP-адрес, переданный для геолокации.
String
Название города.
String
Geoname ID города.
String
Штат или провинция, в которой находится город.
Char[2]
ISO 3166-2 код штата или провинции.
String
Geoname ID штата или провинции.
String
Почтовый индекс.
String
Название страны.
Char[2]
ISO 3166-1 alpha-2 код страны.
String
Geoname ID страны.
Boolean
true, если страна в ЕС, иначе false.
String
Название континента.
Char[2]
2-буквенный код континента: AF, AS, EU, NA, OC, SA, AN.
String
Geoname ID континента.
Float
Долгота в десятичном формате.
Float
Широта в десятичном формате.
Boolean
true, когда IP совпадает с перечисленной базой VPN exit-node (IP-to-VPN MMDB).
Boolean
true, когда IP совпадает с базой прокси (IP-to-VPN MMDB).
String
Название VPN-сервиса из MMDB (например, NordVPN). Опускается, когда is_vpn равен false.
String
Название часового пояса из базы IANA Time Zone Database.
String
Аббревиатура часового пояса из базы IANA Time Zone Database.
String
Смещение часового пояса относительно GMT.
String
Текущее время в локальном часовом поясе.
Boolean
true, если в данный момент действует летнее время (DST).
String
Ссылка на размещённый флаг страны в формате SVG.
String
Ссылка на размещённый флаг страны в формате PNG.
String
Флаг страны в виде эмодзи.
String
Флаг страны в unicode.
String
Название валюты.
String
Код валюты в формате ISO 4217.
String
Выводится из названия организации ASN (например, Cellular, Cable/DSL, Corporate, Cloud, Hosting). VPN и прокси указываются в security, а не здесь.
Uint32
Номер автономной системы.
String
Название организации автономной системы.
String
Название интернет-провайдера (ISP).
String
Название организации.

Ограничение полей ответа

Можно получать только выбранные поля из JSON-ответа. Для этого передайте в query-параметрах fields со списком верхнеуровневых ключей через запятую. Например, запрос только страны и города IP выглядит так:
Ответ будет таким:

Сценарии использования

Геолокация посетителя сайта

Для запроса геолокации по IP-адресу включите ваш уникальный API-ключ в шаблон ниже. Обратите внимание: знать IP посетителя для запроса не обязательно.
Этого достаточно для получения геолокации и других данных о посетителе! Единственный обязательный параметр — ваш уникальный API-ключ.

Коды ответов и ошибок

При неудачном запросе ошибка также возвращается в JSON с кодом и описанием — подробности ниже.

Коды стран

Ниже список двухбуквенных ISO 3166 Alpha 2 кодов стран, используемых в ответе. Список в CSV.

Прочее

Важная информация по биллингу: каждый обработанный IP-адрес расходует один кредит. Списание происходит за запрос, независимо от успеха ответа. Поэтому даже передача невалидного IP вроде «fda3346ds» спишет один кредит с аккаунта.