API геолокації IP

GET

API геолокації IP

curl --request GET \
  --url https://ipgeolocation.cleariflow.com/v1

{
    "ip_address": "80.255.13.30",
    "city": null,
    "city_geoname_id": null,
    "region": null,
    "region_iso_code": null,
    "region_geoname_id": null,
    "postal_code": null,
    "country": "Germany",
    "country_code": "DE",
    "country_geoname_id": 2921044,
    "country_is_eu": true,
    "continent": "Europe",
    "continent_code": "EU",
    "continent_geoname_id": 6255148,
    "longitude": 9.491,
    "latitude": 51.2993,
    "security": {
        "is_vpn": true,
        "is_proxy": false,
        "vpn_provider": "NordVPN"
    },
    "timezone": {
        "name": "Europe/Berlin",
        "abbreviation": "CEST",
        "gmt_offset": 2,
        "current_time": "21:21:22",
        "is_dst": true
    },
    "flag": {
        "emoji": "🇩🇪",
        "unicode": "U+1F1E9 U+1F1EA",
        "png": "https://static.cleariflow.com/country-flags/DE_flag.png",
        "svg": "https://static.cleariflow.com/country-flags/DE_flag.svg"
    },
    "currency": {
        "currency_name": "Euros",
        "currency_code": "EUR"
    },
    "connection": {
        "autonomous_system_number": 201011,
        "autonomous_system_organization": "Core-Backbone GmbH",
        "connection_type": null,
        "isp_name": null,
        "organization_name": null
    }
}

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

https://ipgeolocation.cleariflow.com/v1/

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

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

https://ipgeolocation.cleariflow.com/v1/
? api_key = YOUR_UNIQUE_API_KEY
& ip_address = 94.198.41.118 (optional)

Це успішний запит — нижче повертаються IP-адреса та пов’язані дані:

{
    "ip_address": "80.255.13.30",
    "city": null,
    "city_geoname_id": null,
    "region": null,
    "region_iso_code": null,
    "region_geoname_id": null,
    "postal_code": null,
    "country": "Germany",
    "country_code": "DE",
    "country_geoname_id": 2921044,
    "country_is_eu": true,
    "continent": "Europe",
    "continent_code": "EU",
    "continent_geoname_id": 6255148,
    "longitude": 9.491,
    "latitude": 51.2993,
    "security": {
        "is_vpn": true,
        "is_proxy": false,
        "vpn_provider": "NordVPN"
    },
    "timezone": {
        "name": "Europe/Berlin",
        "abbreviation": "CEST",
        "gmt_offset": 2,
        "current_time": "21:21:22",
        "is_dst": true
    },
    "flag": {
        "emoji": "🇩🇪",
        "unicode": "U+1F1E9 U+1F1EA",
        "png": "https://static.cleariflow.com/country-flags/DE_flag.png",
        "svg": "https://static.cleariflow.com/country-flags/DE_flag.svg"
    },
    "currency": {
        "currency_name": "Euros",
        "currency_code": "EUR"
    },
    "connection": {
        "autonomous_system_number": 201011,
        "autonomous_system_organization": "Core-Backbone GmbH",
        "connection_type": null,
        "isp_name": null,
        "organization_name": null
    }
}

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

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_vpn — false.

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 виглядатиме так:

https://ipgeolocation.cleariflow.com/v1/
    ? api_key = YOUR_API_KEY
    & ip_address = 94.198.41.122
    & fields = country,city

Відповідь виглядатиме так:

{
    "city": "Vienna",
    "country": "Austria"
}

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

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

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

$.getJSON("https://ipgeolocation.cleariflow.com/v1/?api_key=YOUR_UNIQUE_API_KEY", function(data) {
   console.log(data.ip_address);
   console.log(data.country);
})

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

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

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

