API 接口文档

快速开始

不需要注册，也没有 Key 的前置条件，直接调用即可。返回 JSON；响应里的地名、网络类型、风险类型一律是标准码或稳定 slug，不含中文，方便贵方直接入库与统计，不必在解析层处理中文编码。

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

加上自助创建的 Key，额度按账户计：

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

分数是什么，不是什么

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

两个接口的关系

Pulse 是基础画像的升级版。同一个分、同一份证据底座，但把精度与可回溯性各提高一档：基础画像回答「此刻是什么」，Pulse 还能回答「当时为什么这么判」，并说清这类证据有多硬——观测了多久、几个独立来源、属于哪个资源池。

档位

Pulse 是专业版能力。公开档只给分数与证据类型；单类型分、观测天数、独立来源数、资源池匿名句柄、地址归属，以及 ?at= 的历史回溯，都只对专业版及以上开放；秒级捕获时刻、精确年龄与近 30 天命中次数另需签署数据处理协议。

分级口径是按个人信息法律定性分级，不按付费能力分级：越高档位交付的不是「更多条目」，而是更精确的时间与来源刻画，那正是需要合同与审计才能外发的部分。厂商来源编码任何档位都不外发。

未达档位时的表现是明确的，不会静默少给：传 ?at= 返回 403 history_requires_professional；已到专业版但缺数据处理协议时，响应带 professional_degraded: "dpa_required"——告诉你字段是被什么扣下的，而不是让它们凭空消失。

开通专业版或签订数据处理协议 →

基础画像：GET /v1/ip/{ip}

响应示例

下面是一次真实调用（86.111.136.23，此刻判为高风险的代理出口）的原样返回：

{
  "ip": "86.111.136.23",
  "risk": {
    "score": 90,
    "level": "high",
    "tags": ["proxy"],
    "tag_details": [ { "tag": "proxy", "last_seen": "2026-09-10 13:41:22" } ]
  },
  "evidence_state": "active",
  "score_semantics": "capture_evidence_freshness",
  "computed_at": "2026-09-10T06:23:46Z",
  "signals": { "proxy": true, "vpn": false, "dialup_pool": false, "hijacked_proxy": false,
               "osint": false, "crawler": false, "cloud_service": false, "cloud_phone": false,
               "hosting": false, "mobile": false },
  "network": { "asn": 15547, "usage_type": "DYN" },
  "geo": { "continent": "EU", "country": "CH", "region": "Valais", "city": "Sitten",
           "lat": 46.22739, "lon": 7.35559, "tz": "Europe/Zurich" },
  "meta": { "provider": "threathunter", "data_version": "risk:20260910142326 geo:20260910",
            "query_ms": 0, "query_us": 225 },
  "source": "ip99.com",
  "source_url": "https://ip99.com/?ip=86.111.136.23"
}

字段字典

Pulse：GET /pulse/v1/ip/{ip}

curl -H "X-API-Key: 你的KEY" \
  "https://ip99.com/pulse/v1/ip/8.8.8.8?at=2026-08-26T13:34:36Z"

响应示例（公开档，实时）

同一次真实调用里，Pulse 对同一个地址的返回：

{
  "ip": "86.111.136.23",
  "risk": {
    "score": 90,
    "level": "high",
    "tags": ["proxy"],
    "tag_details": [{ "tag": "proxy", "last_seen": "2026-09-10T14:20:31+08:00" }]
  },
  "share_tier": "T1",
  "evidence": [
    { "risk_type": "proxy", "freshness": "within_2h", "calibrated": false, "score": 90, "sources": 2 }
  ],
  "evidence_state": "active",
  "resource_pools": ["cl-9f8e7d6c5b"],
  "score_semantics": "capture_evidence_freshness",
  "computed_at": "2026-09-10T06:23:46Z",
  "source": "ip99.com",
  "source_url": "https://ip99.com/?ip=86.111.136.23"
}

专业版会在每条证据里补上「这条证据有多硬」的字段，形如：

{
  "risk_type": "hijacked_shared_proxy",
  "freshness": "within_2h",
  "calibrated": true,
  "score": 96,
  "obs_days": 9,
  "sources": 3
}

资源池的匿名句柄在响应顶层的 resource_pools（契约 v4 起；此前叫 evidence[].channels / risk_clusters）。

字段字典

认证与额度

Key 通过请求头传递，两种写法等价：X-API-Key: 你的KEY 或 Authorization: Bearer 你的KEY。

成功响应与额度类 429 都带当日额度，不需要额外查询；分钟限速的 429（rate_limited）只带 X-RateLimit-* 与 Retry-After：

网页查询与 API 共用同一份每日额度：未登录按公网 IP 计，登录后按账户计。当前档位与剩余额度可以用 GET /v1/me 查。

登录 / 注册并创建 API Key →

错误与重试

所有错误都是同一结构，便于统一处理。请按 error.code（稳定的小写标识）分支，不要按 error.message 判断——那是给人读的说明，措辞可能调整。

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

?at= 的专用错误码

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

