公共接口文档

全部开放 API 文档，包含接口说明、请求方式、请求参数、返回示例与字段说明。

4 个接口 1 个分组
GET

获取时区列表

/common/world-clock/timezones

获取全球全部 IANA 时区元数据（约 600 个），精选城市附带中文名、国家与经纬度，含当前偏移、UTC 分组与夏令时标记。

2026-09-14 21:29:15

接口说明

获取全球全部 IANA 时区元数据（约 600 个），供世界时钟页面渲染时区表格与搜索使用。精选城市（约 140 个主要城市）额外附带中文名、国家/地区与经纬度信息，可用于地图打点。时区偏移与夏令时标记为服务器实时计算结果。

返回示例 

{
  "code": 200,
  "message": "操作成功",
  "data": [
    {
      "zoneId": "Asia/Shanghai",
      "city": "北京",
      "country": "中国",
      "lat": 39.9,
      "lon": 116.41,
      "representative": true,
      "utcOffset": "+08:00",
      "offsetSeconds": 28800,
      "group": "UTC+08:00",
      "isDst": false
    },
    {
      "zoneId": "America/New_York",
      "city": "纽约",
      "country": "美国",
      "lat": 40.71,
      "lon": -74.01,
      "representative": true,
      "utcOffset": "-04:00",
      "offsetSeconds": -14400,
      "group": "UTC-04:00",
      "isDst": true
    }
  ]
}

返回字段说明

字段名 类型 说明
code number 状态码，200 表示成功
zoneId string IANA 时区 ID，如 Asia/Shanghai
message string 提示信息
city string 精选城市中文名，非精选时区为 null
data array 时区列表
country string 国家/地区，非精选时区为 null
lat number 纬度（地图打点用），非精选时区为 null
lon number 经度（地图打点用），非精选时区为 null
representative boolean 是否为精选城市
utcOffset string 当前 UTC 偏移（已含夏令时），如 +08:00
offsetSeconds number 偏移秒数
group string 偏移分组，如 UTC+08:00
isDst boolean 当前是否处于夏令时

更新日志

2026-08-08：新增 UTC 分组与夏令时标记字段； 2026-08-07：接口首次发布，支持约 600 个 IANA 时区。
GET

获取指定时区当前时间

/common/world-clock/now

获取指定 IANA 时区的当前时间（默认北京时间），返回时间戳、公历、农历、星期、时分秒及未来 32 天日历；默认时区与旧 /api/public/time 接口完全兼容。

2026-09-14 21:29:15

接口说明

获取指定时区（IANA 时区 ID）的当前时间，返回服务器时间戳及该时区的公历、农历、星期、时分秒格式化结果。缺省时区为 Asia/Shanghai（北京时间，与服务器时间一致），服务器时间即北京时间的换算基准。 兼容说明：本接口在缺省时区（Asia/Shanghai）下返回结构与原 GET /api/public/time 完全一致（含 timestamp、secondsOfDay、calendarDays 等全部字段），原调用方仅需替换请求路径即可无缝迁移，无需修改任何解析逻辑；扩展字段不影响老调用方。

请求参数

参数名 类型 必填 默认值 说明
timezone string 否 Asia/Shanghai IANA 时区 ID，如 America/New_York、Europe/London

返回示例 

{
  "code": 200,
  "message": "操作成功",
  "data": {
    "timestamp": 1754544000000,
    "secondsOfDay": 52200,
    "year": 2026,
    "date": "2026年08月07日",
    "lunar": "六月廿五",
    "weekday": "星期五",
    "time": "14:30:00",
    "datetime": "2026年08月07日 六月廿五 星期五 14:30:00",
    "calendarDays": [
      { "year": 2026, "date": "2026年08月07日", "lunar": "六月廿五", "weekday": "星期五" }
    ],
    "timezone": "Asia/Shanghai",
    "zoneCity": "北京",
    "utcOffset": "+08:00",
    "offsetSeconds": 28800,
    "isDst": false,
    "isDay": true,
    "dateDiff": 0,
    "diffFromBeijingMinutes": 0,
    "diffFromBeijingText": "与北京时间相同"
  }
}

返回字段说明

字段名 类型 说明
code number 状态码，200 表示成功
timestamp number 服务器毫秒时间戳（北京时间基准）
message string 提示信息
secondsOfDay number 当地当日已过秒数
data object 时区时间数据
year number 公历年份
date string 日期（yyyy年MM月dd日）
lunar string 农历（如：六月廿五）
weekday string 星期（如：星期五）
time string 当地时分秒（HH:mm:ss）
datetime string 「日期 农历 星期 时间」拼接串
calendarDays array 未来 32 天日历（year/date/lunar/weekday），供前端跨天查农历
timezone string 实际生效的 IANA 时区 ID
zoneCity string 精选城市中文名（非精选为时区 ID）
utcOffset string 当地当前 UTC 偏移（已含夏令时）
offsetSeconds number 偏移秒数
isDst boolean 当地当前是否夏令时
isDay boolean 当地当前是否白天（6:00~18:00 粗略判断）
dateDiff number 相对北京日期差：0 同日 / 1 已进入次日 / -1 仍在前一天
diffFromBeijingMinutes number 相对北京时差（分钟，正数快于北京）
diffFromBeijingText string 时差描述文本

更新日志

2026-08-08：新增 isDay、dateDiff、diffFromBeijingMinutes 等字段； 2026-08-07：接口首次发布，兼容旧 /api/public/time 接口。
GET

获取世界全部城市时间

/common/world-clock/all

一次请求返回全球约 140 个精选城市的当前时间一览，含服务器基准时间、各城市当地时间、相对北京时差、昼夜状态、日期差与农历，支持按 zoneIds 过滤。

2026-09-14 21:29:16