Code	Type	Details
200	OK	Усе працювало як очікувалося.
204	OK	Немає даних про місцезнаходження для переданої IP-адреси.
400	Bad request	Некоректний запит.
401	Unauthorized	Запит неприйнятний. Зазвичай через відсутній або неправильний API-ключ.
422	Quota reached	Запит перервано через недостатню кількість API-кредитів. (Безкоштовні тарифи)
429	Too many requests	Запит перервано через досягнення ліміту запитів на секунду. На безкоштовних тарифах — 1 запит/сек.
500	Internal server error	Запит не може бути виконаний через помилку на сервері.
503	Service unavailable	Сервер був недоступний.

Коди країн

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

Назва країни	Код країни
Afghanistan	AF
Albania	AL
Algeria	DZ
American Samoa	AS
Andorra	AD
Angola	AO
Anguilla	AI
Antigua and Barbuda	AG
Argentina	AR
Armenia	AM
Aruba	AW
Australia	AU
Austria	AT
Azerbaijan	AZ
Bahrain	BH
Bangladesh	BD
Barbados	BB
Belarus	BY
Belgium	BE
Belize	BZ
Benin	BJ
Bermuda	BM
Bhutan	BT
Bolivia	BO
Bosnia and Herzegovina	BA
Botswana	BW
Brazil	BR
British Virgin Islands	VG
Brunei	BN
Bulgaria	BG
Burkina Faso	BF
Burundi	BI
Cabo Verde	CV
Cambodia	KH
Cameroon	CM
Canada	CA
Cayman Islands	KY
Central African Republic	CF
Chad	TD
Chile	CL
China	CN
Colombia	CO
Comoros	KM
Congo	CG
Congo Democratic Republic	CD
Cook Islands	CK
Costa Rica	CR
Cote d’Ivoire	CI
Croatia	HR
Cuba	CU
Curaçao	CW
Cyprus	CY
Czechia	CZ
Denmark	DK
Djibouti	DJ
Dominica	DM
Dominican Republic	DO
East Timor	TL
Ecuador	EC
Egypt	EG
El Salvador	SV
Equatorial Guinea	GQ
Eritrea	ER
Estonia	EE
eSwatini	SZ
Ethiopia	ET
Falkland Islands	FK
Faroe Islands	FO
Fiji	FJ
Finland	FI
France	FR
French Guiana	GF
French Polynesia	PF
Gabon	GA
Gambia	GM
Georgia	GE
Germany	DE
Ghana	GH
Gibraltar	GI
Greece	GR
Greenland	GL
Grenada	GD
Guadeloupe	GP
Guam	GU
Guatemala	GT
Guernsey	GG
Guinea	GN
Guinea-Bissau	GW
Guyana	GY
Haiti	HT
Honduras	HN
Hong Kong	HK
Hungary	HU
Iceland	IS
India	IN
Indonesia	ID
Iran	IR
Iraq	IQ
Ireland	IE
Isle of Man	IM
Israel	IL
Italy	IT
Jamaica	JM
Japan	JP
Jersey	JE
Jordan	JO
Kazakhstan	KZ
Kenya	KE
Kiribati	KI
Kosovo	XK
Kuwait	KW
Kyrgyzstan	KG
Laos	LA
Latvia	LV
Lebanon	LB
Lesotho	LS
Liberia	LR
Libya	LY
Liechtenstein	LI
Lithuania	LT
Luxembourg	LU
Macau	MO
Madagascar	MG
Malawi	MW
Malaysia	MY
Maldives	MV
Mali	ML
Malta	MT
Marshall Islands	MH
Martinique	MQ
Mauritania	MR
Mauritius	MU
Mayotte	YT
Mexico	MX
Micronesia	FM
Moldova	MD
Monaco	MC
Mongolia	MN
Montenegro	ME
Montserrat	MS
Morocco	MA
Mozambique	MZ
Myanmar	MM
Namibia	NA
Nauru	NR
Nepal	NP
Netherlands	NL
New Caledonia	NC
New Zealand	NZ
Nicaragua	NI
Niger	NE
Nigeria	NG
North Korea	KP
North Macedonia	MK
Northern Mariana Islands	MP
Norway	NO
Oman	OM
Pakistan	PK
Palau	PW
Panama	PA
Papua New Guinea	PG
Paraguay	PY
Peru	PE
Philippines	PH
Poland	PL
Portugal	PT
Puerto Rico	PR
Qatar	QA
Reunion	RE
Romania	RO
Russia	RU
Rwanda	RW
Saint Helena	SH
Saint Kitts and Nevis	KN
Saint Lucia	LC
Saint Martin	MF
Saint Pierre and Miquelon	PM
Saint Vincent and the Grenadines	VC
Samoa	WS
San Marino	SM
Sao Tome and Principe	ST
Saudi Arabia	SA
Senegal	SN
Serbia	RS
Seychelles	SC
Sierra Leone	SL
Singapore	SG
Sint Maarten	SX
Slovakia	SK
Slovenia	SI
Solomon Islands	SB
Somalia	SO
South Africa	ZA
South Korea	KR
South Sudan	SS
Spain	ES
Sri Lanka	LK
St. Barts	BL
Sudan	SD
Suriname	SR
Sweden	SE
Switzerland	CH
Syria	SY
Taiwan	TW
Tajikistan	TJ
Tanzania	TZ
Thailand	TH
The Bahamas	BS
Togo	TG
Tonga	TO
Trinidad and Tobago	TT
Tunisia	TN
Turkey	TR
Turkmenistan	TM
Turks and Caicos Islands	TC
Tuvalu	TV
Uganda	UG
Ukraine	UA
United Arab Emirates	AE
United Kingdom	GB
United States	US
Uruguay	UY
US Virgin Islands	VI
Uzbekistan	UZ
Vanuatu	VU
Vatican City (Holy See)	VA
Venezuela	VE
Vietnam	VN
Wallis and Futuna	WF
Yemen	YE
Zambia	ZM
Zimbabwe	ZW

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

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

