IP 地理定位 API - Cleariflow API

GET

IP 地理定位 API

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 架构

与所有 Cleariflow API 一样，IP 地理定位 API 遵循 REST 原则。它采用可预测的资源导向 URL，并使用 HTTP 状态码指示错误。

HTTPS 安全

与 IP 地理定位 API 的所有通信必须使用 TLS 1.2 或更高版本的协议进行保护。

API 版本控制

所有 Cleariflow API 均包含版本控制。IP 地理定位 API 当前运行在第 1 版。

使用 API 密钥进行身份验证

API 密钥是访问 Cleariflow IP 地理定位 API 的唯一身份验证凭证。请注意，每个 Cleariflow API 需要独立的 API 密钥，这意味着 IP 地理定位和邮箱验证等不同服务需要不同的密钥。要对请求进行身份验证，需将 API 密钥附加到基础 URL。

基础 URL

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

地理定位端点

Cleariflow IP 地理定位 API 只需您的唯一 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 密钥。请注意，每个用户为每个 Cleariflow API 拥有独立的 API 密钥，因此您的 IP 地理定位 API 密钥无法用于邮箱验证 API，例如。

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]

两字母大洲代码：AF、AS、EU、NA、OC、SA、AN。

continent_geoname_id

String

大洲的 geoname ID。

longitude

Float

经度的小数值。

latitude

Float

纬度的小数值。

security.is_vpn

Boolean

当 IP 匹配枚举的 VPN 出口节点数据库（IP-to-VPN MMDB）时为 true。

security.is_proxy

Boolean

当 IP 匹配代理数据库（IP-to-VPN MMDB）时为 true。

security.vpn_provider

String

MMDB 中的 VPN 服务名称（例如 NordVPN）。当 is_vpn 为 false 时省略。

timezone.name

String

IANA 时区数据库中的时区名称。

timezone.abbreviation

String

时区缩写，同样来自 IANA 时区数据库。

timezone.gmt_offset

String

时区相对于格林威治标准时间 (GMT) 的偏移。

timezone.current_time

String

本地时区的当前时间。

timezone.is_dst

Boolean

若该位置当前处于夏令时 (DST) 则为 true。

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 响应中的部分字段。为此，可在查询参数中包含 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”，仍会从您的账户扣除一次积分。

简介Cleariflow 汇率 API 通过简洁、现代化的 RESTful JSON 接口提供实时货币转换——支持 80 多种全球货币、实时汇率和即时换算。

IP 地理定位 API

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

地理定位端点

请求参数

响应参数

限制响应字段

使用场景

定位网站访客

响应和错误代码

国家代码

其他说明