API 接口文档

一. 文档说明#

本页是 IP99 IP 风险画像接口的完整参考。全部接口都是 HTTP GET，请求与响应都是 UTF-8 JSON，响应里的地名、网络类型、风险类型一律用标准码或固定英文标识，不含中文，可以直接入库统计。

二. 两个接口怎么选#

Pulse 专业版接口是基础版接口的升级版，不是另一套接口。两者用同一份数据、同一套判定，同一个地址的分数同源同值：要「这个 IP 现在有多危险」，两个都够；要「当时为什么这么判」，只有 Pulse 答得出。

2.1 一句话选型#

2.2 两个接口的差异#

2.3 谁能调用#

Pulse 是专业版能力。基础版 /v1/ip 对所有人开放，连 Key 都不用；Pulse 只对专业版开放。

版本不够时会明确报错，不会悄悄少给字段：调 Pulse 返回 403 professional_required；用 ?at= 返回 403 history_requires_professional。

证据行上的可选字段看档位

三. 认证、额度与请求约束#

3.1 认证#

把 Key 放在请求头里，两种写法等价：X-API-Key: 你的KEY 或 Authorization: Bearer 你的KEY。

curl -H "X-API-Key: 你的KEY" \
  https://ip99.com/v1/ip/8.8.8.8

注：带不带 Key，返回的字段完全一样，区别只在额度。

3.2 额度与响应头#

额度按自然日执行，北京时间 00:00 重置。网页查询与 API 共用同一份每日额度：未登录时按访问来源的 IP 计，登录后按账户计。额度信息随响应头返回，不需要另外查询；当前版本与剩余额度也可以用 GET /v1/me 查。

注：上表是默认值，实际以响应头 X-RateLimit-Limit（每分钟上限）、X-Daily-Limit（每日额度）、X-Daily-Remaining（今日剩余）为准。

注：带 Key 调用的额度按账户与合同执行，请以响应头 X-Daily-Limit / X-RateLimit-Limit 为准，或用 GET /v1/me 查询。

3.3 版本、档位与套餐#

注：档位与套餐互不代管——升级套餐不等于拿到专业档字段，开通专业档也不等于历史回溯可用。需要更高用量或专业能力，见页脚联系方式。

四. 基础版接口#

4.1 请求说明#

注：每分钟上限未登录时与带 Key 时不同（见 3.2 额度与响应头）。

4.2 请求示例#

不需要注册，也不需要先申请 Key，直接调用即可：

curl https://ip99.com/v1/ip/8.8.8.8

curl -H "X-API-Key: 你的KEY" \
  https://ip99.com/v1/ip/8.8.8.8

4.3 请求参数说明#

4.4 返回示例#

一次真实调用的返回：86.111.136.23，此刻判为高风险的代理出口。字段名与取值和线上一致，键序按阅读顺序整理过；JSON 对象本身是无序的，请按字段名取值。两个接口的 risk 是同一形态：都由同一段代码出，只有 score、level、signals 三个键，一套解析逻辑就够。

{
  "ip": "86.111.136.23",
  "computed_at": "2026-09-17T08:47:02Z",
  "evidence_state": "active",
  "risk": {
    "score": 86,
    "level": "high",
    "signals": ["proxy"]
  },
  "network": { "asn": 15547, "usage_type": "DYN" },
  "geo": {
    "continent": "EU", "country": "CH",
    "region": "Valais", "city": "Sitten",
    "lat": 46.22739, "lon": 7.35559,
    "tz": "Europe/Zurich"
  }
}

注：risk.signals 里出现的 slug 见 八. 风险信号说明，取值对照见 九. 风险标签说明。

4.5 返回内容字段说明#

下表是基础版返回的全部字段。risk.signals、network、geo、degraded 四块是「有才出」的：risk.signals 一个信号都没命中时这个键不出现（此时 risk 只剩 score 与 level）；其余三块没出现就是没有这项数据。

五. Pulse 专业版接口#

5.1 请求说明#

注：每分钟上限按 Key 生效，不同 Key 可以不同；以响应头 X-RateLimit-Limit 为准。

5.2 请求示例#

curl -H "X-API-Key: 你的KEY" \
  "https://ip99.com/pulse/v1/ip/86.111.136.23"

