# 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 geo down to the city > (the district for Chinese addresses). > 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: 500 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/domain passive DNS: which IPs a domain resolved to, historically https://ip99.com/en/cert certificate transparency: which certificates a domain has had issued, and by whom 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/asn/ IP ranges and usage-type mix (residential vs datacenter), by autonomous system https://ip99.com/en/proxy-exits proxy exit addresses the IP99 risk feed captured in the last 7 days: counts by usage type, country and ASN, refreshed daily; aggregates only, no address lists 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. ## Guides (answer-first, with FAQ) - https://ip99.com/en/what-is-my-ip — What is my IP address? Find your public IPv4 or IPv6 address - https://ip99.com/en/ip-location — IP location: how to find where an IP address is, and how accurate it is - https://ip99.com/en/ip-address-lookup — IP address lookup: what you can find out about an IP, and what you cannot - https://ip99.com/en/detect-proxy-vpn — How to detect a proxy, VPN or datacenter IP - https://ip99.com/en/rotating-residential-proxies — Rotating residential proxies and dial-up pools: what they are and how to detect them - https://ip99.com/en/ip-risk-score — What an IP risk score means, and why 0 is not "safe" - https://ip99.com/en/residential-vs-datacenter-proxies — Residential proxy vs datacenter proxy: how to tell them apart - https://ip99.com/en/is-this-ip-a-vpn — Is this IP a VPN? What a VPN exit looks like in the data - https://ip99.com/en/ip-risk-evidence-freshness — How fresh should IP risk evidence be? Decay, re-querying and caching - https://ip99.com/en/what-is-an-asn — What is an ASN, and why fraud controls act on whole networks - https://ip99.com/en/free-ip-geolocation-risk-api — Free IP geolocation and risk API: limits, fields and how to call it ## Endpoints GET https://ip99.com/v1/ip the caller's own address and profile (free, no key) GET https://ip99.com/v1/ip/{ip} risk score, risk.signals, 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 OpenAPI 3.1: https://ip99.com/openapi.json 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: ` or `Authorization: Bearer `. 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. ## Domain intelligence (free trial, no key) GET https://ip99.com/v1/domain/dns/{domain} passive DNS history GET https://ip99.com/v1/domain/certs/{domain} certificate transparency records GET https://ip99.com/v1/domain/fingerprint/{hex} other domains on the same certificate GET https://ip99.com/v1/domain/registered/{date} domains registered on a date (domain/ip/registrar/country, YYYY-MM-DD) GET https://ip99.com/v1/domain/malware/{domain} malware-list check: dates this domain was listed (same data as profile.malware) GET https://ip99.com/v1/domain/reverse/{ip} reverse IP lookup: the domains this address historically resolved (?offset= to page) GET https://ip99.com/v1/domain/meta/coverage corpus size and status, pDNS rows only (spends no quota) Six endpoints share one trial allowance of **10/day per public IP**, counted separately from the IP lookup quota. They are endpoints of this site, not part of the OpenAPI spec. - These are **observations, not verdicts**: passive DNS and certificate transparency record what a name resolved to and which certificates it used — not whether the domain is safe. - dns responses carry a **profile** object besides data[]: country / city / ASN number / ASN org for every resolved IP (ip_enrichment), a record-type breakdown (record_types), nameservers and MX, and malware-list hits (malware.listed). That is what answers "where does this name resolve, and whose network are those addresses". **whois is always null** (we hold no registrant data). - /v1/domain/registered has **no pagination**: the first 1000 rows only, no has_more and no next_offset in the body, and offset is rejected with HTTP 400 pagination_unsupported. Looping on has_more here gets the same page again, forever. malware carries no pagination fields either — one domain's listing dates fit in a single answer. - malware answers **HTTP 200 whether it hits or not**: judge by whether data is empty, not by the status code. It is the **same data** as profile.malware in dns responses (listed / last_listed / days_listed), just far cheaper (~5 ms), so it fits per-item pipeline checks. - reverse is the **same corpus read the other way**: dns answers "which addresses did this name resolve to", reverse answers "which domains resolved to this address". Each row is domain / rrtype / first_seen / last_seen, up to 1000 rows per call, and it **does paginate** (read has_more and next_offset, continue with ?offset=N) — the opposite of registered and malware, so do not carry the "no paging" habit over. It is a full-table scan, slower than the rest of this line (seconds); we wait at most 25 seconds for it. - reverse takes a **bare address only** (an IPv4/IPv6 literal): a port (8.8.8.8:443), an IPv6 zone (fe80::1%eth0) or a scheme prefix is HTTP 400 `invalid_ip`. A netmask written with a slash (8.8.8.8/32) does **not** match this route's shape and gets 404 not_found — strip the netmask and retry; do not read it as "this endpoint does not exist". **Private addresses are legitimate queries** — values such as 10.0.0.1 and ::1 really appear in DNS records, so an answer about them is data, not an error. - {date} must be a real calendar date: 2026-13-45 is HTTP 400 `invalid_date`, not "nothing registered". - {hex} is 64 hex characters with no colons; a colon-separated fingerprint is HTTP 400 `invalid_fingerprint`. - An empty array is not an error: for dns/certs it means we hold no record for that name (which does not mean the domain does not exist); for registered it means nothing was registered that day; for malware it means the domain is not on the list. - Top-level **corpus_last_seen** in **dns** responses is the corpus cutoff date (it advances; do not hard-code it). **CT responses carry no such field** — their ts / not_before are ingestion and validity timestamps, minute-level by nature. Judge how old a resolution record is by reading last_seen together with the cutoff: the corpus is imported in periodic batches, so anything resolved after the cutoff is simply absent — reporting "no resolution records" from an empty array is wrong. - Domains must be written in **ASCII**: use the punycode form for internationalized names (for example xn--fiq228c.com). A Unicode form returns HTTP 400 `invalid_domain` — that means the domain spelling is wrong, not that the endpoint is missing. - **The 400s on this line are split by parameter**, so branch on error.code rather than on the status: `invalid_domain` (domain spelling), `invalid_ip` (what reverse takes), `invalid_fingerprint` (the 64-hex certificate fingerprint), `invalid_date` (the registered date). All four are HTTP 400 and the message is English prose that may change. - Responses contain no non-ASCII text; branch on the stable error.code. ## 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 秒更新。页面上标注的「近 7 天新捕获 IP」为该窗口内**首次**出现在风险库中的代理类 IP 个数,同一个 IP 只计一次;它既不是库存总量,也不是推送次数,引用时请一并说明窗口。 - 当前数据版本:20261112 ## 主要页面 - https://ip99.com/ —— 单个 IP 的风险画像查询 - https://ip99.com/domain —— 域名情报试查:被动 DNS、证书签发史与每日新增域名 - 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 计入未登录档。 额度:未登录 500 次/天,登录后 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 是场景码原样透传,我们给它译名了 20 个:ANY/CDN/DNS/EDU/GTW/GOV/DYN/IDC/IXP/MOB/NET/ORG/SAT/BOGON/AUR/RNU/UND/WLA/DDT/USE(逐字段与取值见 https://ip99.com/api-docs#network-geo)。**这张表不等于全部可能取值**:出现表外的码不是错误,只是我们还没有它的译名——机器接口照原样返回,请按「不认识的码」处理,不要因为不认识就丢掉整条记录。geo 给洲码(AS/EU/NA/SA/AF/OC/AN)、ISO 3166-1 国家码、经纬度、时区,以及 region / city / district 三个拉丁地名。**geo 的键集合恒定**:六个字符串键(continent/country/region/city/district/tz)对任何查询成功的地址都在——region 与 city 所有国家的地址都有值(中国地址同样有),district 的值只有中国地址非空(英文地名库对中国收录到区县、对其它国家收录到城市);**库里没有的名字给空串**(不是 0,也不会拿别的层级顶上),一套解析代码可以处理所有行。 - 本接口的响应不含中文:地名、场景、风险类型一律以标准码或稳定 slug 返回,解析层不必处理中文编码。错误体的 message 为英文,code 是稳定标识,请按 code 分支。 - evidence_state:active(有新鲜证据)/ stale(见过但证据已过期,0 分,可作弱特征)/ none(从未见过,0 分,不等于安全)。0 分有两种含义,按这个字段分流。 - risk.signals:本接口的 risk 与 /pulse/v1/ip 专业档**同一形态**,只出 score / level / signals。signals 是命中信号的稳定 slug 数组(十个:proxy、vpn、dialup_pool、hijacked_proxy、osint、crawler、cloud_service、cloud_phone、hosting、mobile,后两个描述网络、本身不是风险),按字典序、只列命中的;一个都没命中时没有这个键。**v9(2026-09-17)起 risk.tags / risk.tag_details 与顶层 signals 布尔对象已停发**(存量读它们的接入方会拿到 undefined);标签与秒级时刻只在专业档的证据行上(evidence[].captured_at / age_min)。 - 429 时响应带 Retry-After;code 为 rate_limited(每分钟)或 quota_exceeded / quota_exceeded_anon(当日)。 ## 引用 引用本站数据时请注明来源为 ip99.com,并保留数据版本与统计窗口。 ## 域名情报(免 Key 试查) 域名线五条端点都不需要 Key,共用一把按访客公网 IP 计的每日试查额度 (10 次/天,与 IP 查询的额度互不占用): GET https://ip99.com/v1/domain/dns/{domain} 被动 DNS:该域名解析过的历史记录 GET https://ip99.com/v1/domain/certs/{domain} 证书透明度:该域名的证书(签发机构、有效期、指纹) GET https://ip99.com/v1/domain/fingerprint/{fp} 证书扩线:同一张证书上还签了哪些域名 GET https://ip99.com/v1/domain/registered/{date} 某一天新注册的域名清单(domain/ip/registrar/country),{date} 形如 2026-10-08 GET https://ip99.com/v1/domain/malware/{domain} 恶意名单核验:该域名被列入的日期(与 dns 的 profile.malware 是同一份数据) GET https://ip99.com/v1/domain/reverse/{ip} IP 反查:这个 IP 历史上解析到过哪些域名({ip} 是 IPv4/IPv6 字面量,可带 ?offset= 翻页) GET https://ip99.com/v1/domain/meta/coverage 语料规模与状态,不占额度(只报 pDNS 的 pdns_rows,没有 CT 侧计数) ### 引用时务必带上的边界 - **这是观测记录,不是判决。** 被动 DNS 与证书透明度回答的是「这个名字曾经或正在解析成什么、 用过哪些证书」,**不是「这个域名安不安全」**。把它转述成风险结论是错的。 - dns 响应除 data[] 外还带 **profile**:每个落地 IP 的国家/城市/ASN 号/ASN 组织(ip_enrichment)、 记录类型分布(record_types)、NS 与 MX、恶意名单命中(malware.listed)。问「这个域名解析到哪、 那些 IP 属于什么网络」要看它。**whois 恒为 null**(我方不掌握注册者数据),不要依赖它。 - 空数组不是错误,但**含义按端点不同**:dns 与 certs 回空表示我方语料里没有这个域名的记录 (不等于该域名不存在);registered 回空表示那一天没有新增;malware 回空表示**不在名单里**。 - malware **命中与未命中都是 HTTP 200**:判定看 data 是否为空,不要看状态码。 它与 dns 响应里的 profile.malware 是**同一份数据**(listed / last_listed / days_listed), 只是问得更轻(毫秒级),适合流水线逐条核验。 - reverse 是**反方向**的同一份数据:dns 回答「这个域名解析到过哪些 IP」,reverse 回答 「这个 IP 上还挂过哪些域名」。每行是 domain / rrtype / first_seen / last_seen, 一次最多 1000 条,**有翻页**(读 has_more 与 next_offset,接着取用 ?offset=N)—— 与 registered / malware 那两条正好相反,别把「不翻页」的习惯带过来。 它是全表查询,比域名线其它端点慢(秒级),我们最多等它 25 秒。 - reverse 的 {ip} 只收**裸地址**(IPv4/IPv6 字面量):带端口(8.8.8.8:443)、IPv6 zone (fe80::1%eth0)或协议前缀是 HTTP 400 invalid_ip。⚠️ 带斜杠的**掩码**写法 (8.8.8.8/32)不匹配本路由的形状,得到的是 404 not_found——去掉掩码再查,别读成 「这条接口不存在」。**私有地址是合法查询**——10.0.0.1、::1 这类值在 DNS 记录里真实 存在,回的是「记录里写过这个地址的域名」,不是错误。 - **只有 dns 响应**顶层的 corpus_last_seen 是语料截止日(会随时间推进,**不要写死**)。 **CT 侧没有这个字段**——证书的 ts 与 not_before 是入库与生效时刻,本身就是分钟级的。 判断「这条解析记录有多旧」必须把它与 last_seen 一起读:语料是周期性批量导入的,截止日 之后的解析不在结果里——**把「查不到」直接说成「该域名没有解析记录」是错的**。 - registered **不提供翻页**:一次只回前 1000 条,响应里没有 has_more 与 next_offset; 带上 offset 会被拒(HTTP 400,code 为 pagination_unsupported)。 **照 has_more 写循环在这里拿不到更多数据**,而且每次都拿到同一批。malware 同样不带翻页字段。 - registered 的 {date} 必须是**真实日历日**:2026-13-45 回 HTTP 400 invalid_date,不是「那天没有新增」。 - 指纹是 **64 位十六进制、不带冒号**:3f:8a:1c 这种分段写法回 HTTP 400 invalid_fingerprint。 - 域名只接受 **ASCII 写法**:要查国际化域名请写 punycode 形(xn--fiq228c.com)。 写 Unicode 形会回 HTTP 400 invalid_domain——那是「域名写法不对」,不是端点不存在。 - 域名线的 400 **按参数分档**:请按 code 而不是状态码分支——invalid_domain(域名写法)、 invalid_ip(反查那一段收的是地址)、invalid_fingerprint(指纹)、invalid_date(日期)。 四个都是 HTTP 400;message 是英文说明,可能变化。 - 响应里**没有一个汉字**:域名、地名、机构名一律按原样返回拉丁字符;错误体的 code 是稳定 标识、message 是英文,请按 code 分支。 ## 手机号风险画像(第二个能力) 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 表示不在风险库中,**不等于该号码安全**。