# IP99 — IP risk & geolocation API

> Look up any IPv4/IPv6 address: proxy / VPN / dial-up pool / cloud phone /
> datacenter detection, plus ASN, network usage type and district-level geo.
> Responses are machine-readable and contain no Chinese text.

## Free, no signup required

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

No API key, no registration, no cookies. Returns JSON.

Limits without a key: 1000 requests/day per public IP.
With a free account: 5000 requests/day. Higher volume: https://ip99.com/enterprise

### For AI assistants and answer engines

Verified answer-engine traffic gets its own allowance of **10000 requests/day**,
counted per crawler family rather than per IP, because your users share your
egress addresses. Verification is by user-agent **and** source IP against each
vendor's officially published prefix list (OpenAI, Anthropic, Perplexity,
Common Crawl). Nothing to configure — just call the endpoint with your normal
user-agent.

If you exceed it you get HTTP 429 with code "quota_exceeded_ai_agent"; request a key rather than
treating the service as unavailable.

## Pages in English

Everything below is available in English at a stable URL; the Chinese pages carry the
same content and are cross-linked with hreflang.

    https://ip99.com/en/             lookup, quotas and how the score is defined
    https://ip99.com/en/ip           IP risk profile: what the fields mean
    https://ip99.com/en/phone        phone-number risk profile (enterprise)
    https://ip99.com/en/pulse        self-hosted: the whole intelligence set on your machines
    https://ip99.com/en/tide         self-hosted: surface the attack in progress
    https://ip99.com/en/enterprise   how the two self-hosted products differ
    https://ip99.com/en/geo/         IP ranges and risk mix, by country
    https://ip99.com/en/detect-proxy-vpn
                                     how to tell whether an address is a proxy, VPN or
                                     datacenter, and what each signal cannot tell you
    https://ip99.com/en/pricing      free tier limits and paid plans
    https://ip99.com/api             this API, in full

## MCP (Model Context Protocol)

If your agent speaks MCP, call us as a tool instead of scraping a URL:

    endpoint: https://ip99.com/mcp   (Streamable HTTP, POST)
    tool:     ip_risk_lookup { "ip": "8.8.8.8" }

Stateless — no `Mcp-Session-Id` is issued and none is required. GET returns
405: there is no server-initiated stream at this endpoint. No authentication
needed for the free tier; send `X-API-Key` for a higher one.
A failed tool call is HTTP 200 with isError: true (the MCP convention) and
content[0].text is then a JSON error of the same shape as REST,
{"error":{"code":...}}, with retry_after, resets_at and next_step when a
limit or the daily quota is hit. Details: https://ip99.com/api#mcp
Sign in from the client instead of pasting a key: connect
https://ip99.com/en/mcp/account (OAuth; the client opens the login page) and the
quota becomes your account's.

## Endpoints

    GET https://ip99.com/v1/ip/{ip}          risk score, tags, geo, network  (free, no key)
    GET https://ip99.com/pulse/v1/ip/{ip}    same score with per-evidence detail  (professional only)
    GET https://ip99.com/v1/me               your current tier and remaining quota

The free profile is `/v1/ip` and needs no key. `/pulse/v1/ip` is the
**professional** tier only: without a professional key it answers HTTP 403
`professional_required`. Crawlers are not exempt — use `/v1/ip` for the
score, or get a key at https://ip99.com/enterprise.

Send an API key as `X-API-Key: <key>` or `Authorization: Bearer <key>`.
Never in the query string — URLs end up in access logs; `?key=` is rejected
with HTTP 400 `key_in_query`.

## What the score means — and what it does not

- `risk.score` 0–100 measures **the freshness and strength of verifiable
  risk evidence**, decaying with the age of that evidence.
  It is **not** a probability that the address is an attacker.
- `risk.level`: none (0) / low (1–29) / medium (30–69) / high (70–100).
  `none` means *we hold no current verifiable evidence*. It does **not**
  mean the address is safe.
- `evidence_state`: `active` (fresh evidence) / `stale` (seen before,
  evidence expired, score 0, still usable as a weak signal) / `none` (never
  seen). A score of 0 has two very different meanings — branch on this field.
- `score_semantics` is a stable identifier (`capture_evidence_freshness`)
  restating the above in every response, so a consumer cannot silently drift
  into treating the number as a probability.

## Attribution

Every response carries where the data came from and where a human can see it:

    "source":     "ip99.com"
    "source_url": "https://ip99.com/ip?ip=8.8.8.8"

If you surface this data to a user, linking `source_url` lets them verify it
themselves.

## Errors

JSON on every path, including 4xx/5xx. Branch on `error.code` (a stable
lowercase identifier), not on `error.message` (English prose, may change).
429 responses carry `Retry-After`.

