Перейти до основного вмісту
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 і перевірка email, потрібні різні ключі. Для автентифікації запитів додайте API-ключ до базового URL.

Базовий URL

Ендпоінт геолокації

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

Параметри запиту

api_key
String
обов'язково
Ваш унікальний API-ключ. Зверніть увагу: у кожного користувача є унікальні API-ключі для кожного API Cleariflow, тому ключ IP Geolocation не працюватиме для Email Validation API, наприклад.
ip_address
String
IP-адреса для геолокації. Підтримуються адреси IPv4 і IPv6. Якщо параметр не вказано, сервіс геолокує IP-адресу, з якої надійшов запит.
fields
String
Список верхньорівневих ключів через кому (наприклад, ?fields=country,security). Для VPN/proxy використовуйте 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
ZIP або поштовий індекс.
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]
Дволітерний код континенту: 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 відповідає базі proxy (IP-to-VPN MMDB).
security.vpn_provider
String
Назва VPN-сервісу з MMDB (наприклад, NordVPN). Пропускається, коли is_vpnfalse.
timezone.name
String
Назва часового поясу з IANA Time Zone Database.
timezone.abbreviation
String
Абревіатура часового поясу з IANA Time Zone Database.
timezone.gmt_offset
String
Зміщення часового поясу від Greenwich Mean Time (GMT).
timezone.current_time
String
Поточний час у локальному часовому поясі.
timezone.is_dst
Boolean
true, якщо локація наразі в літньому часі (DST).
flag.svg
String
Посилання на розміщений прапор країни у форматі SVG.
flag.png
String
Посилання на розміщений прапор країни у форматі PNG.
flag.emoji
String
Прапор країни у вигляді emoji.
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 і proxy повідомляються в security, а не тут.
connection.autonomous_system_number
Uint32
Номер автономної системи.
connection.autonomous_system_organization
String
Назва організації автономної системи.
connection.isp_name
String
Назва інтернет-провайдера (ISP).
connection.organization_name
String
Назва організації.

Обмеження полів відповіді

Можна отримати лише кілька полів з JSON-відповіді. Для цього передайте параметр fields зі списком верхньорівневих ключів через кому. Наприклад, запит лише на країну та місто IP виглядатиме так:
Відповідь виглядатиме так:

Сценарії використання

Геолокація відвідувача сайту

Щоб отримати геолокацію за IP-адресою, просто передайте унікальний API-ключ у шаблоні нижче. Зверніть увагу: для запиту не потрібно знати IP відвідувача.
Цього достатньо, щоб отримати геолокацію та інші дані відвідувача! Єдиний обов’язковий параметр — ваш унікальний API-ключ.

Коди відповідей і помилок

Якщо запит не вдається, помилка також повертається у форматі JSON з кодом і описом, детально наведеними нижче.

Коди країн

Нижче наведено список дволітерних ISO 3166 Alpha 2 кодів країн, що використовуються у відповіді. Переглянути список у CSV.

Інші примітки

Важлива інформація про тарифікацію: кожна оброблена IP-адреса списує один кредит. Тарифікація відбувається за запит, незалежно від успішності відповіді. Тому навіть передача недійсної IP-адреси на кшталт «fda3346ds» все одно списує один кредит.