timezone.io — IP 风险与地理位置 API。查询任意时区或 IP 的当前时间、UTC 偏移和夏令时(DST),同时提供缩写、国家、城市、坐标反查、时间转换 10 个端点;官方兼容已停运的 WorldTimeAPI,客户端只需换一行域名(Base URL 从 worldtimeapi.org 改为 api.timezone.io/v1)即可继续运行,无需 API Key。免费、无需密钥或注册,每 IP 每分钟 60 次。
📌 上手前要看的 3 个细节
这些不是"更正",是上手前值得先了解的补充细节。
Base URL 统一走 v1 版本:
https://api.timezone.io/v1是全部端点根路径,所有请求 HTTPS 返回 JSON;兼容 WorldTimeAPI 模式下只需改 hostname,路径(如/api/timezone/Europe/Paris、/api/ip)保留原样即可。免费无 Key 限制 60次/分钟/出口 IP:速率限制按 IP 统计(不是用户配额),公司/校园/代理共用出口容易互相挤;后端直连建议申请免费 API Key(官方 Get API key 入口),拿到独立配额与更高限额、并解锁用量看板与邮件告警。
DST 切换有"fold/gap"标注:夏令时跨零点/跨冬令时切换时返回
dst_from/dst_until/dst_offset/next_transition字段明确标注"时钟向前跳过"(gap,3月凌晨少1小时)和"时钟倒转"(fold,11月凌晨重复1小时)两个歧义点,避免排程类业务踩坑。
🎁 两个隐藏福利
坐标反查 + 城市日出日落:除了时区名和IP,还支持
/lookup?lat=...&lng=...经纬度反查时区(海上也覆盖),以及/cities/{slug}返回主要城市的日出日落、昼长,做日出触发/日照排程类应用白送数据;OpenAPI 规范 + Try-it 沙盒:文档内置 OpenAPI 3 Schema 和在线 Try-it 按钮,可以直接在浏览器里试完再复制代码,不用 Postman;同时支持
/abbreviations/{code}解码 EST/CET/JST 等缩写(含对应 DST 缩写 EDT/CEST/JST-DST 与覆盖城市数)。
💰 免费额度一览(timezone.io Free 档)
项目 | Free(无 Key) |
|---|---|
费用 | $0 永久免费 |
密钥/注册 | 无需密钥、无需注册 |
速率限制 | 每出口 IP 每分钟 60 次(即 1 次/秒) |
数据来源 | IANA tzdb2026e(2026年9月复核)实时计算 |
返回格式 | JSON(兼容 WorldTimeAPI 的 JSON/TXT 双格式) |
时区端点 | ✅ 全量 IANA 时区列表 |
时区详情 | ✅ 当前时间/偏移/DST状态/下一次切换 |
缩写 | ✅ EST/CET/JST等,含DST对应名与成员城市数 |
国家 | ✅ 默认时区/DST规则/属地依赖 |
城市 | ✅ 主要城市+日出日落+昼长 |
时间转换 | ✅ 1次最多转10个目标时区,标注fold/gap |
坐标反查 | ✅ 经纬度→时区(陆地/海上全覆盖) |
IP 反查 | ✅ 从请求IP自动定位时区 |
协议 | HTTPS,CORS 就绪(浏览器端直接 fetch) |
SLA / 工单 | Community;Key 用户享邮件告警 |
商用授权 | ✅ 免费档允许商用 |
免费档核心字段全部给齐:
datetime/utc_datetime/utc_offset/timezone/abbreviation/day_of_week/day_of_year/week_number/dst/dst_from/dst_until/dst_offset/unixtime/raw_offset,与 WorldTimeAPI 字段 100% 对齐。
🌟 免费档的 6 个核心能力
10个端点全给:时区列表/详情、缩写解码、国家、城市(含日出日落)、时间转换(1→10)、经纬度反查、IP反查——覆盖 99% 时间场景。
WorldTimeAPI 零成本迁移:已停运的 worldtimeapi.org 一键兼容,换 hostname 即可,字段语义 100% 对齐(包括
unixtime/raw_offset/dst/abbreviation这些老项目里常用的字段)。IANA tzdb2026e 实时计算:后端跟着 IANA 数据库实时更新(含2026年新的时区变动,如哈萨克斯坦统一时区、墨西哥部分州取消夏令时),返回的不是缓存快照,不会有"夏令时切换后偏移还错"的坑。
DST 歧义明确标注:
next_transition直接告诉你下一次切换时间;convert 端点遇到 gap/fold 会返回ambiguity: "gap"|"fold"标识,排程类代码可以自动处理。CORS 直连浏览器:响应头默认开启 CORS,前端/小程序/插件/Chrome 扩展直接 fetch,不用自己搭代理。
OpenAPI + 在线 Try-it:文档里直接试跑、直接复制 cURL/JS/Python 代码。
⚠️ 3 个避坑提示
不要在生产依赖 IP 反查做精准定位:
/ip端点基于请求 IP 推断时区,VPN/代理/公司出口/移动NAT会偏;需要城市级精度请让用户选时区或上传经纬度走/lookup。60次/分钟按出口 IP 计算:后端服务器/容器/CI 共用 IP 会共享限额,QPS>1 请申请免费 API Key(独立配额+用量看板+邮件告警)。
转换端点跨 DST 边界要检查 ambiguity:春秋两季切换那一天(北美3月第二个周日、11月第一个周日,欧洲3月最后一个周日、10月最后一个周日)的本地时间可能不存在或重复,记得检查返回的
ambiguity字段,别默认它一定能转。
🎯 适合 / 不适合人群
✅ 适合:
老项目从 worldtimeapi.org 紧急迁移,改一行域名就行
前端/小程序/插件做"用户当地时间"显示,不想引 moment-timezone 大文件
后端做定时任务/会议排程/消息定时发送,需要可信 UTC 偏移和 DST 切换预告
IoT/ESP32/嵌入式设备,只需要一个稳定 NTP 之外的时间 JSON 接口
日出/日落触发类应用(城市端点直接给 sunrise/sunset/daylight 秒数)
❌ 不适合:
需要高精度历史 DST 回查(1970年前)或自定义日历
月调用量超过百万级(建议走付费 Key 或自托管 IANA tz + date-fns/zoneinfo)
城市 IP 级定位到区县级(IP反查只能到 IANA 时区级别,不是地理 IP)
需要 SLA/工单/专属节点/企业合同
🚀 4 步上手
Step 1 — 查某时区当前时间
# 兼容模式:换 hostname 即可,路径保持 WorldTimeAPI 原样
curl https://api.timezone.io/v1/api/timezone/Asia/Shanghai
# v1 原生路径
curl https://api.timezone.io/v1/timezones/Asia/Shanghai
返回示例(字段与 WorldTimeAPI 对齐):
{
"abbreviation": "CST",
"client_ip": "203.0.113.42",
"datetime": "2026-11-18T10:00:00.000000+08:00",
"day_of_week": 3,
"day_of_year": 322,
"dst": false,
"dst_from": null,
"dst_offset": 0,
"dst_until": null,
"raw_offset": 28800,
"timezone": "Asia/Shanghai",
"unixtime": 1794861600,
"utc_datetime": "2026-11-18T02:00:00.000000+00:00",
"utc_offset": "+08:00",
"week_number": 47
}
Step 2 — IP 自动定位时区
# 服务器从请求IP自动推断,客户端/后端都能用
curl https://api.timezone.io/v1/api/ip
Step 3 — 时间转换(含 DST 歧义标注)
# 把"纽约时间2026-11-18 10:00"同时转到东京/上海/伦敦
curl "https://api.timezone.io/v1/convert?from=America/New_York&to=Asia/Tokyo&to=Asia/Shanghai&to=Europe/London&datetime=2026-11-18T10:00:00"
Step 4 — 前端 CORS 直连
// 浏览器直接 fetch,无需代理、无需 Key
const res = await fetch('https://api.timezone.io/v1/api/ip');
const data = await res.json();
console.log(`你的当地时间: ${data.datetime}(${data.timezone},DST=${data.dst})`);
老项目从 worldtimeapi.org 迁移:
- const BASE = 'https://worldtimeapi.org';
+ const BASE = 'https://api.timezone.io/v1';
// 其余 /api/timezone/...、/api/ip 路径、返回字段零改动
📊 8 款免费时间 API 横向对比(2026-11)
产品 | 免费额度 | Key | IP反查 | DST预告 | 转换 | 坐标反查 | 日出日落 | 兼容WTAPI |
|---|---|---|---|---|---|---|---|---|
timezone.io | 60次/分钟/IP | 无需 | ✅ | ✅ next_transition | ✅ 1→10 | ✅ | ✅ | ✅ 换域名 |
timeapi.io | 免费层(额度有限) | 需注册Key | ✅ | ✅ | ✅ | ❌ | ❌ | 路径不同 |
timeapi.world(BSL) | 20000次/月 | 无需 | ✅ | ✅ | ✅ | ✅ | ❌ | ✅ 完全兼容 |
Abstract Time API | 免费层 20000次/月 | 需Key | ✅ | ✅ | ✅ | ✅ | ❌ | ❌ |
Google Time Zone API | $5/1000次,免费额度有限 | 需Key+GCP | ❌ | ✅ | ❌ | ✅ | ❌ | ❌ |
TimeZoneDB | 免费层注册后10req/s | 需注册Key | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ |
WorldTimeAPI | 已停运 | — | — | — | — | — | — | — |
IPgeolocation.io | 1000次/天免费 | 需Key | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ |
💳 付费档位参考
Free(无Key):$0/月,60次/分钟/IP,10个端点全开,社区支持,商用允许
Free Key(注册):$0/月,独立配额+用量看板+邮件告警(官网 Get API key 入口,具体额度以官方页为准)
Pro / Business:更高 RPS、SLA、专属支持、团队席位(官网 Pricing 页公布)
💬 文末互动
你之前踩过 WorldTimeAPI 停服的坑吗?迁移到了哪家替代?
排程类业务遇到过 DST 切换导致的"重复执行/少执行1小时"bug吗?
需要日出日落/经纬度反查的同学,对哪个端点最感兴趣?
文中额度与规则以官方文档为准(核实时点:2026 年 11 月,IANA tzdb2026e)。timezone.io 是 WorldTimeAPI 官方文档点名的 drop-in 替代,60次/分钟/IP 免费够用中小项目,老项目改一行 BASE URL 即可救急。