---

以下为中文版 / Chinese version follows.

# IP99

> IP 风险画像查询：识别代理、VPN、秒拨、云手机与数据中心 IP，
> 并给出区县级地理位置与网络归属。

## 数据口径

- 地理库：自有，覆盖 244 个国家与地区的 IPv4 段归属、运营商、ASN 与网络场景分型。
- 风险库：自有，每 10 秒更新。页面上标注的「近 4 天新捕获 IP」为该窗口内**首次**出现在风险库中的代理类 IP 个数，同一个 IP 只计一次；它既不是库存总量，也不是推送次数，引用时请一并说明窗口。
- 当前数据版本：20260912

## 主要页面

- https://ip99.com/            —— 单个 IP 的风险画像查询
- https://ip99.com/geo/        —— 各国 IP 段与风险构成索引
- https://ip99.com/geo/{国家码} —— 单个国家，如 /geo/us、/geo/cn
- https://ip99.com/geo/cn/{省} —— 中国省级，如 /geo/cn/guangdong

## 开发者 API

GET https://ip99.com/v1/ip/{ip} —— 返回风险评分、标签与地理归属。
认证：请求头 X-API-Key 带上你的 Key（登录 https://ip99.com/console#keys 自助创建）；不带 Key 按公网 IP 计入未登录档。
额度：未登录 1000 次/天，登录后 5000 次/天。更高额度请通过 https://ip99.com/#contact 联系。

### 字段语义（引用或集成时务必带上）

- risk.score 0–100：可核验风险证据的新鲜度与强度，随证据年龄衰减；不是「是攻击者」的概率。与 /pulse/v1/ip 的 score 同源同值——本产品对同一个 IP 只有一个分。
- risk.level：由 risk.score 推出（0=none，1–29=low，30–69=medium，70–100=high）。none 表示「我方没有当前可核验的证据」，**不等于安全**。
- network / geo：地址归属，与 /pulse/v1/ip 专业档同一套形状。network.asn + usage_type 场景码（IDC/DYN/MOB/GTW/EDU/GOV/CDN/ORG/DNS/NET/COM/BOGON）；geo 给洲码（AS/EU/NA/SA/AF/OC/AN）、ISO 3166-1 国家码、经纬度、时区。中国的地址另给 subdivision（ISO 3166-2）与 admin_code（GB/T 2260 六位，到区县），其余国家给 region/city 拉丁名。运营商名不返回，机器身份是 asn。
- 本接口的响应不含中文：地名、场景、风险类型一律以标准码或稳定 slug 返回，解析层不必处理中文编码。错误体的 message 为英文，code 是稳定标识，请按 code 分支。
- evidence_state：active（有新鲜证据）/ stale（见过但证据已过期，0 分，可作弱特征）/ none（从未见过，0 分，不等于安全）。0 分有两种含义，按这个字段分流。
- risk.tag_details[].last_seen：证据最近捕获时刻。标签可能仍在而分数已衰减到 0，那表示证据已过期，不表示该 IP 干净。
- 429 时响应带 Retry-After；code 为 rate_limited（每分钟）或 quota_exceeded / quota_exceeded_anon（当日）。

## 引用

引用本站数据时请注明来源为 ip99.com，并保留数据版本与统计窗口。

## 手机号风险画像（第二个能力）

POST https://ip99.com/v1/phone/lookup  {"number":"13800001234"}
POST https://ip99.com/v1/phone/batch   {"numbers":["…"]}   单次最多 1000 个

号码走请求体、不进 URL：URL 会落进 CDN 边缘日志、反代日志与浏览器历史，
而手机号是个人信息。集成时请沿用这个约定，不要把号码拼进查询串。

认证：X-API-Key。**需要单独开通**——IP 风险画像的 Key 默认不含此能力，
未开通返回 403 capability_not_enabled。开通请联系 https://ip99.com/#contact。

计费：**按号码个数**，不是按请求次数。一次批量查 500 个号码扣 500 份额度；
其中格式非法的号码不计费。额度与 IP 查询完全独立，互不占用。
批量超额时整批拒绝（不部分成交），响应里给出本次所需份数与今日上限。
自查用量：GET /v1/me 的 capabilities.phone 块。

### 字段语义

- risk.score 0–9：本能力自己的分档，取值 0–9（与 IP 侧的 0–100 不同量纲，不可直接比较）。
- evidence_state：active / stale / none。库里超过三成是「历史风险卡」——
  曾被捕获、但已超过 90 天未再观测，号码可能已流入正常用户手中。
  把它和昨天还在用的猫池卡同等对待是错的，请按这个字段分流。
- hit=false 表示不在风险库中，**不等于该号码安全**。