curl -H "X-API-Key: 你的KEY" \
  "https://ip99.com/pulse/v1/ip/86.111.136.23?at=2026-09-14T09:29:23Z"

5.3 请求参数说明#

注：带时区偏移的写法要把 + 转义成 %2B——URL 里裸写 + 等于空格，服务端按格式错退回 invalid_time。时刻写错、写在未来，返回 400 invalid_time；超出可回溯窗口返回 400 at_out_of_window，响应里带 window_from，告诉你最早能问到哪一刻，不必一次次试探。

5.4 返回示例#

不带 at：此刻#

86.111.136.23 的真实返回（2026-09-16 抓取）：risk.score、risk.level、risk.signals、network、geo 与 /v1/ip 的字段名和取值完全一致——同一时刻查，两个接口给的就是同一个数，连 risk 这一块的形状（score / level / signals）也逐字相同。逐条风险标签只在证据行 evidence[].risk_type 上，基础版不返回这一层。

多出来的是 share_tier、evidence 和 resource_pools 三项，含义见下面的字段字典。这份响应一共九个顶层键，下一节那份一个不多、一个不少。

{
  "ip": "86.111.136.23",
  "risk": {
    "score": 77,
    "level": "high",
    "signals": ["proxy"]
  },
  "share_tier": "T1",
  "evidence": [
    {
      "risk_type": "proxy",
      "freshness": "within_12h",
      "captured_at": "2026-09-15T22:43:23Z",
      "age_min": 277.12,
      "obs_days": 14
    }
  ],
  "evidence_state": "active",
  "resource_pools": ["cl-1c004db96b"],
  "computed_at": "2026-09-16T03:20:30Z",
  "network": { "asn": 15547, "usage_type": "DYN" },
  "geo": {
    "continent": "EU", "country": "CH",
    "region": "Valais", "city": "Sitten",
    "lat": 46.22739, "lon": 7.35559,
    "tz": "Europe/Zurich"
  }
}

带 at=：历史时刻#

同一个地址，把时刻拨回 09-14 09:29:23Z：字段、键名、形状与上面那份逐项一致，连 resource_pools 句柄都在。变的只有 computed_at 与相对它计算的量：分数 90（此刻 77）、obs_days 15（此刻 14）、captured_at 与 age_min 跟着那一刻的证据走。

network、geo 与上面那份完全相同——它们没有历史版本，两种问法返回的都是当前值。risk.signals 不在此列：两种问法都由本次评分真正落进 evidence[] 的风险类型折出，与同一份响应里的 evidence[] 逐项对应（没有证据行的信号不会出现）。

{
  "ip": "86.111.136.23",
  "risk": {
    "score": 90,
    "level": "high",
    "signals": ["proxy"]
  },
  "share_tier": "T1",
  "evidence": [
    {
      "risk_type": "proxy",
      "freshness": "within_2h",
      "captured_at": "2026-09-14T08:32:51Z",
      "age_min": 56.53,
      "obs_days": 15
    }
  ],
  "evidence_state": "active",
  "resource_pools": ["cl-1c004db96b"],
  "computed_at": "2026-09-14T09:29:23Z",
  "network": { "asn": 15547, "usage_type": "DYN" },
  "geo": {
    "continent": "EU", "country": "CH",
    "region": "Valais", "city": "Sitten",
    "lat": 46.22739, "lon": 7.35559,
    "tz": "Europe/Zurich"
  }
}

5.5 返回内容字段说明#

前几项与基础版 /v1/ip 是同一批字段、同一批取值（risk 这一块连形状都一样），后面几项是 Pulse 独有的。这些字段带不带 at= 都在，含义的差别只有一处：computed_at，以及相对它计算的量。

降级出分不写在 body 里，写在响应头里。单路证据源这次取不到、我们仍然出分时，响应头会带 X-Pulse-Degraded: 1。看到它就把这次结果打个折扣看，不要当成正常返回；这个接口的响应体里没有表示降级的字段。

5.6 evidence[] 里每一条#

一条证据行只有这五个键：risk_type、freshness 与 obs_days 每次都带；captured_at 与 age_min 有值才出——没出现就是那条证据没有这一项。

obs_days 不一样：它固定出现——专业版与私有化版的每条证据行都带这个键；captured_at 与 age_min 有值才出，没出现就是那条证据没有这一项。

5.7 同一套字段，只有时刻不同#