其中「参数写错、超出窗口、本部署没装历史库」这几类不消耗额度：我方一眼就能判定，既没算出分数也没查一次库，让客户为此付额度说不通。

手机号风险画像：POST /v1/phone/lookup

第二个能力：一个手机号是不是猫池卡、账号卡、二次放号。仅企业客户，Key 需要单独开通这条能力， 额度也独立于 IP 查询——按号码个数计，不按请求次数。免费与注册账户调用会得到 401 / 403，不会消耗任何额度。 开通请走企业版。

号码只走请求体，没有 GET /v1/phone/{号码} 这种形式：手机号是个人信息，放进 URL 会被各层访问日志原样记下。

curl -X POST https://ip99.com/v1/phone/lookup \
  -H "X-API-Key: 你的KEY" -H "Content-Type: application/json" \
  -d '{"number": "13800001234"}'

号码怎么写

常见分隔符（空格、-、括号、点）、全角数字、从表格或聊天窗口复制时夹带的零宽字符与不换行空格都会被正确归一； +86… 与 0086… 是国际写法，013800001234 这种长途前缀也认。不带 + 的裸数字串按这个顺序读： 形如 1[3-9] 开头的 11 位大陆手机号按 +86；不是那个形状、又能拆出国家码且号码本体长度符合该国规划的 （如 12025550001）当作省略了 + 的国际号；其余才按 +86 补全。要精确就带 +。

输入里出现字母、引号、emoji 等电话号码里不该有的字符时判为解析失败，不猜、不抠数字：单号查询返回 400 bad_number， 批量里对应那条带内嵌 error，两种都不计费。位数不对的号码（少打一位、座机）能解析、也确实查了库， 照常计费，返回里 query.valid_length 为 false、miss_reason 为 unqueryable_bad_length——据此把「输入错了」和「查过了，干净」分开。

响应示例（命中）

{
  "query": {
    "input": "13800001234", "e164": "+8613800001234", "national_number": "13800001234",
    "country_code": 86, "country": {"iso2": "CN"}, "valid_length": true
  },
  "hit": true,
  "evidence_state": "active",
  "risk": {
    "score": 6, "level": "medium",
    "primary_tag": {"code": 2, "slug": "dormant"},
    "tags": [{"code": 2, "slug": "dormant"}]
  },
  "activity": {
    "first_seen": "2026-06-20T10:54:16Z", "last_active": "2026-06-20T10:54:16Z",
    "last_active_days_ago": 83, "observed_days": 0
  },
  "carrier": {
    "province": "CN-BJ", "city_code": "1101", "carrier": "CMCC",
    "attribute": {"code": 0, "slug": "base_carrier"},
    "card_type": {"code": 0, "slug": "standard"}
  },
  "sources": [{"library": "cn", "risk": 6, "tag": {"code": 2, "slug": "dormant"},
               "first_seen": "2026-06-20T10:54:16Z", "last_active": "2026-06-20T10:54:16Z"}],
  "meta": {"request_id": "472ef7d6e49a49fe",
           "data_version": {"cn": "20260911", "sg": "20260911", "cn_minute": "202609120339", "sg_minute": "202609120339"}}
}

未命中时只有 query、hit: false、evidence_state: "none"、risk（0 分、空标签）、 miss_reason 与 meta。

字段字典

批量响应顶层是 count（输入个数）、billable（实际计费的号码数）、hit_count（命中条数）与 results[]； 每条结果的形状与单号查询相同，解析失败的那条只有 query.input、hit: false 与内嵌 error。

额度与响应头

批量是全有或全无：剩余额度装不下整批时整批 429 quota_exceeded、不扣费，按 X-Daily-Remaining 缩小批次重试； 一批的号码数超过每分钟额度时返回 429 batch_over_rate_limit——这一批无论何时重试都不会过，要拆小。 GET /v1/me 的 capabilities.phone 里能看到 used_today、refunded_today 与 remaining。

错误码

其他端点

/mcp 上的失败按 MCP 惯例是 HTTP 200 + isError: true（裸 429 会让客户端把服务器当成坏了）。每个 content[0].text 都是合法 JSON：成功与 GET /v1/ip/{ip} 同一份文档，失败与 REST 同一个错误体 {"error":{"code":…}}，额度类还带 retry_after（秒）、resets_at、next_step 与 signup_url / pricing_url，用光了直接照着引导登录或拿 Key。参数错误码 missing_ip / invalid_ip / reserved_ip / not_found，额度与凭据用上面「错误与重试」那张表的码；握手方法被限速时是 JSON-RPC error -32000，同一个对象在 error.data.error。登录用的端点是 https://ip99.com/mcp/account：客户端自己弹出登录页（OAuth，Claude Code / Claude.ai / ChatGPT 连接器 / Cursor 都认），不用抄 Key，额度按账户计；/mcp 仍免登录、按来访 IP 计。已授权的客户端在控制台「API Key」面板里能看到并一键断开；英文站用 /en/mcp/account，登录页与控制台随之是英文。字段与示例见英文版 /api#mcp。

面向海外开发者与答案引擎的英文版是 ip99.com/api；给机器读的站点摘要见 /llms.txt。