接口说明

一次请求返回全球主要城市（约 140 个精选城市）当前时间一览：服务器基准时间（北京时间）、各城市当地时间、相对北京时差、昼夜状态、日期差与农历，是世界时钟页面（www /world-clock.html）首屏数据源。支持 zoneIds 参数过滤，只返回关注的时区。

请求参数

参数名 类型 必填 默认值 说明
zoneIds string 否 全部精选城市 逗号分隔的时区 ID 列表，如 Asia/Tokyo,America/New_York

返回示例 

{
  "code": 200,
  "message": "操作成功",
  "data": {
    "server": {
      "timezone": "Asia/Shanghai",
      "city": "北京",
      "utcOffset": "+08:00",
      "offsetSeconds": 28800,
      "timestamp": 1754544000000,
      "secondsOfDay": 52200,
      "time": "14:30:00",
      "date": "2026年08月07日",
      "weekday": "星期五",
      "isDay": true
    },
    "zones": [
      {
        "zoneId": "Asia/Tokyo",
        "city": "东京",
        "country": "日本",
        "lat": 35.68,
        "lon": 139.69,
        "utcOffset": "+09:00",
        "offsetSeconds": 32400,
        "isDst": false,
        "isDay": true,
        "dateDiff": 0,
        "diffFromBeijingMinutes": 60,
        "diffFromBeijingText": "比北京时间快 1 小时",
        "time": "15:30:00",
        "date": "2026年08月07日",
        "weekday": "星期五",
        "secondsOfDay": 55800,
        "lunar": "六月廿五"
      },
      {
        "zoneId": "America/New_York",
        "city": "纽约",
        "country": "美国",
        "utcOffset": "-04:00",
        "offsetSeconds": -14400,
        "isDst": true,
        "isDay": false,
        "dateDiff": 0,
        "diffFromBeijingMinutes": -720,
        "diffFromBeijingText": "比北京时间慢 12 小时",
        "time": "02:30:00",
        "date": "2026年08月07日",
        "weekday": "星期五",
        "secondsOfDay": 9000,
        "lunar": "六月廿五"
      }
    ],
    "total": 80
  }
}

返回字段说明

字段名 类型 说明
code number 状态码，200 表示成功
server object 服务器基准时间（北京时间）
timezone string 基准时区 ID（Asia/Shanghai）
zoneId string IANA 时区 ID
message string 提示信息
city string 基准城市名（北京）
zones array 各城市当前时间
city string 城市中文名
data object 城市时间数据
utcOffset string 基准 UTC 偏移
country string 国家地区
total number 返回城市总数
offsetSeconds number 基准偏移秒数
lat number 纬度
timestamp number 服务器毫秒时间戳
lon number 经度
secondsOfDay number 北京当日已过秒数
utcOffset string 当地当前 UTC 偏移
time string 北京时分秒
offsetSeconds number 当地偏移秒数
date string 北京日期
isDst boolean 当地是否夏令时
weekday string 北京星期
isDay boolean 当地是否白天
isDay boolean 北京当前是否白天
dateDiff number 相对北京日期差
diffFromBeijingMinutes number 相对北京时差（分钟）
diffFromBeijingText string 时差描述文本
time string 当地时分秒
date string 当地日期
weekday string 当地星期
secondsOfDay number 当地当日已过秒数
lunar string 当地农历

更新日志

2026-08-08：新增 isDay、dateDiff、lunar 等字段； 2026-08-07：接口首次发布，支持 zoneIds 过滤。
GET

时区时间转换

/common/world-clock/convert

将指定时刻从一个时区转换到另一个时区，返回两地的当地时间与精确时差；时刻缺省时取服务器当前时间（北京时间）。

2026-09-14 21:29:16

接口说明

将指定时刻从一个时区转换到另一个时区，返回两地的当地时间、星期与时差。时刻缺省时取服务器当前时间（北京时间）。时差按双方在转换时刻的实际偏移计算，已自动包含夏令时影响。

请求参数

参数名 类型 必填 默认值 说明
time string 否 服务器当前时间 时刻，格式 yyyy-MM-dd HH:mm:ss
from string 否 Asia/Shanghai 来源时区 ID
to string 否 Asia/Shanghai 目标时区 ID

返回示例 

{
  "code": 200,
  "message": "操作成功",
  "data": {
    "time": "2026-08-07 14:30:00",
    "from": {
      "timezone": "Asia/Shanghai",
      "city": "北京",
      "utcOffset": "+08:00",
      "time": "2026-08-07 14:30:00",
      "date": "2026年08月07日",
      "weekday": "星期五"
    },
    "to": {
      "timezone": "America/New_York",
      "city": "纽约",
      "utcOffset": "-04:00",
      "time": "2026-08-07 02:30:00",
      "date": "2026年08月07日",
      "weekday": "星期五"
    },
    "diffMinutes": -720,
    "diffText": "比北京时间慢 12 小时"
  }
}

返回字段说明

字段名 类型 说明
code number 状态码，200 表示成功
time string 入参时刻（缺省时为 null）
timezone string 来源时区 ID
timezone string 目标时区 ID
message string 提示信息
from object 来源时区信息
city string 来源城市名
city string 目标城市名
data object 转换结果数据
utcOffset string 来源 UTC 偏移
to object 目标时区信息
utcOffset string 目标 UTC 偏移
time string 来源当地时间
time string 目标当地时间
diffMinutes number 目标相对来源的时差（分钟，正数快于来源）
date string 来源当地日期
date string 目标当地日期
diffText string 相对北京时间的时差描述文本
weekday string 来源当地星期
weekday string 目标当地星期

更新日志

2026-08-08：新增 diffText 字段，提供更友好的时差描述； 2026-08-07：接口首次发布，支持跨时区时间转换。