带不带 at，返回的是同一个形状。同一套键名、同一层嵌套、同一批字段——两种问法由同一段代码出结果，不是两套接口。唯一变的是 computed_at 的含义：不带 at 是此刻，带了 at= 就是你指定的那一刻。

凡是「相对某一刻」的量都相对 computed_at 解释：risk.score、risk.level、risk.signals、share_tier、evidence_state、resource_pools，以及 evidence[] 里的 freshness、captured_at、age_min、obs_days。例外只剩 network 与 geo 这两块：它们没有历史版本，两种问法返回的都是当前值。

六. network 与 geo 逐字段#

这两块和 risk.signals 一样是「有才出」：某个键没有值就不出现，整块都没值就整块不出现——不会用 0、空字符串或 null 占位。所以「键不存在」只有一个含义：不知道。按字段分组统计时，请把「键不存在」与「值真的是 0」分开处理。

注：geo 的键集合恒定：continent / country / region / city / district / tz 六个字符串键对任何查询成功的地址都在，不会因为地址在中国还是别的国家而多一个键、少一个键；库里没有的名字给空串（是「库里没有」，不是 0）。region / city 取自英文地名库，各国地址都有值；district 只有中国地址有值（英文地名库对中国收录到区县、对其它国家收录到城市，所以非中国地址到 city 为止，如 8.8.8.8 只到 California / Mountain View）。运营商名不返回的理由同理：数据源里是本地化译名（非中国行也有中文），只给一部分会让「运营商维度」的统计口径悄悄失真。

七. 风险等级、分数与处置建议#

与传统 IP 情报库最大的不同：我们给的是一个会过期的判断，而不是一个长期有效的标签。同一个地址上周是秒拨池、今天还是不是，取决于证据距今多久。所以同一个 IP 隔几小时查两次、分数不一样，是正常的。

7.1 风险分数与风险等级#

注：上表「风险分数 → 风险等级」是接口口径（risk.level 恒由 score 推出，不接受调用方另给）；「处置建议」是通用建议，不构成合同承诺——同一个分数在登录、下单、注册上的答案本就不同，最终阈值请按自家业务、成本与风险偏好定。另外 hijacked_proxy（劫持共用代理）的持有人是受害者，处理方式通常不该是封号。

7.2 共用度 share_tier#

Pulse 会给出这个地址大概被多少人共用，它决定封禁范围：数字越小，误伤到的人越少。它也参与评分——共用的人越多，旧证据衰减得越重，所以 T3 上的分天然比 T0 保守。

注：share_tier 只在 Pulse 上返回；基础版拿不到，此时按 network.usage_type 判断大致的网络形态。

7.3 读结果的分流口径#

上面几节列出了每个字段的含义，这里说明该按什么顺序读——分数最容易用错，所以不要一上来只看它。

1. 先看 evidence_state，它回答「这个结论可不可信」。值为 none 时分数一定是 0，但那是「没见过」，不是「干净」。
2. 再看 risk.score 与 risk.level。只有 active 或 stale 时它们才有内容。
3. 然后看命中了哪些风险类型，它决定怎么处理：代理、秒拨、云手机的风险含义和用户申诉理由都不一样。两个接口都先看 risk.signals（只列命中的 slug）；要每条证据的新鲜度，再看 Pulse 的 evidence[].risk_type。
4. 要决定封禁范围时看 share_tier（Pulse 才有）。同一个分数，独占 IP 和移动大内网上的处理方式不该一样。
5. 最后看降级标记：degraded 是基础版专有的 body 字段（有才出），Pulse 用响应头 X-Pulse-Degraded。它出现时给这次结果打个折扣，不要当成正常返回。

八. 风险信号说明#

risk.signals 里会出现的 slug 一共这 10 个。只列命中的，按字典序；一个都没命中时 risk 里没有 signals 这个键。其中 8 个由风险标签派生，另外 2 个说的是这个地址处在什么样的网络上，不是风险。

这 8 个与同一份响应里的 evidence[].risk_type 逐项对应。signals 里出现的每个风险标签，都能在 evidence[] 里找到那一条；反过来不一定——evidence[] 里还有自采类型（见 九. 风险标签说明）。带不带 at= 都是这条规则：risk.signals 由本次评分真正落进 evidence[] 的风险类型折出，不是照搬画像里的标签。唯一的例外是 hosting / mobile：它们是网络属性、本来就没有证据行，见下面第二段提醒。

