timezone.io-查询任意时区或 IP 的当前时间、UTC 偏移和夏令时,兼容WorldTimeAPI

壹贰线报 · 官方文档核实(核实时点:2026年11月)

timezone.io — IP 风险与地理位置 API。查询任意时区或 IP 的当前时间、UTC 偏移和夏令时(DST),同时提供缩写、国家、城市、坐标反查、时间转换 10 个端点;官方兼容已停运的 WorldTimeAPI,客户端只需换一行域名(Base URL 从 worldtimeapi.org 改为 api.timezone.io/v1)即可继续运行,无需 API Key。免费、无需密钥或注册,每 IP 每分钟 60 次。


📌 上手前要看的 3 个细节

这些不是"更正",是上手前值得先了解的补充细节。

  1. Base URL 统一走 v1 版本:https://api.timezone.io/v1 是全部端点根路径,所有请求 HTTPS 返回 JSON;兼容 WorldTimeAPI 模式下只需改 hostname,路径(如 /api/timezone/Europe/Paris、/api/ip)保留原样即可。

  2. 免费无 Key 限制 60次/分钟/出口 IP:速率限制按 IP 统计(不是用户配额),公司/校园/代理共用出口容易互相挤;后端直连建议申请免费 API Key(官方 Get API key 入口),拿到独立配额与更高限额、并解锁用量看板与邮件告警。

  3. DST 切换有"fold/gap"标注:夏令时跨零点/跨冬令时切换时返回 dst_from/dst_until/dst_offset/next_transition 字段明确标注"时钟向前跳过"(gap,3月凌晨少1小时)和"时钟倒转"(fold,11月凌晨重复1小时)两个歧义点,避免排程类业务踩坑。

🎁 两个隐藏福利

  1. 坐标反查 + 城市日出日落:除了时区名和IP,还支持 /lookup?lat=...&lng=... 经纬度反查时区(海上也覆盖),以及 /cities/{slug} 返回主要城市的日出日落、昼长,做日出触发/日照排程类应用白送数据;

  2. 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 双格式)

时区端点 /timezones

✅ 全量 IANA 时区列表

时区详情 /timezones/{iana}

✅ 当前时间/偏移/DST状态/下一次切换

缩写 /abbreviations/abbreviations/{code}

✅ EST/CET/JST等,含DST对应名与成员城市数

国家 /countries/countries/{iso2}

✅ 默认时区/DST规则/属地依赖

城市 /cities/cities/{slug}

✅ 主要城市+日出日落+昼长

时间转换 /convert

✅ 1次最多转10个目标时区,标注fold/gap

坐标反查 /lookup

✅ 经纬度→时区(陆地/海上全覆盖)

IP 反查 /ip(兼容WorldTimeAPI /api/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 即可救急。


版权声明

本文仅代表作者观点,不代表本站立场。
本文系作者授权发表,未经许可,不得转载。