API 参考文档

简单一致的接口。已启用 CORS,无需身份验证。完整的多语言支持 —— 每个字段的键和值都会翻译成 10 种以上的语言。

基础 URL

https://ipto.to

快速开始

# Detect your own IP
curl https://ipto.to/v1/ip

# Look up any IP
curl https://ipto.to/v1/ip/8.8.8.8

# Bulk lookup (up to 100 IPs, Pro/Enterprise only)
curl -X POST https://ipto.to/v1/ip/bulk \
  -H "Content-Type: application/json" \
  --data '["1.1.1.1","8.8.8.8","9.9.9.9"]'

终端快捷方式: 当请求来自 curl、Wget 或 HTTPie 时(通过 User-Agent 检测),curl ipto.to 或 curl ipto.to/8.8.8.8(无需 https:// 或 /v1/ip/)同样可用。它返回的是更简短的、类似 ipinfo.io 风格的字段集(ip、country、city、asn、org 等),而非下方的完整结构 — 如需获取本页文档所述的完整响应,请直接使用 /v1/ip 路径。

仅返回 IP: curl ipto.to/ip(或在浏览器中打开)只会以纯文本形式返回您自己的 IP 地址 —— 例如 73.9.114.155,没有 JSON,也没有页面外壳。是 ipinfo.io/ip 的直接等价物。参见下方的 GET /ip。

默认支持多语言：将 ?lang= 设为任意受支持的代码，响应中的每个 JSON 键和值都会翻译回来 —— 不只是国家/大陆。完整语言列表和 &localize=0 退出选项请见下方的本地化。

curl "https://ipto.to/v1/ip/8.8.8.8?lang=de"
# "landesname":"Vereinigte Staaten","ist_vpn":false, ...
# every key & value comes back translated -- add &localize=0 for the legacy English-keys shape

Lookup Lab

构建任意 ipto 请求，复制为你所用语言的可直接运行的代码，或在此直接发送并查看实时响应。免费套餐无需密钥。

MCP 服务器

ipto 同时也可作为 MCP(模型上下文协议)工具服务器访问 —— 将 Claude Desktop、Cursor 或任何支持 MCP 的客户端指向下方的接口地址,即可使用它暴露的 14 个可调用工具:ip_lookup、bulk_ip_lookup(专业版/企业版)、asn_lookup、country_lookup、reverse_dns_lookup、user_agent_parse、phone_lookup、email_lookup、fraud_score、language_detect、currency_convert、weather_lookup、trademark_lookup 以及 patent_lookup。基于 Streamable HTTP 的 JSON-RPC 2.0 —— 仅支持 POST,无需会话或 SSE。认证方式与 REST API 相同:不传则使用免费层级(按 IP 计,每天 1,000 次请求),或在接口 URL 后追加 ?api_key=。

{
  "mcpServers": {
    "ipto": { "url": "https://ipto.to/mcp" }
  }
}

对于仅支持 stdio 的客户端,可通过以下方式桥接:npx mcp-remote https://ipto.to/mcp

curl -X POST https://ipto.to/mcp \
  -H "Content-Type: application/json" \
  --data '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"ip_lookup","arguments":{"ip":"8.8.8.8"}}}'

接口

GET/ip

仅以纯文本形式(Content-Type: text/plain)返回请求客户端自身的公网 IP 地址 —— 例如 73.9.114.155。是 ipinfo.io/ip 的直接等价物:无论是通过 curl、Wget、HTTPie,还是直接在浏览器中访问,行为都完全一致(不像上面的 curl ipto.to 快捷方式那样依赖 User-Agent 检测),在浏览器中打开时只会渲染出裸 IP,没有任何页面外壳。

无参数,无查询字符串。如需完整的地理位置/威胁情报对象,请改用下方的 GET /v1/ip。该路由直接读取连接方 IP(不进行 D1/KV 查询),且不计入每日请求预算 —— 参见速率限制。

curl https://ipto.to/ip
# 203.0.113.7

GET/v1/ip

返回请求 IP 的地理位置和威胁情报数据,包括通过 CF 边缘对象获取的城市级数据。

无必填参数。支持 ?lang=、?fields=、?format= —— 参见下方的本地化和输出格式部分。

curl https://ipto.to/v1/ip
# the lookup for the calling IP: same shape as /v1/ip/:ip below

GET/v1/ip/:ip

查询任意 IPv4 地址。当该 IP 落在 IP2Location 或 MaxMind 这两个合并地理数据集之一的覆盖范围内时,会填充城市级字段(city、state、postal_code、latitude、longitude、timezone)—— 可通过响应中的 geo_precision 判断得到的是城市级还是国家级数据。timezone 的格式取决于匹配到的数据源(IP2Location 返回 UTC 偏移字符串,MaxMind 返回 IANA 名称)。IPv6 查询目前只返回国家级数据。

Parameter	In	Description
`ip`	path	必填。任意有效的 IPv4 或 IPv6 地址。
`lang`	query	可选。用于本地化 country_name 和 continent:en(默认)、pt, fr, de, zh-TW, ko, zh-CN, ja-JP, es-ES, ar-SA, hi-IN。
`fields`	query	可选。以逗号分隔的待返回字段列表。例如 ?fields=ip,country_code,is_vpn
`format`	query	可选。响应格式:json(默认)、csv、text、xml、yaml。

curl https://ipto.to/v1/ip/8.8.8.8

# only the fields you want:
curl "https://ipto.to/v1/ip/8.8.8.8?fields=ip,asn,country_code,city"
# {"ip":"8.8.8.8","asn":15169,"country_code":"US","city":"Mountain View"}

GET/v1/search/:query

这是首页搜索框背后使用的统一搜索接口。它会检测 :query 是 IP、ASN(AS15169 或 15169)、两位字母的国家代码、邮箱还是电话号码,然后将所有相关检查聚合到一个响应中返回。对于 IP 查询,该接口会在服务端并行展开 —— 同时调用主 IP 查询以及 RPKI、IP 归属公司、移动运营商、关联域名和地点信息查询,因此一次搜索只会占用您每日速率限制预算中的一次请求,而不是每个功能单独计费。

Parameter	In	Description
`query`	path	必填。IP、ASN、国家代码、邮箱或电话号码。

Field	Type	Description
`query`	string	接收到的、已解码的原始输入。
`detected_type`	string	"ip"、"asn"、"country"、"email" 或 "phone"。
`ip`	object\|null	当 detected_type 为 "ip" 时出现 —— 结构与 GET /v1/ip/:ip 相同。
`rpki`	object\|null	IP 查询时出现 —— 结构与 GET /v1/ip/:ip/rpki 相同。
`company`	object\|null	IP 查询时出现 —— 结构与 GET /v1/ip/:ip/company 相同。
`whois`	object\|null	IP 查询时出现 —— 结构与 GET /v1/ip/:ip/whois 相同。
`carrier`	object\|null	IP 查询时出现 —— 结构与 GET /v1/ip/:ip/carrier 相同。
`asn / country / email / phone`	object\|null	当 detected_type 匹配其他类型时,会以此字段替代上述六个字段 —— 结构与该类型自身的专用接口相同。

每个子字段都会独立降级 —— 某个上游服务(RIPEstat、某个 RDAP 服务器、crt.sh)响应缓慢或失败,只会表现为对应字段返回 null,而不会导致整个搜索失败。只有主查询本身无效(例如格式错误的 IP)时,整个请求才会返回错误状态。

curl https://ipto.to/v1/search/8.8.8.8

GET/v1/ip/:ip/hostname

反向 DNS —— 通过 DNS-over-HTTPS 进行的单次实时 PTR 查询,而非域名枚举数据库。如果该 IP 没有 PTR 记录,则返回 null。

Parameter	In	Description
`ip`	path	必填。任意有效的 IPv4 或 IPv6 地址。

curl https://ipto.to/v1/ip/8.8.8.8/hostname
# {"ip":"8.8.8.8","hostname":"dns.google"}

GET/v1/ip/:ip/rpki

针对某 IP 当前宣告路由的 RPKI 路由源验证,通过 RIPEstat 实时解析(本地不摄取或同步任何 ROA 数据库)。status 只会是 "valid"、"invalid" 或 "unknown" 之一 —— 绝不会根据其他信号推断合成;任何 RIPEstat 失败或超时都会返回带有原因说明字符串的 "unknown",而不是错误。

Parameter	In	Description
`ip`	path	必填。任意有效的 IPv4 或 IPv6 地址。

Field	Type	Description
`asn`	integer\|null	当前宣告该路由的 ASN,通过实时解析获得 —— 并非来自本站自身的 ASN 数据集。
`prefix`	string\|null	当前宣告的 CIDR 前缀。
`status`	string	"valid"、"invalid" 或 "unknown"。
`validating_roas`	array	RIPEstat 匹配到的具体 ROA 记录,每条包含 origin/prefix/max_length/validity。
`validator`	string\|null	RIPEstat 使用的 RPKI 验证器(例如 "routinator")。
`reason`	string\|null	说明 "unknown" 结果的原因 —— 例如不存在覆盖该前缀的 ROA,或 RIPEstat 无法访问。

curl https://ipto.to/v1/ip/8.8.8.8/rpki
# {"ip":"8.8.8.8","asn":15169,"prefix":"8.8.8.0/24","status":"valid",...}

GET/v1/rpki

显式的(ASN、前缀)RPKI 验证 —— 适用于您已经明确知道想要检查的具体路由,而非依赖上方由 IP 推导出的便捷方式。

Parameter	In	Description
`asn`	query	必填。ASN 编号,可带或不带 AS 前缀。例如 15169 或 AS15169。
`prefix`	query	必填。CIDR 前缀,例如 8.8.8.0/24。

curl "https://ipto.to/v1/rpki?asn=15169&prefix=8.8.8.0/24"

GET/v1/ip/:ip/company

通过将 RDAP(结构化 WHOIS)注册人数据与 ASN 自身的机构名称相结合,识别某 IP 的注册机构,并给出分类置信度,而非数值分数。

Parameter	In	Description
`ip`	path	必填。任意有效的 IPv4 或 IPv6 地址。

Field	Type	Description
`company_name`	string\|null	解析得到的公司名称 —— 当 confidence 为 "low"(两个数据源结果不一致,因此都不作为权威结果呈现)或 "none" 时为 null。
`rdap_org_name`	string\|null	RDAP 注册人名称,独立于 company_name。
`asn_org_name`	string\|null	ASN 自身的机构名称,独立于 company_name。
`confidence`	string	"high"(数据源一致)、"medium"(仅有一个数据源可用)、"low"(数据源不一致 —— 两者均显示)或 "none"。
`reason`	string	对置信度等级的简明说明。

curl https://ipto.to/v1/ip/1.1.1.1/company
# {"ip":"1.1.1.1","company_name":null,"rdap_org_name":"APNIC Research and Development","asn_org_name":"Cloudflare, Inc.","confidence":"low",...}

GET/v1/ip/:ip/whois

底层的 RDAP 注册记录本身 —— 包括网络块、注册/最后变更日期,以及 RDAP 存档的每一个联系人信息。这与上方的 /company 不同,后者会将同一份注册人数据与 ASN 的机构名称进行核对,得出一个带置信度评分的结果;而本接口按原样返回原始记录,更接近传统的 WHOIS 输出。同样支持 IPv6 地址。

Parameter	In	Description
`ip`	path	必填。任意有效的 IPv4 或 IPv6 地址。

Field	Type	Description
`available`	boolean	如果无法解析出 RDAP 记录则为 false —— 参见 reason。
`reason`	string\|null	说明 available: false 结果的原因。
`startAddress / endAddress / cidr`	string\|null	注册的网络块。
`netName / netHandle / parentHandle`	string\|null	RIR 为该网络对象分配的标识符。
`country`	string\|null	根据 RDAP 得出的注册人所在国家。
`allocationType`	string\|null	例如 "direct allocation"、"reassigned"。
`registeredDate / lastChangedDate`	string\|null	RDAP 记录中的 ISO 时间戳。
`rir`	string\|null	提供该记录的区域注册管理机构(ARIN、RIPE、APNIC、LACNIC、AFRINIC)。
`contacts`	array	RDAP 存档的每一个联系人,均包含 roles、name、email 和 handle —— 而不仅仅是第一个匹配结果。

curl https://ipto.to/v1/ip/8.8.8.8/whois
# {"ip":"8.8.8.8","available":true,"cidr":"8.8.8.0/24","netName":"LVLT-GOGL-8-8-8","rir":"ARIN","contacts":[...],...}

GET/v1/ip/:ip/carrier

针对被归类为移动网络的 IP,尽力识别其移动运营商,并与 MCC/MNC 运营商目录进行交叉比对。该接口刻意不提供单一的 carrier 字段 —— 参见下方的 matched_carrier_entries 和 note —— 因为一个孤立的运营商名称会被解读为针对具体用户的实时判定,而这份数据无法诚实地支撑这样的结论。

Parameter	In	Description
`ip`	path	必填。任意有效的 IPv4 或 IPv6 地址。

Field	Type	Description
`is_mobile_network`	boolean	为 false 时到此为止,directory 为空 —— 对非移动 ASN 不做任何猜测。
`asn_organization`	string\|null	ASN 自身的机构名称。
`matched_carrier_entries`	array	MCC/MNC 目录中运营商名称与 asn_organization 模糊匹配的条目,范围限定在该 IP 所在国家内。
`note`	string	说明该字段能够以及不能得出的结论。

curl https://ipto.to/v1/ip/8.8.8.8/carrier
# {"ip":"8.8.8.8","is_mobile_network":false,"asn_organization":null,"matched_carrier_entries":[],...}

GET/v1/ip/:ip/hosted-domains

通过某 IP 的反向 DNS(PTR)主机名以及证书透明度日志(crt.sh)查找与之关联的域名 —— 并非通用的反向 IP 查询。响应中的 limitations 字段会明确说明该功能能够以及不能发现哪些内容。

Parameter	In	Description
`ip`	path	必填。任意有效的 IPv4 或 IPv6 地址。

Field	Type	Description
`ptr_hostname`	string\|null	该 IP 的反向 DNS 主机名,如果没有 PTR 记录则为 null。
`root_domain`	string\|null	从 ptr_hostname 推导出的可注册域名。
`subdomains_seen`	array\|null	通过证书透明度发现的子域名。null 表示 crt.sh 查询本身未能完成 —— 这与空数组不同,空数组表示查询已执行但未发现任何结果。
`limitations`	string	说明该功能在结构上无法检测到的情况(无 PTR 记录、共享主机、未签发证书的域名)。

curl https://ipto.to/v1/ip/8.8.8.8/hosted-domains
# {"ip":"8.8.8.8","ptr_hostname":"dns.google","root_domain":"dns.google","subdomains_seen":["dns.google","dns.google.com",...],...}

POST/v1/ip/bulk

批量查询 —— 每次请求最多 100 个 IP,仅限专业版/企业版使用。返回一个以每个 IP 为键的对象。由于采用并行的缓存和数据库读取,速度快于依次单独调用。批次中的每个 IP 都会计入您的每日请求预算,与单独查询时相同。免费层级的请求会收到 403 —— 参见价格。

Parameter	In	Description
`body`	body (JSON)	IP 字符串组成的 JSON 数组。例如 ["1.1.1.1","8.8.8.8"]

curl -X POST https://ipto.to/v1/ip/bulk \
  -H "Content-Type: application/json" \
  --data '["1.1.1.1","8.8.8.8"]'

GET/v1/asn/:asn

按编号查询自治系统。返回机构名称、国家、大洲、IP 段数量、分类类型、汇率以及地区参考数据(语言、顶级域名、首都、接壤国家)。

Parameter	In	Description
`asn`	path	不带 AS 前缀的 ASN 编号。例如 Google 为 15169。
`lang`	query	可选。用于本地化 country_name 和 continent:en(默认)、pt, fr, de, zh-TW, ko, zh-CN, ja-JP, es-ES, ar-SA, hi-IN。
`format`	query	可选。响应格式:json(默认)、csv、text、xml、yaml。

curl https://ipto.to/v1/asn/15169

GET/v1/places/:ip

对某 IP 已有的城市级位置进行反向地理编码,然后返回附近的兴趣点(餐厅、公园、学校、交通设施、知名地标)、在有数据源的地区提供的本地犯罪数据(仅限英国和美国),以及可选的按需驾车通勤时间预估。

Parameter	In	Description
`ip`	path	必填。任意有效的 IPv4 地址。暂不支持 IPv6。
`dest_lat`	query	可选。用于通勤时间预估的目的地纬度 —— 需与 dest_lon 配合使用。
`dest_lon`	query	可选。用于通勤时间预估的目的地经度 —— 需与 dest_lat 配合使用。
`dest_address`	query	可选。用于通勤时间预估的自由文本目的地地址,系统会自动进行正向地理编码。如果同时提供了 dest_lat/dest_lon,则该参数会被忽略。

Field	Type	Description
`geocode`	object\|null	country、countryCode、region、city、neighbourhood、displayName —— 如果该 IP 没有可用于地理编码的城市级位置,则为 null。
`locality.restaurants / .parks / .schools / .transit`	array	每个分类最多返回 4 条最近的结果,均包含 name 和 distanceMeters。
`locality.notable`	array	通过 Wikidata 获取的附近知名地标及简要说明。
`locality.usCrime`	object\|null	距离最近执法机构的暴力/财产犯罪总数 —— 仅限美国,且需要在部署环境中配置 FBI_CRIME_API_KEY。其他地区均为 null。
`locality.ukCrime`	object\|null	1 英里范围内的街道级事件摘要 —— 仅限英国。
`locality.caCrime`	null	始终为 null —— 目前尚未接入覆盖全加拿大的犯罪数据源(参见 docs/places.md)。
`commute`	object\|null	durationMinutes 和 distanceKm,仅在提供了目的地且 OpenRouteService 成功返回路线时才有值。否则为 null —— 绝不进行推测性计算。

curl https://ipto.to/v1/places/8.8.8.8
curl "https://ipto.to/v1/places/8.8.8.8?dest_address=Space+Needle,+Seattle"

GET/v1/country/:code

国家级汇总统计数据,以及地区参考数据(货币、汇率、语言、顶级域名、首都、接壤国家)。

Parameter	In	Description
`code`	path	ISO 3166-1 alpha-2 国家代码。例如 US、DE、JP。
`lang`	query	可选。用于本地化 country_name 和 continent:en(默认)、pt, fr, de, zh-TW, ko, zh-CN, ja-JP, es-ES, ar-SA, hi-IN。
`format`	query	可选。响应格式:json(默认)、csv、text、xml、yaml。

curl https://ipto.to/v1/country/US
# {"country_code":"US","country_name":"United States","continent":"North America","currency_code":"USD",
#  "calling_code":"+1","languages":["English"],"tld":[".us"],"capital":"Washington D.C.","borders":["CA","MX"],
#  "is_eu":false,"ip_range_count":151633,"ip_range_count_v6":30329,"asn_count":18243, ...}

GET/v1/ua

解析 User-Agent 字符串。返回浏览器、操作系统、设备类型以及机器人检测结果。默认读取调用方的 User-Agent 请求头,也可通过 ?ua= 传入任意字符串。

Parameter	In	Description
`ua`	query	可选。要解析的、经过 URL 编码的 User-Agent 字符串。默认为请求的 User-Agent 请求头。

curl "https://ipto.to/v1/ua?ua=Mozilla%2F5.0+%28iPhone%3B+CPU+iPhone+OS+17_0%29"

GET/v1/phone/:number

始终免费验证并格式化电话号码:通过自建解析器给出所属区域、号码类型,以及 E.164/国内/国际格式,不调用任何服务商。当按 IP/密钥计算的月度高级额度可用时(Free 版每月 100 次,付费版更多 — 参见价格),同一个请求还会从实时运营商查询服务返回实时运营商名称、携号转网状态,以及服务商分类的电话类型 — 参见 source 及下方字段。无论哪一层,都会返回经过本地化的 country_name,以及 lang/lang_source — 参见本地化。该高级额度用完,或上游出现任何问题时,会无缝回退到上方的免费字段;请求不会因此而失败。如需按国家划分的网络运营商参考数据,而非按号码查询,请改用 GET /v1/carriers。

Parameter	In	Description
`number`	path	必填。任意电话号码,建议使用 E.164 格式(例如 +14155552671)。开头的 + 需进行 URL 编码。
`country`	query	可选。用于解析含糊不清的国内格式号码的两位国家代码提示,例如 ?country=US。
`mode`	query	可选。当高级层可用时,?mode=current 会请求号码的实时(而非 SIM 卡签发时的)运营商。若请求回退到免费版,该参数会被忽略。

Field	Type	Description
`valid`	boolean	如果该号码符合其所属区域的有效编号规则,则为 true。
`country_code`	string\|null	该号码所属区域的 ISO 3166-1 alpha-2 代码。
`national_format`	string\|null	按照该区域自身的国内格式惯例进行格式化。
`international_format`	string\|null	带国家代码和空格的格式化结果,例如 "+1 415 555 2671"。
`e164`	string\|null	规范的 E.164 形式,例如 "+14155552671"。
`line_type`	string\|null	FIXED_LINE、MOBILE、FIXED_LINE_OR_MOBILE、VOIP、TOLL_FREE、PREMIUM_RATE 或类似值。许多编号方案(包括北美的编号方案)仅凭号码本身无法区分固定电话和移动电话。
`source`	string	如果此请求有可用的实时运营商查询额度,则为"premium";如果回退到上方的免费解析器,则为"local"。下方的 carrier、phone_type、original_carrier、is_ported、phone_region 和 country_prefix 仅在 source 为"premium"时才会填充 — 而再往下的 country_name 及 lang/lang_source 无论哪一层都会填充。
`phone_type`	string\|null	实时运营商查询服务商自己的分类之一:mobile、fixed_line、voip、toll_free、premium_rate、shared_cost、personal_number、pager、uan、voicemail 或 unknown — 不只是前四种(那只是最常见的例子)。当 source 为"local"时为 null — 与上方的 line_type(来自本地解析器,使用另一套分类)不同。
`carrier`	string\|null	号码当前所属网络运营商的名称。当 source 为"local"时为 null。
`original_carrier`	string\|null	如果号码已携号转网,则为其最初签发所属的网络运营商。当 source 为"local"或号码未携号转网时为 null。
`is_ported`	boolean\|null	如果号码已从其原运营商携出,则为 true。当 source 为"local"时为 null。
`phone_region`	string\|null	号码的所在地/州级详细信息(例如"California"),比上方的 country_code 更细。当 source 为"local"时为 null。
`country_prefix`	string\|null	号码的国家区号,不含开头的"+"(例如德国为"49")。当 source 为"local"时为 null。
`country_name`	string\|null	完整的国家显示名称(例如"Germany")— 上方的 country_code 只是 ISO alpha-2 形式("DE"),不是显示名称。与上面那些仅限高级层的字段不同,只要有 country_code(即无论哪一层)就会填充该字段,并且会像其他端点的 `country_name` 字段一样,通过 `?lang=`/`Accept-Language` 进行本地化 — 参见下方的 `lang`/`lang_source`。
`lang`	string	实际应用于上方 country_name 的语言 — 解析后的 `?lang=` 值,如果未指定或指定的语言不受支持,则为"en"。
`lang_source`	string	如果请求中带有 `?lang=`,则为"param";如果改用了 `Accept-Language`,则为"header";如果两者都没有而使用了英语,则为"default"。与 GET /v1/asn/:asn 和 GET /v1/country/:code 上同名字段含义相同。

curl "https://ipto.to/v1/phone/+14155552671"

POST/v1/phone/bulk

批量验证。所有套餐层级均可使用批量功能(这与 /v1/ip/bulk 不同)—— 对免费层级的限制是通过每层级的批次上限来实现的,而非直接返回 403。免费版:每次请求 10 个,每天 100 个。专业版:每次请求 100 个,每天 1,000 个。企业版:每次请求 1,000 个,每天 10,000 个。该额度与您的通用每日请求限制相互独立 —— 参见速率限制。

Parameter	In	Description
`body`	body (JSON)	电话号码字符串组成的 JSON 数组。

curl -X POST https://ipto.to/v1/phone/bulk \
  -H "Content-Type: application/json" \
  --data '["+14155552671","+442071838750"]'

GET/v1/carriers

参考查询:某个国家已知的移动网络运营商(MCC/MNC)—— 与任何具体电话号码无关。数据来源于社区维护的 MCC/MNC 汇编(MIT 许可,最近一次同步于 2026 年 —— 详见 docs 仓库);这是一张静态参考表,而非实时数据源,因为编号方案的分配变动并不频繁,不需要实时更新。

Parameter	In	Description
`country`	query	必填。两位国家代码,例如 ?country=US。

curl "https://ipto.to/v1/carriers?country=US"

GET/v1/email/:email

邮箱语法验证、通过 DNS-over-HTTPS 进行的实时 MX 记录检查,以及针对社区维护的黑名单(CC0 许可,每日同步)进行的一次性/临时域名检测。不会验证邮箱本身是否真实存在 —— 那需要本 API 并未执行的 SMTP 握手过程(has_mx 究竟能证明什么、不能证明什么,请参见下方的字段参考)。

Parameter	In	Description
`email`	path	必填。任意邮箱地址,需进行 URL 编码(@ 必须编码为 %40)。

Field	Type	Description
`valid_syntax`	boolean	如果该地址符合标准邮箱语法格式,则为 true。不会验证邮箱是否真实存在。
`domain`	string\|null	域名部分,已转换为小写。如果 valid_syntax 为 false,则为 null。
`has_mx`	boolean\|null	如果该域名当前至少存在一条 MX 记录,则为 true。如果语法无效,或 DNS 查询本身失败/超时,则为 null —— 请将 null 视为"未知",而非"否"。
`disposable`	boolean\|null	如果该域名匹配已知的一次性/临时邮箱服务商,则为 true。在与 has_mx 相同的条件下为 null。
`source`	"premium"\|"local"	若本次请求执行了实时检测，则为 "premium"；否则为 "local"（已达到限额，或功能未启用）— 无论哪种情况，上述字段（从 valid_syntax 到 disposable）始终会被填充。
`is_reachable`	string\|null	可选实时检测给出的总体结论："safe"（可送达）、"invalid"（被拒绝）、"risky"（不确定）或 "unknown"（无法确定 — 请重试）。若本次请求未执行实时检测，则为 null（见下方 source）。
`is_catch_all`	boolean\|null	如果该域名接收发往任意地址的邮件，意味着无法确认这个具体邮箱是否存在，则为 true。未执行实时检测时为 null。
`mailbox_full`	boolean\|null	如果实时检测发现该邮箱已满，则为 true。未执行实时检测时为 null。
`is_role_account`	boolean\|null	如果该地址看起来像角色账户（例如 support@、admin@）而非个人邮箱，则为 true。未执行实时检测时为 null。
`is_disabled`	boolean\|null	如果实时检测发现该邮箱已被明确停用，则为 true。未执行实时检测时为 null。

curl "https://ipto.to/v1/email/user%40example.com"
# When the live-verification budget allows, the same response also includes the
# source/is_reachable/is_catch_all/mailbox_full/is_role_account/is_disabled fields above:
# {"email":"user@example.com","valid_syntax":true,"domain":"example.com","has_mx":true,
#  "disposable":false,"source":"premium","is_reachable":"safe","is_catch_all":false,
#  "mailbox_full":false,"is_role_account":false,"is_disabled":false}

GET/v1/fraud-score

将您提供的 IP、邮箱、电话号码和 User-Agent 中任意组合融合为一个 0–100 的评分 —— 这是 ip-api.com、ipapi.co、ipgeolocation.io、ipify.org、ipregistry.co、ip2location.io、AbstractAPI、IPLocate.io 或 BigDataCloud 均未提供的单一融合信号(经过实际核实)。这四项输入均为可选且相互独立 —— 可传入任意子集。若省略,ip 默认使用您自己的 IP,ua 默认使用您自己的 User-Agent 请求头,与 GET /v1/ip 和 GET /v1/ua 的约定一致。未传入的信号只会在响应中缺失,而不会被计为"无风险"—— 其权重会重新分配给您实际提供的其他信号。

Parameter	In	Description
`ip`	query	可选。默认为您自己的 IP。IPv6 暂不参与评分(与本 API 其余威胁数据部分的限制相同)。
`email`	query	可选。任意邮箱地址。
`phone`	query	可选。任意电话号码。
`ua`	query	可选。默认为您自己的 User-Agent 请求头。

Field	Type	Description
`score`	integer	基于所提供信号计算得出的 0-100 加权综合评分。
`risk_tier`	string	"low"(<20)、"medium"(20-44)、"high"(45-69)或 "critical"(70 及以上)。
`signals`	object	按输入项拆分的明细 —— 只会出现您实际提供的输入对应的键:ip、email、phone、user_agent。每一项都包含其自身的分项评分,以及 GET /v1/ip/:ip、/v1/email/:email、/v1/phone/:number 和 /v1/ua 针对该输入已经返回的相同字段。

curl "https://ipto.to/v1/fraud-score?ip=1.2.3.4&email=test%40mailinator.com"

GET/v1/screenshot

在真实的无头 Chrome 实例(Cloudflare Browser Rendering,而非第三方截图服务商)中渲染指定 URL,并返回一张 PNG 图片。内部/私有目标(localhost、RFC 1918 网段、链路本地/云元数据地址)会在浏览器启动之前就被拒绝。受 Browser Rendering 自身平台级限制的约束,这些限制比本 API 其余部分严格得多 —— 在较低的 Cloudflare 套餐上,该功能很可能会在您常规的每日请求预算耗尽之前就先被限流。

Parameter	In	Description
`url`	query	必填。必须为 http 或 https。

curl "https://ipto.to/v1/screenshot?url=https://example.com" --output screenshot.png

GET/v1/language

通过本地三元组频率分析识别一段文本的语言 —— 不调用任何外部服务商,不进行 AI 模型推理,也不记录日志。输入少于 10 个字符时,language 将返回 null;少于约 30 个字符时,仍可能返回一个最佳猜测,但 reliable 会为 false。

Parameter	In	Description
`text`	query	必填。最多 5,000 个字符 —— 超长输入会被截断,而不会被拒绝。

Field	Type	Description
`language`	object\|null	最佳匹配结果的 code(ISO 639-1)、iso639_3、name 和 local_name。如果文本过短或无法识别("und"),则为 null。
`reliable`	boolean	输入过短时为 false —— 此时应将结果视为猜测,而非可信匹配。
`candidates`	array	最多 5 个次优候选语言及其相对分数,用于处理高度相近的语言组合。

curl "https://ipto.to/v1/language?text=Bonjour%2C+comment+allez-vous%3F"

GET/v1/currency/convert

在两种货币(共支持 154 种)之间转换金额,使用的正是每次 IP、ASN 和国家查询中为 currency_code/exchange_rate_usd 提供支持的同一份每日参考汇率数据 —— 在此作为独立的转换接口暴露出来,而不是嵌套在地理位置响应内部。

Parameter	In	Description
`from`	query	必填。三位 ISO 4217 货币代码。
`to`	query	必填。三位 ISO 4217 货币代码。
`amount`	query	可选。默认为 1。

Field	Type	Description
`result`	number	转换后的金额。
`rate`	number	每 1 单位 from 货币对应的 to 货币单位数。
`updated`	string	本次转换所使用的参考汇率同步时间的 ISO 时间戳。

curl "https://ipto.to/v1/currency/convert?from=USD&to=EUR&amount=100"

GET/v1/currency/rates

完整汇率表(154 种货币),可以任意受支持的货币为基准重新计算,不局限于美元。

Parameter	In	Description
`base`	query	可选。默认为 USD。

Field	Type	Description
`rates`	object	货币代码 → 相对于基准货币汇率的映射表。

curl "https://ipto.to/v1/currency/rates?base=EUR"

GET/v1/currency/history

某一货币对最长 90 天的每日参考汇率历史 —— 即货币转换工具中汇率走势图背后的数据。数据先进行一次性回填,此后由更新 GET /v1/currency/convert 的同一个定时任务每日追加。这是随时间变化的单一每日参考汇率,而非买卖价差。

Parameter	In	Description
`target`	query	必填。要绘制走势图的三位 ISO 4217 货币代码。
`base`	query	可选。默认为 USD。
`days`	query	可选。可选值为 30、60、90 之一。默认为 30。

Field	Type	Description
`series`	array	按日期升序排列的 { date, rate } 数据点数组。
`stats`	object	返回序列中的 min、avg、max 和 current。

curl "https://ipto.to/v1/currency/history?base=USD&target=EUR&days=90"

GET/v1/weather

针对地名、邮政编码、"lat,lon" 坐标对，或 lat + lon、ip，返回当前天气状况 — 传入 detail=1 后还会附带逐小时展望和多日预报。美国地点由美国国家气象局（National Weather Service）提供，其他地区由 MET Norway 提供。加上 include= 可获得完整文档，包含单位选择、最多 9 天、太阳和月亮、官方预警等 — 请参阅下方的 include 卡片。weather-lookup 工具还会在显式调用此接口之前，先在客户端自动检测调用者自身的位置。

Parameter	In	Description
`q`	query	城市名称、邮政编码或 "lat,lon"（最多 100 个字符）。也可改为传入 lat 与 lon，或 ip。三者任选其一，必填。
`detail`	query	可选。传入 "1" 会为 weather 添加 pressure_mb/visibility_km/dewpoint_c/sunrise/sunset 等字段,并附带一个 forecast 对象(hourly + daily)。默认不传。

Field	Type	Description
`condition`	string\|null	简短的文字描述。
`temp_c / temp_f`	number\|null	当前温度。
`feels_like_c`	number\|null	摄氏度体感温度。
`humidity_pct`	number\|null	相对湿度。
`wind_kmph / wind_dir`	number\|null / string\|null	风速及 16 方位罗盘风向。
`uv_index`	number\|null	紫外线指数。
`location`	object\|null	所查询地点解析得到的名称、地区、国家及经纬度 —— 而不仅仅是原始输入。
`forecast.hourly[]`	array	仅在 detail=1 时返回。未来 24 小时,每 3 小时一个数据点:hour_label、temp_c/temp_f、weather_code、chance_of_rain_pct。
`forecast.daily[]`	array	仅在 detail=1 时返回。未来 3 天展望:date、day_label、weather_code、condition、chance_of_rain_pct、max/min temp_c/temp_f。

curl "https://ipto.to/v1/weather?q=Tokyo"

curl "https://ipto.to/v1/weather?q=Tokyo&detail=1"

GET/v1/trademark/:serial

实时代理请求 USPTO 的商标状态与文件检索(TSDR)系统,按 8 位序列号查询案件状态 —— 每次调用都是直接的实时请求,而非缓存或转售的副本。案件状态数据属于美国政府作品,根据 USPTO 自身的使用条款属于公共领域,因此每个响应都会附带 source/attribution 字段,而不会悄悄缓存或转售该数据。商标标志/图片数据被刻意排除在范围之外 —— USPTO 的条款将图片许可与本接口返回的案件状态文本数据分开处理。目前尚不支持按注册号查询;USPTO 目前只公开记录了按序列号查询的方式。可在商标查询工具中试用。

Parameter	In	Description
`serial`	path	必填。必须为 8 位数字,例如 98267877。

Field	Type	Description
`source`	string	始终为 "USPTO TSDR"。
`attribution`	string	根据 USPTO 使用条款要求提供的署名行。
`data`	object	USPTO 返回的原始案件状态数据负载,直接透传而未做重新整形 —— 已于 2026-08-12 确认可正常调用。在 `data.trademarks[0]` 下:`status`(申请/注册日期、`markElement`、`descOfMark`、`tm5StatusDesc`)、`parties.ownerGroups`(按角色划分的所有人姓名/地址)、`gsList[]`(商品/服务描述及类别),以及 `prosecutionHistory[]`(完整案件时间线)。字段是否出现取决于申请状态 —— 例如处于待审状态的申请尚不会有 `usRegistrationNumber`。

curl "https://ipto.to/v1/trademark/98267877" # ANTHROPIC, Reg. No. 8296420

GET/v1/patent/:number

实时代理请求 USPTO 的专利文件包裹(Patent File Wrapper)API(开放数据门户),按 7-8 位实用新型专利号查询授权状态 —— 每次调用都是直接的实时请求,而非缓存或转售的副本。最初计划对接的数据源(PatentsView 的 Search API)已确认于 2026-03-20 关闭;本接口改为代理其实时的继任服务。专利文件包裹数据属于美国政府作品,根据 USPTO 自身的使用条款属于公共领域,因此每个响应都会附带 source/attribution 字段。范围以申请/审查程序为中心 —— 不提供引文关系图、专利家族、法律状态字段或图片,不同于 Lens.org、Espacenet 或 Google Patents 所展示的内容。数据覆盖范围从 2001 年提交的申请开始。目前尚不支持外观设计专利、植物专利和再颁专利;仅支持按已授权的实用新型专利号查询。可在专利查询工具中试用。

Parameter	In	Description
`number`	path	必填。7-8 位数字,例如 12393227。仅限已授权的实用新型专利号,不能是申请号。

Field	Type	Description
`source`	string	始终为 "USPTO Patent File Wrapper"。
`attribution`	string	根据 USPTO 使用条款要求提供的署名行。
`data`	object	USPTO 返回的原始审查记录数据负载,直接透传而未做重新整形 —— 已于 2026-08-12 针对真实专利(12393227、9935534)确认可正常调用。关键字段:`applicationMetaData`(`inventionTitle`、`filingDate`、`applicationStatusDescriptionText`、`applicationStatusDate`、`patentNumber`、`inventorBag[]`)、`recordAttorney.attorneyBag[]`、`applicationNumberText`,以及 `eventDataBag[]`(完整审查时间线)。如果该编号不存在、属于外观设计/植物/再颁专利,或早于 2001 年覆盖范围,则返回 `404`。

curl "https://ipto.to/v1/patent/12393227" # WEARABLE COMPUTING DEVICE, granted 2025

GET/v1/feeds

分页返回的 VPN、Tor 及威胁情报数据源。每页 200 条记录。每条记录包含 IP/CIDR、数据来源归属、ISP、国家以及分类类型。

Parameter	In	Description
`page`	query	从 0 开始计数的页码。默认值:0。
`type`	query	按类型过滤:VPN、Tor Exit Node、Tor Node、High-Risk Threat Intel。
`q`	query	按 IP 或 CIDR 子串过滤。

curl "https://ipto.to/v1/feeds?page=0&type=VPN"
# {"metadata":{...},"pagination":{"page":0,"page_size":200,"total":11200,"total_pages":56,"has_next":true},
#  "ranges":[{"ip":"2.26.157.0/24","type":"VPN","provider":"Datacamp Limited","isp":"Datacamp Limited","country":"GB"}, ...]}

GET/v1/feeds/stats

仅返回元数据 —— 总记录数、各数据源的记录数,以及最后同步时间。不返回具体的 IP 数据。

curl https://ipto.to/v1/feeds/stats
# {"total_tracked_ranges":34561,"last_updated":"2026-10-06T18:00:44.321Z",
#  "sources":[{"name":"X4BNet VPN Ranges","type":"VPN","count":11200}, ...]}

GET/v1/abuse

分页返回的滥用网络段。通过跨数据源相互印证给出 1-10 分的评分。风险等级:critical(8-10)、high(5-7)、medium(3-4)。

Parameter	In	Description
`page`	query	从 0 开始计数的页码。默认值:0。
`tier`	query	按风险等级过滤:critical、high、medium。
`q`	query	按网络段子串过滤。
`source`	query	可选。按来源订阅源名称筛选，须与 source_feed 返回的名称完全一致，例如 'Spamhaus DROP' 或 'IPsum Threat Intel'。

curl "https://ipto.to/v1/abuse?page=0&tier=critical&source=Spamhaus%20DROP"
# {"metadata":{...},"pagination":{"page":0,"page_size":200,"total":1640,"total_pages":9,"has_next":true},
#  "networks":[{"network_range":"1.10.16.0/20","abuse_score":10,"risk_tier":"critical","source_feed":"Spamhaus DROP"}, ...]}

GET/v1/abuse/stats

仅返回元数据 —— 网络段总数、各数据源的记录数、风险等级分布,以及最后同步时间。

curl https://ipto.to/v1/abuse/stats
# {"total_networks_tracked":18300,"last_updated":"2026-10-06T18:00:15.762Z",
#  "classification":{"ipsum_threat_intel":16660,"spamhaus_drop":1641,"spamhaus_edrop":0},
#  "sources":[{"name":"IPsum Threat Intel","count":16660}, ...]}

GET/v1/datasets/:kind

可下载的 CSV 格式导出文件,数据来自本 API 本身所依赖的开放数据集 —— 数据相同,不涉及新的授权协议。asn 和 ranges 始终可用;在给定部署上,只要该数据源尚未激活,geo-city 就会返回 503。geo-city 每次只导出单一地理数据源的原始数据行,而非合并视图 —— 可传入 ?source=primary(默认)或 ?source=secondary。

Parameter	In	Description
`kind`	path	可选值之一:asn、ranges、geo-city。
`source`	query	仅适用于 geo-city。primary(默认)或 secondary。

curl -OJ https://ipto.to/v1/datasets/asn
curl -OJ https://ipto.to/v1/datasets/ranges
curl -OJ "https://ipto.to/v1/datasets/geo-city?source=secondary"

POST/v1/keys

即时签发 API 密钥 —— 无需邮箱,无需注册。每个密钥初始均为免费层级(每天 1,000 次请求;不含批量查询)。专业版和企业版密钥可解锁更高的每日额度以及批量查询功能(每次请求最多 100 个 IP)—— 参见价格。请妥善保存该密钥 —— 事后无法再次找回。

curl -X POST https://ipto.to/v1/keys

GET/v1/keys/usage

查询某个密钥已发起的请求次数。在任意 /v1/* 请求中通过 X-API-Key 请求头或 ?api_key= 传入该密钥,即可将其计入统计。

Parameter	In	Description
`key`	query	必填。由 POST /v1/keys 返回的密钥。

curl "https://ipto.to/v1/keys/usage?key=ipto_xxxxxxxx"

GET/v1/ip/:ip/abuse

拥有某个 IP 的网络的滥用举报联系方式，来自 RDAP：RIR、网络句柄、所属 CIDR 以及滥用举报邮箱。用于确定举报应发往何处。

Parameter	In	Description
`ip`	path	IPv4 或 IPv6 地址。

curl https://ipto.to/v1/ip/8.8.8.8/abuse
# {"available":true,"failure":null,"ip":"8.8.8.8","rir":"arin","network":"GOGL","cidr":"8.8.8.0/24",
#  "contacts":[{"name":"Abuse","email":"network-abuse@google.com","handle":"ABUSE5250-ARIN"}]}

无法连接注册机构时，available 为 false，并在 failure 中给出原因。

GET/v1/asn/:asn/ranges

某个 ASN 实际宣告的 IP 段，分页返回，每个段包含国家以及托管 / 移动 / 住宅 / 机器人 / 黑名单标记。

Parameter	In	Description
`asn`	path	不含 AS 前缀的 ASN 编号，例如 15169。
`limit`	query	每页的 IP 段数。默认 50，上限 200。
`offset`	query	要跳过的 IP 段数。默认 0。

curl "https://ipto.to/v1/asn/15169/ranges?limit=1&offset=0"
# {"asn":15169,"total":153,"limit":1,"offset":0,"ranges":[{"start_ip":"8.8.4.0","end_ip":"8.8.4.255",
#  "country_code":"US","is_hosting":false,"is_mobile":false,"is_residential":false,"is_bot":false,"is_blacklisted":false}]}

GET/v1/asn/:asn/whois

ASN 的注册机构（RDAP）记录：句柄、名称、国家、分配类型、注册日期、RIR 及其联系人。

Parameter	In	Description
`asn`	path	不含 AS 前缀的 ASN 编号，例如 15169。

curl https://ipto.to/v1/asn/15169/whois
# {"asn":15169,"available":true,"reason":null,"handle":"AS15169","name":"GOOGLE","country":"US",
#  "allocationType":"...","registeredDate":"...","lastChangedDate":"...","rir":"arin","contacts":[...]}

注册机构不可达时，available 为 false 并附带 reason。

GET/v1/asn/:asn/related

可能与该 ASN 相关的其他 ASN：先列出同一注册组织，再列出相同国家和类型的。

Parameter	In	Description
`asn`	path	不含 AS 前缀的 ASN 编号，例如 15169。

curl https://ipto.to/v1/asn/15169/related
# {"asn":15169,"related":[{"asn":13949,"name":"SLIDE-INC","org":"Google LLC","country_code":"US","type":null},
#  {"asn":16550,"name":"GOOGLE-PRIVATE-CLOUD","org":"Google LLC","country_code":"US","type":"hosting"}, ...]}

GET/v1/asn/:asn/geo-sample

ASN 实际所在位置：根据其最大 IP 段的样本得到的城市级定位点，以及最常见的城市。用于 ASN 页面的分布地图。

Parameter	In	Description
`asn`	path	不含 AS 前缀的 ASN 编号，例如 15169。

curl https://ipto.to/v1/asn/15169/geo-sample
# {"asn":15169,"sampled":true,"sample_size":30,"points":[{"city":"Council Bluffs","state":"Iowa",
#  "country_code":"US","latitude":41.2591,"longitude":-95.8517}, ...],"top_cities":[...]}

这是样本，不是完整的 IP 段列表。要获取全部 IP 段，请使用 /v1/asn/:asn/ranges。

GET/v1/asn/:asn/hosted-domains

托管在某个 ASN 中的域名，通过对其部分地址样本做反向 DNS（PTR）查询得到。每条记录包含根域名、PTR 主机名和采样的 IP。

Parameter	In	Description
`asn`	path	不含 AS 前缀的 ASN 编号，例如 15169。

curl https://ipto.to/v1/asn/15169/hosted-domains
# {"asn":15169,"sampled":true,"sample_size":5,"domains":[{"root_domain":"googleusercontent.com",
#  "ptr_hostname":"0.0.214.35.bc.googleusercontent.com","sample_ip":"35.214.0.0"}, ...]}

基于采样，只能大致反映该 ASN 托管的内容，并非完整列表。针对单个 IP 请使用 /v1/ip/:ip/hosted-domains。

GET/v1/asn/:asn/relationships

ASN 的 BGP 关系：对等方、上游服务商和下游客户，并附带数量。

Parameter	In	Description
`asn`	path	不含 AS 前缀的 ASN 编号，例如 15169。

curl https://ipto.to/v1/asn/15169/relationships
# {"asn":15169,"available":true,"peers":[],"upstreams":[],"downstreams":[],
#  "peer_count":0,"upstream_count":0,"downstream_count":0}

无法连接 BGP 数据源时，available 为 false。available: true 且数组为空，表示该 ASN 没有上报任何关系。

GET/v1/ip-ranges

IPv4 地址空间目录：每个 /8 块一条，包含其 IP 段、国家和 ASN 的数量以及占比最高的国家。从这里开始，再通过 /v1/ip-ranges/:a 和 /v1/ip-ranges/:a/:b 逐级深入。

curl https://ipto.to/v1/ip-ranges
# {"blocks":[{"octet":1,"range_count":814,"country_count":15,"asn_count":182,"top_country":"KR",
#  "top_country_share":35,"top_country_name":"South Korea"}, ...],"data_version":"2026-10-06"}

GET/v1/ip-ranges/:a

某个 /8（例如 8.0.0.0/8）内的 /16 块，同样包含每块的 IP 段、国家和 ASN 数量。

Parameter	In	Description
`a`	path	第一个八位组，0-255。

curl https://ipto.to/v1/ip-ranges/8
# {"octet1":8,"cidr":"8.0.0.0/8","blocks":[{"octet":8,"range_count":...,"country_count":...,"asn_count":...,
#  "top_country":"US", ...}, ...]}

GET/v1/ip-ranges/:a/:b

某个 /16（例如 8.8.0.0/16）内已分配的 IP 段，每段附带所属 ASN，以及每块的数量。

Parameter	In	Description
`a`	path	第一个八位组，0-255。
`b`	path	第二个八位组，0-255。

curl https://ipto.to/v1/ip-ranges/8/8
# {"octet1":8,"octet2":8,"cidr":"8.8.0.0/16","blocks":[{"octet":1,"range_count":1,"country_count":1,"asn_count":1,
#  "top_country":"US", ...}, ...],"ranges_total":30,"ranges":[...]}

GET/v1/nearby

针对某个坐标的 Nearby 数据的一部分，便于客户端在每部分到达时即时渲染：逆地理编码、周边兴趣点或当地犯罪统计。

Parameter	In	Description
`lat`	query	纬度，必填。
`lon`	query	经度，必填。
`part`	query	要获取的部分：geocode、poi 或 crime。未知的值会返回 400。
`country`	query	仅 part=crime：ISO 国家代码。US 和 GB 有犯罪数据。
`region`	query	仅 part=crime：州或地区名称，例如 Utah。
`city`	query	仅 part=crime：城市名称，例如 Orem。
`lang`	query	可选。本地化地点标签（与上方本地化表中的代码相同）。

curl "https://ipto.to/v1/nearby?lat=40.2969&lon=-111.6948&part=geocode"
# {"geocode":{...reverse-geocoded place...}}

curl "https://ipto.to/v1/nearby?lat=40.2969&lon=-111.6948&part=poi"
# {"locality":{...nearby points of interest...}}

curl "https://ipto.to/v1/nearby?lat=40.2969&lon=-111.6948&part=crime&country=US&region=Utah&city=Orem"
# {"locality":{"ukCrime":null,"usCrime":{"agencyName":"Orem Police Department","agencyType":"City",
#  "distanceKm":4.4,"year":2025,"categories":[{"category":"violent-crime","label":"Violent crime","totalOffenses":129}, ...]}}}

GET/v1/commute

两点之间的驾车时间和距离。快速路径：省略 /v1/places/:ip 所做的逆地理编码和兴趣点查询。

Parameter	In	Description
`from_lat`	query	起点纬度，必填。
`from_lon`	query	起点经度，必填。
`dest_lat`	query	终点纬度。与 dest_lon 一起使用，或改为传入 dest_address。
`dest_lon`	query	终点经度。
`dest_address`	query	自由文本形式的终点，由我们为您做地理编码。在缺少 dest_lat/dest_lon 时使用。

curl "https://ipto.to/v1/commute?from_lat=40.2969&from_lon=-111.6948&dest_lat=40.7608&dest_lon=-111.8910"
# {"from":{"lat":40.2969,"lon":-111.6948},"to":{"lat":40.7608,"lon":-111.891},
#  "commute":{"durationMinutes":44,"distanceKm":63.5}}

无法解析出终点时，响应中 to 为 null、commute 为 null，并带有 reason 字符串。

GET/v1/address-lookup

以输入的街道地址而非 IP 为基准的 /v1/places/:ip 数据：地理编码、地点信息以及可选的通勤时间估算。

Parameter	In	Description
`q`	query	自由文本地址，必填。
`dest_lat`	query	可选的终点纬度，用于包含通勤时间估算（需配合 dest_lon）。
`dest_lon`	query	可选的终点经度。
`dest_address`	query	可选的自由文本终点，用于替代 dest_lat/dest_lon。
`part`	query	part=geo 只返回标签和坐标，使首屏渲染更快。
`lang`	query	可选。本地化地点标签（与上方本地化表中的代码相同）。

curl "https://ipto.to/v1/address-lookup?q=1600+Pennsylvania+Ave+NW+Washington+DC"
# {"query":"1600 Pennsylvania Ave NW Washington DC","found":true,"label":"...","latitude":38.89,
#  "longitude":-77.03,"geocode":{...},"commute":null,"locality":{...}}

curl "https://ipto.to/v1/address-lookup?q=1600+Pennsylvania+Ave+NW+Washington+DC&part=geo"
# {"query":"...","found":true,"label":"...","latitude":38.89,"longitude":-77.03}

无法对该地址进行地理编码时，found 为 false。

GET/v1/address-suggest

地址自动补全：针对不完整的地址返回若干匹配地点，可选择偏向某个位置。

Parameter	In	Description
`q`	query	不完整的地址文本，必填。
`near_lat`	query	可选纬度，结果会偏向该位置。
`near_lon`	query	可选经度，结果会偏向该位置。

curl "https://ipto.to/v1/address-suggest?q=1600+Penn&near_lat=38.9&near_lon=-77.0"
# {"suggestions":[{"label":"Penn Quarter, Ward 2, Washington, District of Columbia, United States",
#  "lat":38.8949563,"lon":-77.0224592}, ...]}

GET/v1/weather?include=

完整的天气文档，适用于地名、邮政编码、坐标或 IP。用 include 选择所需区块：current、hourly、daily、astro（太阳和月亮）、solar、indicators、alerts、marine、air_quality、nowcast，或 all。美国地点来自美国国家气象局（National Weather Service），其他地区来自 MET Norway；meta.source 会标明来源。省略 include 时返回上文所述的简单格式 { query, weather }。

Parameter	In	Description
`q / lat+lon / ip`	query	位置：q（城市、邮政编码或 "lat,lon"），或 lat 与 lon，或 ip。三者任选其一，必填。
`country`	query	可选。用于消除有歧义的 q 的 ISO 代码或国家名称，例如邮政编码 75001 搭配 country=FR。
`include`	query	此格式必填。以逗号分隔：current、hourly、daily、astro、solar、indicators、alerts、marine、air_quality、nowcast，或 all。
`units`	query	metric（默认）或 imperial。字段名随单位变化：temp_c 变为 temp_f，wind_kmph 变为 wind_mph，precip_mm 变为 precip_in。
`wind_unit`	query	kmh、ms、mph 或 kn。仅更改风速单位。
`hours`	query	要返回的逐小时条目数，1-240。默认 48。近期为每小时，之后为每 6 小时，可通过 step_hours 区分。
`days`	query	要返回的逐日条目数，1-9。默认 7。美国数据覆盖 7 天。

curl "https://ipto.to/v1/weather?lat=38.8977&lon=-77.0365&include=current,daily,alerts&days=1"
# {"query":"38.8977,-77.0365","place":{"name":"Washington","region":"DC","country":"United States","country_code":"US",
#  "lat":38.8977,"lon":-77.0365,"timezone":"America/New_York"},
#  "current":{"time":"2026-10-07T12:00-04:00","observed":false,"temp_c":18.9,"feels_like_c":18.9,"humidity_pct":52,"wind_kmph":12.9,
#   "wind_gust_kmph":24.1,"wind_dir":"S","uv_index":5.4,"condition":"Sunny","weather_code":113,"is_day":true, ...},
#  "daily":[{"date":"2026-10-07","tmax_c":22.2,"tmin_c":12.8,"precip_mm":0,"precip_prob_pct":1,"gust_max_kmph":25.9,"uv_index_max":5.4, ...}],
#  "alerts":{"available":true,"source":"NWS","official":true,"items":[]},
#  "meta":{"source":"NOAA National Weather Service","fallback_used":false,"coverage":{"precip_prob":true,"wind_gusts":true, ...},
#   "derived":["current.uv_index","current.wet_bulb", ...],"timezone":"America/New_York", ...}}

curl "https://ipto.to/v1/weather?q=Oslo&include=marine,air_quality,nowcast&units=imperial"
# Norway-only blocks come back with available: true there and available: false everywhere else

meta.coverage 说明该地点有哪些字段：降雨概率、阵风和雷暴概率仅适用于美国和北欧，其他地区为 null（不是 0）。alerts 是美国和挪威的官方预警；marine、air_quality 和 nowcast 仅覆盖挪威及邻近海域，其他地区返回 available: false。meta.derived 中的内容是 ipto.to 的估算值，indicators 是推导出的标记，并非官方预警。展示数据时请保留 meta.attribution（MET Norway 的数据采用 CC BY 4.0）。

GET/v1/weather/history

ipto.to 为已被查询过的地点自行记录的每日数据：当天预报快照中出现过的最高高温、最低低温和最大降水量。只有已被请求过的地点才有数据，并会随时间积累。

Parameter	In	Description
`q / lat+lon / ip`	query	位置：q（城市、邮政编码或 "lat,lon"），或 lat 与 lon，或 ip。三者任选其一，必填。
`days`	query	要返回的最近天数，1-400。默认 30。

curl "https://ipto.to/v1/weather/history?q=Tokyo&days=7"
# {"query":"Tokyo","place":{"name":"Tokyo","cc":"JP", ...},
#  "days":[{"date":"2026-10-06","tmax_c":24.1,"tmin_c":17.8,"precip_mm":1.2,"condition_code":296,"source":"metno","snapshots":4}, ...],
#  "note":"Daily envelope of day-0 forecast snapshots (highest high, lowest low, largest precipitation seen), not station observations."}

这些是预报快照，不是站点观测值或再分析数据，因此请勿当作实测历史使用。404 表示该地点尚未记录任何快照。

GET/v1/weather/radar/frames

可用的雷达动画帧，按时间从旧到新排列，每帧包含 Unix 时间戳和用于雷达瓦片 URL 的帧 id。

curl https://ipto.to/v1/weather/radar/frames
# {"frames":[{"time":1791316200,"id":"fdc753dba723"},{"time":1791316800,"id":"2314000028f2"}, ...]}

GET/v1/weather/radar/:frame/:z/:x/:y.png

某一帧在标准 Web 地图 z/x/y 位置的雷达地图瓦片（PNG）。通过同源代理提供，地图无需发起第三方请求即可加载。

Parameter	In	Description
`frame`	path	来自 /v1/weather/radar/frames 的帧 id（小写十六进制）。
`z`	path	缩放级别。
`x`	path	瓦片列。
`y`	path	瓦片行。

# 1. pick the latest frame id
FRAME=$(curl -s https://ipto.to/v1/weather/radar/frames | python3 -c "import sys,json;print(json.load(sys.stdin)['frames'][-1]['id'])")

# 2. fetch a tile (image/png)
curl -o radar.png "https://ipto.to/v1/weather/radar/$FRAME/5/6/12.png"

GET/v1/weather/satellite/:z/:x/:y.png

标准 Web 地图 z/x/y 位置的卫星影像地图瓦片，通过同源代理提供。

Parameter	In	Description
`z`	path	缩放级别。
`x`	path	瓦片列。
`y`	path	瓦片行。

curl -o satellite.jpg "https://ipto.to/v1/weather/satellite/5/6/12.png"
# the response body is the tile image (served as image/jpeg despite the .png path)

GET/v1/openapi/email.json

/v1/email/:email 的机器可读 OpenAPI 3.1 规范，便于 LLM 和 MCP 代理无需阅读本文档即可调用邮箱端点。

curl https://ipto.to/v1/openapi/email.json
# {"openapi":"3.1.0","info":{...},"servers":[{"url":"https://ipto.to"}],"paths":{"/v1/email/{email}":{...}}}

IP 查询字段参考

Field	Type	Description
`ip`	string	所查询的 IP 地址。
`version`	string	"v4" 或 "v6"。
`bogon`	boolean	如果该地址为私有、保留或不可路由地址,则为 true。
`bogon_type`	string\|null	当 bogon 为 true 时的原因代码:"loopback"、"private"、"link-local"、"multicast"、"reserved"、"documentation"、"unspecified"。
`asn`	integer\|null	宣告该 IP 的自治系统编号。
`asn_name`	string\|null	该 ASN 的简称(例如 "GOOGLE")。
`asn_org`	string\|null	该 ASN 注册的机构名称(例如 "Google LLC")。
`asn_type`	string\|null	ASN 分类:"hosting"、"isp"、"business"、"education"、"government"、"mobile"、"residential"。
`continent`	string\|null	完整的大洲名称(例如 "North America")。
`continent_code`	string\|null	两位大洲代码:AF AS EU NA SA OC AN。
`country_code`	string\|null	IP 实际所在国家的 ISO 3166-1 alpha-2 国家代码（例如 "US"），与城市和经纬度使用相同的地理定位数据。没有地理定位匹配时，回退为 ASN 的注册国家（asn_country_code）。国家名称、国旗、货币等字段由此派生。
`country_name`	string\|null	完整的英文国家名称(例如 "United States")。
`country_flag`	string\|null	国家 emoji 旗帜(例如 "🇺🇸")。
`is_eu`	boolean	如果该国家是欧盟成员国(共 27 个成员国),则为 true。
`city`	string\|null	城市名称。在自身查询时会填充,在显式查询中,只要 IP2Location 或 MaxMind 这两个合并地理数据源之一匹配成功也会填充 —— 请检查 geo_precision。
`state`	string\|null	行政区/次级行政区划。可用性与 city 相同。
`postal_code`	string\|null	邮政编码。在自身查询时会填充,在显式查询中,只要 IP2Location(优先)或 MaxMind 匹配成功也会填充 —— 可用性与 city 相同。
`latitude`	number\|null	十进制纬度。可用性与 city 相同。
`longitude`	number\|null	十进制经度。可用性与 city 相同。
`timezone`	string\|null	时区 —— 可用性与 city 相同。自身查询时返回 IANA 标识符(例如 "America/New_York")。在显式查询中,格式取决于匹配到的数据源:IP2Location 返回类似 "-08:00" 的 UTC 偏移字符串,MaxMind 返回 IANA 名称。
`geo_precision`	string	位置数据的精度级别:"city"、"country"(城市级查询未匹配到结果)或 "none"。
`geo_country_code`	string\|null	IP 实际所在的国家（依据地理定位数据，ISO 3166-1 alpha-2）。只要有值，就与 country_code 相同。没有地理定位匹配时为 null。
`asn_country_code`	string\|null	ASN 持有者的注册国家（ISO 3166-1 alpha-2）。对于从持有者注册国以外的国家发布路由的 CDN、VPN、托管或 anycast 网络，可能与 country_code 不同。IP 没有 ASN 记录时为 null。
`currency_code`	string\|null	该国家的 ISO 4217 货币代码(例如 "USD")。
`exchange_rate_usd`	number\|null	每 1 美元对应的本地货币单位数,数据来自每日同步、覆盖 154 种货币的参考汇率数据源。不在该范围内的货币为 null。
`calling_code`	string\|null	国家电话区号,包含 + 前缀(例如 "+1")。
`languages`	string[]	该国家的官方/公认语言,以英文列出。
`tld`	string[]	国家/地区顶级域名,例如 [".us"]。
`capital`	string\|null	首都名称。
`borders`	string[]	接壤国家的 ISO alpha-2 代码。
`is_datacenter`	boolean	如果该 IP 属于主机托管或云服务提供商,则为 true。
`is_mobile`	boolean	如果该 IP 注册给某移动运营商,则为 true。
`is_residential`	boolean	如果该 IP 被归类为住宅宽带,则为 true。
`connection_type`	string	"mobile"、"datacenter" 或 "unknown" —— 基于与 is_mobile/is_datacenter 相同的分类推导得出。刻意不尝试区分住宅与企业网络:仅凭 ASN 机构名称文本无法可靠地推导出这一点,因此无法被明确归类为移动或数据中心的 ASN 会保持 "unknown",而不会被强行猜测。
`is_bot`	boolean	如果该 IP 与已知的机器人基础设施相关联,则为 true。
`is_proxy`	boolean	如果该 IP 是已知的代理出口节点,则为 true。
`is_vpn`	boolean	如果该 IP 落在威胁数据源中已知的 VPN 服务器网段内,则为 true。
`is_tor`	boolean	如果该 IP 是已确认的 Tor 出口节点,则为 true。
`is_abuser`	boolean	如果该 IP 落在被多个滥用情报数据源标记的网络段内,则为 true。
`abuse_score`	integer\|null	当 is_abuser 为 true 时,基于跨数据源相互印证得出的 1-10 严重程度评分。否则为 null。
`risk_tier`	string\|null	"critical"(8-10)、"high"(5-7)或 "medium"(3-4)—— 由 abuse_score 推导得出。未被标记时为 null。
`threat_type`	string\|null	当 is_tor/is_vpn/is_abuser 出现重叠时,给出最具行动指导意义的单一匹配分类:"tor_exit" > "abuser" > "vpn"。如果均不匹配则为 null。
`flags`	object	与 is_* 字段对应的向后兼容对象。键包括:hosting、mobile、residential、bot、blacklisted、vpn、tor、abuser。
`meta.data_version`	string	本次查询所使用的数据集日期(YYYY-MM-DD)。自身查询时为 "cf-edge"。私有网段为 "bogon"。
`meta.cached`	boolean	如果该响应来自缓存层,则为 true。
`meta.lang`	string	此响应实际使用的语言 —— 若提供了 ?lang= 则与其一致,否则为从 Accept-Language 解析出的值,或为 "en"。
`meta.lang_source`	"param"\|"header"\|"default"	lang 是如何确定的:"param"(传入了 ?lang=)、"header"(从 Accept-Language 解析得出)、或 "default"(两者都未提供)。

输出格式

IP、ASN 和国家查询均支持 ?format=。

Format	Content-Type	Usage
`json`	`application/json`	默认格式。完整的结构化响应。
`csv`	`text/csv`	扁平的 key,value 键值对。嵌套对象会被省略。
`text`	`text/plain`	key: value 形式的文本行。每行一个字段。
`xml`	`application/xml`	完整的嵌套结构,数组会重复使用同一标签。
`yaml`	`application/x-yaml`	完整的嵌套结构。

curl "https://ipto.to/v1/ip/8.8.8.8?format=csv"
curl "https://ipto.to/v1/ip/8.8.8.8?format=xml"
curl "https://ipto.to/v1/ip/8.8.8.8?format=yaml"
curl "https://ipto.to/v1/ip/8.8.8.8?fields=ip,country_code,is_vpn,is_tor"

本地化

在 /v1/ip、/v1/asn/:asn 或 /v1/country/:code 上传入 ?lang=,可对 country_name 和 continent 进行本地化。其他所有内容(ASN 机构名称、城市名称、货币代码)都会保持原始形式 —— 这些是标识符和专有名词,而非界面文本。不受支持的语言代码会回退为英文,而不会报错。

Code	Language
`en`	English (default)
`pt`	Português
`fr`	Français
`de`	Deutsch
`zh-TW`	繁體中文
`ko`	한국어
`zh-CN`	简体中文
`ja-JP`	日本語
`es-ES`	Español
`ar-SA`	العربية
`hi-IN`	हिन्दी

curl "https://ipto.to/v1/ip/8.8.8.8?lang=de"
# "landesname":"Vereinigte Staaten","kontinent":"Nordamerika","ist_vpn":false, ...
# every key is renamed and every enum value translated -- this is the default for any non-English lang

没有 ?lang=?改为发送 Accept-Language 请求头即可 —— 相同的端点也会读取它,因此只需 curl -H "Accept-Language: es" https://ipto.to/v1/ip/8.8.8.8,无需查询字符串即可对响应进行本地化。若两者同时存在,显式的 ?lang= 始终优先。注意:shell 的 LANG/LC_ALL 环境变量(例如 LANG=es_ES.UTF-8 curl ...)只会设置 curl 自身的区域设置 —— curl 从不读取它,也不会把它转换成请求头发送,因此对响应语言没有任何影响。真正有效的只有 Accept-Language 或 ?lang= 这两种方式。

curl -H "Accept-Language: es" https://ipto.to/v1/ip/8.8.8.8
# "nombre_país":"Estados Unidos","continente":"Norteamérica" -- full key+value localization, same as ?lang=es

# equivalent, explicit form:
curl "https://ipto.to/v1/ip/8.8.8.8?lang=es"

# does NOT work -- LANG only sets curl's own locale, never a header:
LANG=es_ES.UTF-8 curl https://ipto.to/v1/ip/8.8.8.8

每个 /v1/ip、/v1/asn/:asn 与 /v1/country/:code 响应都包含 lang 和 lang_source(在 /v1/ip 中嵌套于 meta 下;在另外两者中为顶层字段),让你始终能准确知道实际应用了哪种语言、以及它是通过 "param"、"header" 还是 "default" 确定的 —— 无需从你发送的请求去猜测。

curl -s -H "Accept-Language: es" https://ipto.to/v1/ip/8.8.8.8 | python3 -m json.tool
# "meta": { "data_version": "...", "cached": true, "lang": "es-ES", "lang_source": "header" }

只要设置非英文的 lang，完整的键和值本地化就是默认行为 —— 每个字段（包括嵌套的 flags 和 meta 键）都会以目标语言重命名后返回，固定的枚举值（risk_tier、threat_type、connection_type、geo_precision、bogon_type、asn_type）也会一起翻译。需要改回旧版的英文键格式？在 /v1/ip 上加上 &localize=0 即可退出。

curl -s "https://ipto.to/v1/ip/8.8.8.8?lang=de&localize=0" | python3 -m json.tool
# opts back out to the legacy English-keys shape:
# "country_name": "Vereinigte Staaten", "geo_precision": "country", "is_vpn": false,
# "flags": { "hosting": false, "mobile": false, ... },
# "meta": { "lang": "de", "lang_source": "param", ... }

代码示例

JavaScript

const res = await fetch("https://ipto.to/v1/ip/8.8.8.8");
const data = await res.json();
console.log(data.country_name, data.asn_org, data.is_vpn);

Python

import requests
r = requests.get("https://ipto.to/v1/ip/8.8.8.8")
print(r.json()["country_name"], r.json()["is_vpn"])

PHP

$data = json_decode(file_get_contents("https://ipto.to/v1/ip/8.8.8.8"), true);
echo $data["country_name"] . " " . $data["asn_org"];

resp, _ := http.Get("https://ipto.to/v1/ip/8.8.8.8")
var data map[string]interface{}
json.NewDecoder(resp.Body).Decode(&data)

速率限制

限制按天(UTC)执行,免费层级按 IP 地址计数,专业版/企业版按密钥计数。超出限额会返回带有 Retry-After 请求头的 HTTP 429。如需用于生产环境的工作负载,请参见价格。

适用于每一个 /v1/* 接口、/mcp 服务器,以及 curl ipto.to / curl ipto.to/:ip 快捷方式。唯一的例外是 GET /ip —— 它只是简单地回显请求头,没有任何查询成本,因此完全不占用任何额度。

Tier	Requests / day	Auth
Free	1,000	无
Pro	100,000	API 密钥(请求头)
Enterprise	Unlimited	API 密钥 + 专属接口

错误代码

Status	Meaning
`200`	OK。响应中包含数据。
`202`	数据源正在同步。请在 45 秒后重试。
`400`	请求无效。IP、ASN 或国家代码不合法。
`404`	数据集中未找到该 ASN 或国家。
`503`	数据集尚不可用。可能正在进行初次数据导入。