九. 风险标签说明#

标签是固定标识，不是给人读的名字，这里给一份对照。两个接口用的是同一套写法：risk.signals 里列的就是第一列那些 slug，Pulse 的 evidence[].risk_type 也是同一批。

十. 错误码表#

所有错误都是同一个结构，便于统一处理。请按 error.code 分支，不要按 error.message 判断——后者是给人读的说明，措辞可能调整。

{
  "error": {
    "code": "invalid_ip",
    "message": "不是合法的 IPv4/IPv6 地址：…"
  }
}

10.1 通用错误码#

10.2 ?at= 专用错误码#

这几个码含义互不相同，请不要合并处理：看到码就知道该做什么——改参数、开通版本，还是稍后重试。

注：其中「参数写错、超出窗口、这个接入点没有历史数据」这几类不消耗额度：请求还没算到分数、也没查过一次数据就被退回了。

十一. DEMO 示例#

同一个查询在三种语言里的最小可用写法，一个语言一块。三段都只调免费接口 GET /v1/ip/{ip}、只用各语言标准库，不需要 Key、没有第三方依赖，把 IP 换成你自己的即可直接运行。

curl -s "https://ip99.com/v1/ip/8.8.8.8"

curl -s -H "X-API-Key: $IP99_API_KEY" "https://ip99.com/pulse/v1/ip/86.111.136.23?at=2026-09-14T09:29:23Z"

{
  "ip": "86.111.136.23",
  "risk": { "score": 90, "level": "high", "signals": ["proxy"] },
  "share_tier": "T1",
  "evidence": [
    {
      "risk_type": "proxy",
      "freshness": "within_2h",
      "captured_at": "2026-09-14T08:32:51Z",
      "age_min": 56.53,
      "obs_days": 15
    }
  ],
  "evidence_state": "active",
  "resource_pools": ["cl-1c004db96b"],
  "computed_at": "2026-09-14T09:29:23Z",
  "network": { "asn": 15547, "usage_type": "DYN" },
  "geo": { "continent": "EU", "country": "CH", "region": "Valais", "city": "Sitten", "lat": 46.22739, "lon": 7.35559, "tz": "Europe/Zurich" }
}

import json, urllib.request

def lookup(ip, key=None, at=None):
    path = "/v1/ip/" + ip
    if at:  # 历史回溯：仅 Pulse 专业版支持，需带 Key
        path = "/pulse/v1/ip/" + ip + "?at=" + at
    req = urllib.request.Request("https://ip99.com" + path)
    if key:
        req.add_header("X-API-Key", key)  # 免费接口不需要
    try:
        with urllib.request.urlopen(req, timeout=5) as r:
            return json.load(r)
    except urllib.error.HTTPError as e:
        return json.load(e)  # {"error": {"code": ..., "message": ...}}

d = lookup("8.8.8.8")
print(d["ip"], d["risk"]["score"], d["risk"]["level"], d["risk"].get("signals"), d["evidence_state"])

package main

import (
	"encoding/json"
	"fmt"
	"net/http"
	"time"
)

func main() {
	// 免费接口，不需要 Key。带 Key 时在下面加一行（Pulse 必需）：
	//   req.Header.Set("X-API-Key", os.Getenv("IP99_API_KEY"))
	req, _ := http.NewRequest("GET", "https://ip99.com/v1/ip/8.8.8.8", nil)
	resp, err := (&http.Client{Timeout: 5 * time.Second}).Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()

	var out struct {
		IP            string `json:"ip"`
		EvidenceState string `json:"evidence_state"`
		Risk          struct {
			Score   int      `json:"score"`
			Level   string   `json:"level"`
			Signals []string `json:"signals"` // 一个都没命中时该键不出现
		} `json:"risk"`
	}
	if err := json.NewDecoder(resp.Body).Decode(&out); err != nil {
		panic(err)
	}
	fmt.Println(out.IP, out.Risk.Score, out.Risk.Level, out.Risk.Signals, out.EvidenceState)
}

注：出错时 HTTP 状态码非 200，响应体仍是 {"error":{"code","message"}}，请先读 error.code 再决定是否重试（见 十. 错误码表）。历史回溯那一支只有在专业版、且该接入点已开通历史时才可用。