Попередня

ВступAPI обмінних курсів Cleariflow надає конвертацію валют у реальному часі через сучасний RESTful JSON-інтерфейс — з підтримкою понад 80 світових валют, актуальних курсів і миттєвої конвертації.

Наступна

API геолокації IP

curl --request GET \
  --url https://ipgeolocation.cleariflow.com/v1

{
    "ip_address": "80.255.13.30",
    "city": null,
    "city_geoname_id": null,
    "region": null,
    "region_iso_code": null,
    "region_geoname_id": null,
    "postal_code": null,
    "country": "Germany",
    "country_code": "DE",
    "country_geoname_id": 2921044,
    "country_is_eu": true,
    "continent": "Europe",
    "continent_code": "EU",
    "continent_geoname_id": 6255148,
    "longitude": 9.491,
    "latitude": 51.2993,
    "security": {
        "is_vpn": true,
        "is_proxy": false,
        "vpn_provider": "NordVPN"
    },
    "timezone": {
        "name": "Europe/Berlin",
        "abbreviation": "CEST",
        "gmt_offset": 2,
        "current_time": "21:21:22",
        "is_dst": true
    },
    "flag": {
        "emoji": "🇩🇪",
        "unicode": "U+1F1E9 U+1F1EA",
        "png": "https://static.cleariflow.com/country-flags/DE_flag.png",
        "svg": "https://static.cleariflow.com/country-flags/DE_flag.svg"
    },
    "currency": {
        "currency_name": "Euros",
        "currency_code": "EUR"
    },
    "connection": {
        "autonomous_system_number": 201011,
        "autonomous_system_organization": "Core-Backbone GmbH",
        "connection_type": null,
        "isp_name": null,
        "organization_name": null
    }
}

​Початок роботи

​REST-архітектура

​Безпека HTTPS

​Версіонування API

​Автентифікація за API-ключем

​Базовий URL

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

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

​Параметри відповіді

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

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

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

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

​Коди країн

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

Початок роботи

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

Безпека HTTPS

Версіонування API

Автентифікація за API-ключем

Базовий URL

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

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

Параметри відповіді

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

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

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

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

Коди країн

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