> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cleariflow.com/llms.txt
> Use this file to discover all available pages before exploring further.

# IP 地理定位 API

> Cleariflow IP 地理定位 API 是一款快速、高效、现代化的 RESTful JSON API，可定位 190 多个国家 IP 地址的位置及其他详细信息。

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 地址及关联详情如下：

<ResponseExample>
  ```json theme={"system"}
  {
      "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
      }
  }
  ```
</ResponseExample>

### 请求参数

<ParamField query="api_key" type="String" required>
  您的唯一 API 密钥。请注意，每个用户为每个 Cleariflow API 拥有独立的 API 密钥，因此您的 IP 地理定位 API 密钥无法用于邮箱验证 API，例如。
</ParamField>

<ParamField query="ip_address" type="String">
  要定位的 IP 地址。支持 IPv4 和 IPv6 地址。请注意，若留空此参数，服务将定位发起请求的 IP 地址。
</ParamField>

<ParamField query="fields" type="String">
  要返回的**顶级**键的逗号分隔列表（例如 `?fields=country,security`）。要包含 VPN/代理标志，使用 `security`——将返回整个对象（`is_vpn`、`is_proxy` 以及存在时的 `vpn_provider`）。不支持单独使用 `is_vpn` 等嵌套键。
</ParamField>

### 响应参数

API 响应以通用、轻量的 [JSON 格式](https://www.json.org/json-en.html) 返回。

<ResponseField name="ip_address" type="String">
  提交进行地理定位的 IP 地址。
</ResponseField>

<ResponseField name="city" type="String">
  城市名称。
</ResponseField>

<ResponseField name="city_geoname_id" type="String">
  城市的 geoname ID。
</ResponseField>

<ResponseField name="region" type="String">
  城市所在的州或省。
</ResponseField>

<ResponseField name="region_iso_code" type="Char[2]">
  州或省的 ISO 3166-2 代码。
</ResponseField>

<ResponseField name="region_geoname_id" type="String">
  州或省的 geoname ID。
</ResponseField>

<ResponseField name="postal_code" type="String">
  邮政编码。
</ResponseField>

<ResponseField name="country" type="String">
  国家名称。
</ResponseField>

<ResponseField name="country_code" type="Char[2]">
  国家的 ISO 3166-1 alpha-2 代码。
</ResponseField>

<ResponseField name="country_geoname_id" type="String">
  国家的 geoname ID。
</ResponseField>

<ResponseField name="country_is_eu" type="Boolean">
  若国家在欧盟内则为 true，否则为 false。
</ResponseField>

<ResponseField name="continent" type="String">
  大洲名称。
</ResponseField>

<ResponseField name="continent_code" type="Char[2]">
  两字母大洲代码：AF、AS、EU、NA、OC、SA、AN。
</ResponseField>

<ResponseField name="continent_geoname_id" type="String">
  大洲的 geoname ID。
</ResponseField>

<ResponseField name="longitude" type="Float">
  经度的小数值。
</ResponseField>

<ResponseField name="latitude" type="Float">
  纬度的小数值。
</ResponseField>

<ResponseField name="security.is_vpn" type="Boolean">
  当 IP 匹配枚举的 VPN 出口节点数据库（IP-to-VPN MMDB）时为 `true`。
</ResponseField>

<ResponseField name="security.is_proxy" type="Boolean">
  当 IP 匹配代理数据库（IP-to-VPN MMDB）时为 `true`。
</ResponseField>

<ResponseField name="security.vpn_provider" type="String">
  MMDB 中的 VPN 服务名称（例如 `NordVPN`）。当 `is_vpn` 为 `false` 时省略。
</ResponseField>

<ResponseField name="timezone.name" type="String">
  IANA 时区数据库中的时区名称。
</ResponseField>

<ResponseField name="timezone.abbreviation" type="String">
  时区缩写，同样来自 IANA 时区数据库。
</ResponseField>

<ResponseField name="timezone.gmt_offset" type="String">
  时区相对于格林威治标准时间 (GMT) 的偏移。
</ResponseField>

<ResponseField name="timezone.current_time" type="String">
  本地时区的当前时间。
</ResponseField>

<ResponseField name="timezone.is_dst" type="Boolean">
  若该位置当前处于夏令时 (DST) 则为 true。
</ResponseField>

<ResponseField name="flag.svg" type="String">
  托管的国家 SVG 格式国旗链接。
</ResponseField>

<ResponseField name="flag.png" type="String">
  托管的国家 PNG 格式国旗链接。
</ResponseField>

<ResponseField name="flag.emoji" type="String">
  国家国旗的表情符号。
</ResponseField>

<ResponseField name="flag.unicode" type="String">
  国家国旗的 unicode 表示。
</ResponseField>

<ResponseField name="currency.currency_name" type="String">
  货币名称。
</ResponseField>

<ResponseField name="currency.currency_code" type="String">
  ISO 4217 格式的货币代码。
</ResponseField>

<ResponseField name="connection.connection_type" type="String">
  从 ASN 组织名称推断（例如 Cellular、Cable/DSL、Corporate、Cloud、Hosting）。VPN 和代理在 `security` 中报告，而非此处。
</ResponseField>

<ResponseField name="connection.autonomous_system_number" type="Uint32">
  自治系统编号。
</ResponseField>

<ResponseField name="connection.autonomous_system_organization" type="String">
  自治系统组织名称。
</ResponseField>

<ResponseField name="connection.isp_name" type="String">
  互联网服务提供商 (ISP) 名称。
</ResponseField>

<ResponseField name="connection.organization_name" type="String">
  组织名称。
</ResponseField>

### 限制响应字段

您可以选择仅接收 JSON 响应中的部分字段。为此，可在查询参数中包含 fields 值，列出要返回的顶级键的逗号分隔列表。

例如，仅获取 IP 的国家和城市的请求如下：

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

响应如下：

```json theme={"system"}
{
    "city": "Vienna",
    "country": "Austria"
}
```

## 使用场景

### 定位网站访客

要从 IP 地址请求地理定位，只需在下方模板中包含您的唯一 API 密钥。

请注意，发起请求时无需知道访客的 IP。

```javascript theme={"system"}
$.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](https://docs.google.com/spreadsheets/d/1w4VMneDoL6JW2NaUp2SjTOyvRcD4rlXDI0XpqKS2PeQ/view?usp=sharing) 中查看此列表。

| 国家名称       | 国家代码 |
| ---------- | ---- |
| 阿富汗        | 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"，仍会从您的账户扣除一次积分。