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 Geolocation и Email Validation нужны разные ключи. Для аутентификации добавьте ключ к базовому 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 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 выглядит так:

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.

Название страны	Код страны
Афганистан	AF
Албания	AL
Алжир	DZ
Американское Самоа	AS
Андорра	AD
Ангола	AO
Ангилья	AI
Антигуа и Барбуда	AG
Аргентина	AR
Армения	AM
Аруба	AW
Австралия	AU
Австрия	AT
Азербайджан	AZ
Бахрейн	BH
Бангладеш	BD
Барбадос	BB
Беларусь	BY
Бельгия	BE
Белиз	BZ
Бенин	BJ
Бермуды	BM
Бутан	BT
Боливия	BO
Босния и Герцеговина	BA
Ботсвана	BW
Бразилия	BR
Британские Виргинские острова	VG
Бруней	BN
Болгария	BG
Буркина-Фасо	BF
Бурунди	BI
Кабо-Верде	CV
Камбоджа	KH
Камерун	CM
Канада	CA
Каймановы острова	KY
ЦАР	CF
Чад	TD
Чили	CL
Китай	CN
Колумбия	CO
Коморы	KM
Конго	CG
ДР Конго	CD
Острова Кука	CK
Коста-Рика	CR
Кот-д’Ивуар	CI
Хорватия	HR
Куба	CU
Кюрасао	CW
Кипр	CY
Чехия	CZ
Дания	DK
Джибути	DJ
Доминика	DM
Доминиканская Республика	DO
Восточный Тимор	TL
Эквадор	EC
Египет	EG
Сальвадор	SV
Экваториальная Гвинея	GQ
Эритрея	ER
Эстония	EE
Эсватини	SZ
Эфиопия	ET
Фолклендские острова	FK
Фарерские острова	FO
Фиджи	FJ
Финляндия	FI
Франция	FR
Французская Гвиана	GF
Французская Полинезия	PF
Габон	GA
Гамбия	GM
Грузия	GE
Германия	DE
Гана	GH
Гибралтар	GI
Греция	GR
Гренландия	GL
Гренада	GD
Гваделупа	GP
Гуам	GU
Гватемала	GT
Гернси	GG
Гвинея	GN
Гвинея-Бисау	GW
Гайана	GY
Гаити	HT
Гондурас	HN
Гонконг	HK
Венгрия	HU
Исландия	IS
Индия	IN
Индонезия	ID
Иран	IR
Ирак	IQ
Ирландия	IE
Остров Мэн	IM
Израиль	IL
Италия	IT
Ямайка	JM
Япония	JP
Джерси	JE
Иордания	JO
Казахстан	KZ
Кения	KE
Кирибати	KI
Косово	XK
Кувейт	KW
Кыргызстан	KG
Лаос	LA
Латвия	LV
Ливан	LB
Лесото	LS
Либерия	LR
Ливия	LY
Лихтенштейн	LI
Литва	LT
Люксембург	LU
Макао	MO
Мадагаскар	MG
Малави	MW
Малайзия	MY
Мальдивы	MV
Мали	ML
Мальта	MT
Маршалловы острова	MH
Мартиника	MQ
Мавритания	MR
Маврикий	MU
Майотта	YT
Мексика	MX
Микронезия	FM
Молдова	MD
Монако	MC
Монголия	MN
Черногория	ME
Монтсеррат	MS
Марокко	MA
Мозамбик	MZ
Мьянма	MM
Намибия	NA
Науру	NR
Непал	NP
Нидерланды	NL
Новая Каледония	NC
Новая Зеландия	NZ
Никарагуа	NI
Нигер	NE
Нигерия	NG
КНДР	KP
Северная Македония	MK
Северные Марианские острова	MP
Норвегия	NO
Оман	OM
Пакистан	PK
Палау	PW
Панама	PA
Папуа — Новая Гвинея	PG
Парагвай	PY
Перу	PE
Филиппины	PH
Польша	PL
Португалия	PT
Пуэрто-Рико	PR
Катар	QA
Реюньон	RE
Румыния	RO
Россия	RU
Руанда	RW
Остров Святой Елены	SH
Сент-Китс и Невис	KN
Сент-Люсия	LC
Сен-Мартен	MF
Сен-Пьер и Микелон	PM
Сент-Винсент и Гренадины	VC
Самоа	WS
Сан-Марино	SM
Сан-Томе и Принсипи	ST
Саудовская Аравия	SA
Сенегал	SN
Сербия	RS
Сейшелы	SC
Сьерра-Леоне	SL
Сингапур	SG
Синт-Мартен	SX
Словакия	SK
Словения	SI
Соломоновы острова	SB
Сомали	SO
ЮАР	ZA
Южная Корея	KR
Южный Судан	SS
Испания	ES
Шри-Ланка	LK
Сен-Бартелеми	BL
Судан	SD
Суринам	SR
Швеция	SE
Швейцария	CH
Сирия	SY
Тайвань	TW
Таджикистан	TJ
Танзания	TZ
Таиланд	TH
Багамы	BS
Того	TG
Тонга	TO
Тринидад и Тобаго	TT
Тунис	TN
Турция	TR
Туркменистан	TM
Тёркс и Кайкос	TC
Тувалу	TV
Уганда	UG
Украина	UA
ОАЭ	AE
Великобритания	GB
США	US
Уругвай	UY
Виргинские острова США	VI
Узбекистан	UZ
Вануату	VU
Ватикан	VA
Венесуэла	VE
Вьетнам	VN
Уоллис и Футуна	WF
Йемен	YE
Замбия	ZM
Зимбабве	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

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

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

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

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

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

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

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

Коды стран

Прочее