Перейти к основному содержанию
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-адрес и связанные данные:

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

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

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

Ответ API возвращается в универсальном лёгком формате JSON.
ip_address
String
IP-адрес, переданный для геолокации.
city
String
Название города.
city_geoname_id
String
Geoname ID города.
region
String
Штат или провинция, в которой находится город.
region_iso_code
Char[2]
ISO 3166-2 код штата или провинции.
region_geoname_id
String
Geoname ID штата или провинции.
postal_code
String
Почтовый индекс.
country
String
Название страны.
country_code
Char[2]
ISO 3166-1 alpha-2 код страны.
country_geoname_id
String
Geoname ID страны.
country_is_eu
Boolean
true, если страна в ЕС, иначе false.
continent
String
Название континента.
continent_code
Char[2]
2-буквенный код континента: AF, AS, EU, NA, OC, SA, AN.
continent_geoname_id
String
Geoname ID континента.
longitude
Float
Долгота в десятичном формате.
latitude
Float
Широта в десятичном формате.
security.is_vpn
Boolean
true, когда IP совпадает с перечисленной базой VPN exit-node (IP-to-VPN MMDB).
security.is_proxy
Boolean
true, когда IP совпадает с базой прокси (IP-to-VPN MMDB).
security.vpn_provider
String
Название VPN-сервиса из MMDB (например, NordVPN). Опускается, когда is_vpn равен false.
timezone.name
String
Название часового пояса из базы IANA Time Zone Database.
timezone.abbreviation
String
Аббревиатура часового пояса из базы IANA Time Zone Database.
timezone.gmt_offset
String
Смещение часового пояса относительно GMT.
timezone.current_time
String
Текущее время в локальном часовом поясе.
timezone.is_dst
Boolean
true, если в данный момент действует летнее время (DST).
flag.svg
String
Ссылка на размещённый флаг страны в формате SVG.
flag.png
String
Ссылка на размещённый флаг страны в формате PNG.
flag.emoji
String
Флаг страны в виде эмодзи.
flag.unicode
String
Флаг страны в unicode.
currency.currency_name
String
Название валюты.
currency.currency_code
String
Код валюты в формате ISO 4217.
connection.connection_type
String
Выводится из названия организации ASN (например, Cellular, Cable/DSL, Corporate, Cloud, Hosting). VPN и прокси указываются в security, а не здесь.
connection.autonomous_system_number
Uint32
Номер автономной системы.
connection.autonomous_system_organization
String
Название организации автономной системы.
connection.isp_name
String
Название интернет-провайдера (ISP).
connection.organization_name
String
Название организации.

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

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

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

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

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

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

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

Коды стран

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

Прочее

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