世界时间与时区转换

正常 NEW

世界时间与时区转换服务，支持会议时段推荐与节假日查询。

协议：HTTP 格式：JSON 版本：v1.0.0日调用量：1683次

¥ 0.001 / 次

按次计费

购买次数包更优惠，低至 0.0008 元/次

100次调用包 100 次调用 ¥0.0010 /次

500次调用包 500 次调用 ¥0.00095 /次省 5%

1000次调用包 1,000 次调用 ¥0.0009 /次省 10%

推荐 5000次调用包 5,000 次调用 ¥0.00085 /次省 15%

热门 10000次调用包 10,000 次调用 ¥0.0008 /次省 20%

健康检查

服务存活探测

探测时间服务是否可用，返回服务版本、服务器当前时间与内置时区数量。无需任何参数，适合健康检查与连通性验证。

调用方式：在接口地址后拼接 ?key=您的API密钥 即可直接调用；也可改用 Authorization: Bearer 或 X-App-Key 请求头传递，避免密钥出现在访问日志中。

GET http://www.shujuyu.cn/v1/api/time/ping JSON

请求参数

参数名	类型	必填	说明
key	string	是	您的API密钥，可在个人中心获取

返回参数说明

参数名	类型	说明
code	integer	状态码，200 表示成功
msg	string	返回消息
data	object	业务数据
data.version	string	服务版本
data.time	string	服务器当前时间
data.zones	integer	内置时区数量

请求示例

返回示例

{"msg":"pong","code":200,"data":{"time":"2026-10-24 13:08:49","zones":419,"version":"1.0"}}

时区列表

返回全部时区列表

返回时区列表（共 419 个）。支持按 region 前缀、country 国家代码、q 关键字过滤；detail 为 true 时每个时区返回完整详情（日期时间、偏移、夏令时等），默认仅返回时区名。

调用方式：在接口地址后拼接 ?key=您的API密钥 即可直接调用；也可改用 Authorization: Bearer 或 X-App-Key 请求头传递，避免密钥出现在访问日志中。

GET http://www.shujuyu.cn/v1/api/time/zones JSON

请求参数

参数名	类型	必填	说明
key	string	是	您的API密钥，可在个人中心获取
region	string	否	时区名前缀过滤，如 Asia
country	string	否	ISO-3166 alpha-2 国家代码，精确匹配（会自动转大写）
q	string	否	时区名关键字，不区分大小写
detail	boolean	否	是否返回时区完整详情，默认 false 仅返回时区名

返回参数说明

参数名	类型	说明
code	integer	状态码，200 表示成功
msg	string	返回消息
data	object	业务数据
data.total	integer	过滤后总条数
data.returned	integer	本次实际返回条数
data.zones	array	时区列表
data.zones[]	object	单个时区
data.zones[].zone	string	时区名
data.zones[].country	string	国家/地区代码（仅 detail=true 时返回）
data.zones[].datetime	string	该时区当前时间（仅 detail=true 时返回）
data.zones[].iso	string	ISO 8601 时间（仅 detail=true 时返回）
data.zones[].date	string	日期（仅 detail=true 时返回）
data.zones[].time	string	时间（仅 detail=true 时返回）
data.zones[].weekday	integer	星期（1-7，仅 detail=true 时返回）
data.zones[].weekday_name	string	星期英文名（仅 detail=true 时返回）
data.zones[].offset	string	UTC 偏移（仅 detail=true 时返回）
data.zones[].offset_seconds	integer	UTC 偏移秒数（仅 detail=true 时返回）
data.zones[].dst	boolean	当前是否处于夏令时（仅 detail=true 时返回）
data.zones[].dst_info	object	夏令时信息（仅 detail=true 时返回）
data.zones[].dst_info.observes_dst	boolean	该时区是否实行夏令时
data.zones[].dst_info.enter	object	本年夏令时开始时间，未实行时为 null
data.zones[].dst_info.exit	object	本年夏令时结束时间，未实行时为 null
data.zones[].dst_info.note	string	备注，无则为 null
data.zones[].reference_utc	string	对应的 UTC 时间
data.filters	object	实际生效的过滤条件，未传时为空对象
data.filters.country	string	实际生效的国家过滤
data.filters.detail	boolean	是否返回时区完整详情
data.filters.region	string	实际生效的时区名前缀过滤
data.filters.q	string	实际生效的时区关键字过滤

请求示例

返回示例

{"msg":"success","code":200,"data":{"total":2,"zones":[{"dst":false,"iso":"2026-10-24T13:08:52+08:00","date":"2026-10-24","time":"13:08:52","zone":"Asia/Shanghai","offset":"+08:00","country":"CN","weekday":6,"datetime":"2026-10-24 13:08:52","dst_info":{"exit":null,"note":"该时区本年不实施夏令时","enter":null,"observes_dst":false},"weekday_name":"Saturday","reference_utc":"2026-10-24 05:08:52","offset_seconds":28800},{"dst":false,"iso":"2026-10-24T11:08:52+06:00","date":"2026-10-24","time":"11:08:52","zone":"Asia/Urumqi","offset":"+06:00","country":"CN","weekday":6,"datetime":"2026-10-24 11:08:52","dst_info":{"exit":null,"note":"该时区本年不实施夏令时","enter":null,"observes_dst":false},"weekday_name":"Saturday","reference_utc":"2026-10-24 05:08:52","offset_seconds":21600}],"filters":{"detail":true,"country":"CN"},"returned":2}}

时区详情

返回指定时区信息

返回指定时区的详情，包含当前（或指定时刻）的日期时间、ISO 时间、星期、UTC 偏移、夏令时状态以及本年夏令时的起止时间。

调用方式：在接口地址后拼接 ?key=您的API密钥 即可直接调用；也可改用 Authorization: Bearer 或 X-App-Key 请求头传递，避免密钥出现在访问日志中。

GET http://www.shujuyu.cn/v1/api/time/zone JSON

请求参数

参数名	类型	必填	说明
key	string	是	您的API密钥，可在个人中心获取
zone	string	是	时区名，如 Asia/Shanghai
at	string	否	参考时刻，按 UTC 解析（Y-m-d H:i:s）；不传则使用服务器当前时间

返回参数说明

参数名	类型	说明
code	integer	状态码，200 表示成功
msg	string	返回消息
data	object	业务数据
data.zone	string	时区名
data.country	string	国家/地区代码
data.datetime	string	该时区日期时间
data.iso	string	ISO 8601 时间
data.date	string	日期
data.time	string	时间
data.weekday	integer	星期（1-7）
data.weekday_name	string	星期英文名
data.offset	string	UTC 偏移
data.offset_seconds	integer	UTC 偏移秒数
data.dst	boolean	当前是否处于夏令时
data.dst_info	object	夏令时信息
data.dst_info.observes_dst	boolean	该时区是否实行夏令时
data.dst_info.enter	object	本年夏令时开始时间，未实行时为 null
data.dst_info.exit	object	本年夏令时结束时间，未实行时为 null
data.dst_info.note	string	备注，无则为 null
data.reference_utc	string	对应的 UTC 时间

请求示例

返回示例

{"msg":"success","code":200,"data":{"dst":false,"iso":"2026-08-01T20:00:00+08:00","date":"2026-08-01","time":"20:00:00","zone":"Asia/Shanghai","offset":"+08:00","country":"CN","weekday":6,"datetime":"2026-08-01 20:00:00","dst_info":{"exit":null,"note":"该时区本年不实施夏令时","enter":null,"observes_dst":false},"weekday_name":"Saturday","reference_utc":"2026-08-01 12:00:00","offset_seconds":28800}}

当前时间

返回指定时区当前时间

返回一个或多个时区的当前时间。zones 为必填项，支持逗号分隔字符串或数组，最多 10 个；个别时区无效不会导致整体失败，而是在该条记录中返回 error 字段。

调用方式：在接口地址后拼接 ?key=您的API密钥 即可直接调用；也可改用 Authorization: Bearer 或 X-App-Key 请求头传递，避免密钥出现在访问日志中。

GET http://www.shujuyu.cn/v1/api/time/now JSON

请求参数

参数名	类型	必填	说明
key	string	是	您的API密钥，可在个人中心获取
zones	string	否	时区名，多个用逗号分隔或传数组，最多 10 个；与 zone 至少提供一个，两者都不传 → 400，超过 10 个 → 400
zone	string	否	zones 的别名，用于只查询单个时区；与 zones 至少提供一个

返回参数说明

参数名	类型	说明
code	integer	状态码，200 表示成功
msg	string	返回消息
data	object	业务数据
data.reference_utc	string	本次查询的 UTC 基准时间
data.reference_iso	string	UTC 基准时间的 ISO 8601 格式
data.list	array	各时区结果列表
data.list[]	object	单个时区结果
data.list[].zone	string	时区名
data.list[].country	string	国家/地区代码
data.list[].datetime	string	该时区当前时间
data.list[].iso	string	ISO 8601 时间
data.list[].date	string	日期
data.list[].time	string	时间
data.list[].weekday	integer	星期（1-7）
data.list[].weekday_name	string	星期英文名
data.list[].offset	string	UTC 偏移
data.list[].offset_seconds	integer	UTC 偏移秒数
data.list[].dst	boolean	当前是否处于夏令时
data.list[].dst_info	object	夏令时信息
data.list[].dst_info.observes_dst	boolean	该时区是否实行夏令时
data.list[].dst_info.enter	object	本年夏令时开始时间，未实行时为 null
data.list[].dst_info.exit	object	本年夏令时结束时间，未实行时为 null
data.list[].dst_info.note	string	备注，无则为 null
data.list[].reference_utc	string	对应的 UTC 时间
data.list[].error	string	时区无效时返回该项，正常时不存在
data.list[].dst_info.enter.time	string	夏令时开始时间（本地时间）
data.list[].dst_info.enter.offset	string	夏令时开始时的 UTC 偏移
data.list[].dst_info.exit.time	string	夏令时结束时间（本地时间）
data.list[].dst_info.exit.offset	string	夏令时结束时的 UTC 偏移

请求示例

返回示例

{"msg":"success","code":200,"data":{"list":[{"dst":false,"iso":"2026-10-24T13:08:57+08:00","date":"2026-10-24","time":"13:08:57","zone":"Asia/Shanghai","offset":"+08:00","country":"CN","weekday":6,"datetime":"2026-10-24 13:08:57","dst_info":{"exit":null,"note":"该时区本年不实施夏令时","enter":null,"observes_dst":false},"weekday_name":"Saturday","reference_utc":"2026-10-24 05:08:57","offset_seconds":28800},{"dst":true,"iso":"2026-10-24T06:08:57+01:00","date":"2026-10-24","time":"06:08:57","zone":"Europe/London","offset":"+01:00","country":"GB","weekday":6,"datetime":"2026-10-24 06:08:57","dst_info":{"exit":{"time":"2026-10-25 09:00:00","offset":"+00:00"},"note":null,"enter":{"time":"2026-03-29 09:00:00","offset":"+01:00"},"observes_dst":true},"weekday_name":"Saturday","reference_utc":"2026-10-24 05:08:57","offset_seconds":3600}],"reference_iso":"2026-10-24T05:08:57+00:00","reference_utc":"2026-10-24 05:08:57"}}

时区差值

计算两个时区时间差

计算两个时区在同一 UTC 时刻的时差，返回秒/分/小时与可读标签；若任一方当前处于夏令时，会附带 DST 切换提示。

调用方式：在接口地址后拼接 ?key=您的API密钥 即可直接调用；也可改用 Authorization: Bearer 或 X-App-Key 请求头传递，避免密钥出现在访问日志中。

GET http://www.shujuyu.cn/v1/api/time/diff JSON

请求参数

参数名	类型	必填	说明
key	string	是	您的API密钥，可在个人中心获取
from	string	是	源时区
to	string	是	目标时区
at	string	否	参考时刻，按 UTC 解析（Y-m-d H:i:s）；不传则使用服务器当前时间

返回参数说明

参数名	类型	说明
code	integer	状态码，200 表示成功
msg	string	返回消息
data	object	业务数据
data.reference_utc	string	本次比较使用的 UTC 时间
data.from	object	源时区信息
data.from.zone	string	时区名
data.from.datetime	string	该时区的本地时间
data.from.offset	string	UTC 偏移
data.from.dst	boolean	是否处于夏令时
data.to	object	目标时区信息
data.to.zone	string	时区名
data.to.datetime	string	该时区的本地时间
data.to.offset	string	UTC 偏移
data.to.dst	boolean	是否处于夏令时
data.diff_seconds	integer	时差（秒）
data.diff_minutes	integer	时差（分钟）
data.diff_hours	integer	时差（小时，向下取整）
data.diff_label	string	时差的可读标签
data.note	string	提示信息，无需提示时为 null

请求示例

返回示例

{"msg":"success","code":200,"data":{"to":{"dst":true,"zone":"America/New_York","offset":"-04:00","datetime":"2026-08-01 08:00:00"},"from":{"dst":false,"zone":"Asia/Shanghai","offset":"+08:00","datetime":"2026-08-01 20:00:00"},"note":"注意: 当前一方处于夏令时, 时差可能在 DST 切换后变化","diff_hours":-12,"diff_label":"-12h","diff_minutes":-720,"diff_seconds":-43200,"reference_utc":"2026-08-01 12:00:00"}}

时间转换

跨时区时间转换

将一个时区的时间转换为一个或多个目标时区的时间。from、datetime、to 均必填，to 支持数组或逗号分隔，最多 10 个；format 为 PHP 原生日期格式串（如 Y-m-d H:i:s、Y-m-d\TH:i:sP），不传则使用默认格式；无效的目标时区会在结果项中返回 error 字段，不影响其他结果。

调用方式：在接口地址后拼接 ?key=您的API密钥 即可直接调用；也可改用 Authorization: Bearer 或 X-App-Key 请求头传递，避免密钥出现在访问日志中。

POST http://www.shujuyu.cn/v1/api/time/convert JSON

请求参数

参数名	类型	必填	说明
key	string	是	您的API密钥，可在个人中心获取
from	string	是	源时区
datetime	string	是	源时区的时间（Y-m-d H:i:s）
to	array	是	目标时区，数组或逗号分隔字符串，最多 10 个，超出直接报错（4004）
format	string	否	输出格式，须为 PHP 原生日期格式串；传预设名（如 iso8601）会得到异常结果，不传则用默认格式

返回参数说明

参数名	类型	说明
code	integer	状态码，200 表示成功
msg	string	返回消息
data	object	业务数据
data.from	object	源时间信息
data.from.zone	string	源时区
data.from.datetime	string	源时间（按 format 格式化）
data.from.iso	string	源时间 ISO 8601 格式
data.from.offset	string	UTC 偏移
data.from.dst	boolean	是否处于夏令时
data.results	array	各目标时区的转换结果
data.results[]	object	单个目标时区结果
data.results[].zone	string	目标时区
data.results[].datetime	string	转换后的时间（按 format 格式化）
data.results[].iso	string	转换后时间的 ISO 8601 格式
data.results[].offset	string	UTC 偏移
data.results[].dst	boolean	是否处于夏令时
data.results[].error	string	时区无效时返回该项，正常时不存在

请求示例

返回示例

{"msg":"success","code":200,"data":{"from":{"dst":false,"iso":"2026-08-01T12:00:00+08:00","zone":"Asia/Shanghai","offset":"+08:00","datetime":"2026-08-01 12:00:00"},"results":[{"dst":false,"iso":"2026-08-01T04:00:00+00:00","zone":"UTC","offset":"+00:00","datetime":"2026-08-01 04:00:00"},{"dst":true,"iso":"2026-08-01T00:00:00-04:00","zone":"America/New_York","offset":"-04:00","datetime":"2026-08-01 00:00:00"}]}}

会议时段推荐

推荐多人会议时段

根据多名成员的时区与工作时段推荐会议时间，按重叠度、舒适度与公平性加权评分排序。支持指定日期范围、会议时长、返回条数，以及是否避开午休与成员所在国的节假日；members 2-10 人。

调用方式：在接口地址后拼接 ?key=您的API密钥 即可直接调用；也可改用 Authorization: Bearer 或 X-App-Key 请求头传递，避免密钥出现在访问日志中。

POST http://www.shujuyu.cn/v1/api/time/meet JSON

请求参数

参数名	类型	必填	说明
key	string	是	您的API密钥，可在个人中心获取
members	array	是	参与者数组，每项含 name/zone，可选 work_start/work_end（默认 09:00-18:00），2-10 人
date_range	array	否	候选日期范围（YYYY-MM-DD），数组或逗号分隔；不传时由引擎取默认范围
duration_min	integer	否	会议时长（分钟），默认 60
top_n	integer	否	返回的候选时段数量，默认 5
avoid_lunch	boolean	否	是否避开 12:00-13:00 午休时段，默认 true
respect_holidays	boolean	否	是否跳过成员所在国的法定节假日，默认 false
reference_utc	string	否	参考 UTC 时刻，可选

返回参数说明

参数名	类型	说明
code	integer	状态码，200 表示成功
msg	string	返回消息
data	object	业务数据
data.slots	array	按评分排序的推荐时段
data.slots[]	object	单个推荐时段
data.slots[].score	number	综合评分（0-100）
data.slots[].utc_start	string	开始时（UTC）
data.slots[].utc_end	string	结束时（UTC）
data.slots[].duration_min	integer	时长（分钟）
data.slots[].in_work_count	integer	处于工作时段内的成员数
data.slots[].total_members	integer	成员总数
data.slots[].burden_count	integer	需要承担非常规时段负担的成员数
data.slots[].lunch_hit	boolean	是否命中成员午休时段
data.slots[].locals	array	各成员的本地时间
data.slots[].locals[]	object	单个成员的本地时间
data.slots[].locals[].name	string	成员名称
data.slots[].locals[].zone	string	成员时区
data.slots[].locals[].start	string	本地开始时间
data.slots[].locals[].end	string	本地结束时间
data.slots[].locals[].local_start	string	本地开始时刻（时:分）
data.slots[].locals[].local_end	string	本地结束时刻（时:分）
data.slots[].locals[].weekday	integer	星期（1-7）
data.slots[].locals[].in_work_hours	boolean	是否处于该成员工作时段
data.slots[].locals[].burden	boolean	是否为该成员带来负担
data.slots[].score_breakdown	object	评分明细
data.slots[].score_breakdown.overlap	integer	重叠度得分
data.slots[].score_breakdown.comfort	integer	舒适度得分
data.slots[].score_breakdown.fairness	integer	公平性得分
data.slots[].score_breakdown.lunch_penalty	integer	午休扣分
data.slots[].score_breakdown.weights	object	各维度权重
data.slots[].score_breakdown.weights.overlap	number	重叠度权重
data.slots[].score_breakdown.weights.comfort	number	舒适度权重
data.slots[].score_breakdown.weights.fairness	number	公平性权重
data.slots[].rank	integer	排名
data.total_candidates	integer	候选时段总数
data.returned	integer	本次实际返回条数
data.filters	object	实际生效的筛选条件
data.filters.date_range	array	实际使用的日期范围
data.filters.duration_min	integer	会议时长（分钟）
data.filters.avoid_lunch	boolean	是否避开午休
data.filters.respect_holidays	boolean	是否跳过节假日
data.filters.step_min	integer	候选时段的时间粒度（分钟）
data.filters.top_n	integer	请求的返回条数
data.reference_utc	string	参考 UTC 时刻
data.fairness_loaded	boolean	是否加载了历史会议负担数据用于公平性评分
data.skipped_holiday_days	integer	因节假日被跳过的天数
data.filters.date_range[]	string	实际使用的候选日期

请求示例

返回示例

{"msg":"success","code":200,"data":{"slots":[{"rank":1,"score":100,"locals":[{"end":"2026-08-03 17:00","name":"A","zone":"Asia/Shanghai","start":"2026-08-03 16:00","burden":false,"weekday":1,"local_end":"17:00","local_start":"16:00","in_work_hours":true},{"end":"2026-08-03 10:00","name":"B","zone":"Europe/London","start":"2026-08-03 09:00","burden":false,"weekday":1,"local_end":"10:00","local_start":"09:00","in_work_hours":true}],"utc_end":"2026-08-03 09:00:00","lunch_hit":false,"utc_start":"2026-08-03 08:00:00","burden_count":0,"duration_min":60,"in_work_count":2,"total_members":2,"score_breakdown":{"comfort":100,"overlap":100,"weights":{"comfort":0.25,"overlap":0.5,"fairness":0.25},"fairness":100,"lunch_penalty":0}},{"rank":2,"score":100,"locals":[{"end":"2026-08-03 17:30","name":"A","zone":"Asia/Shanghai","start":"2026-08-03 16:30","burden":false,"weekday":1,"local_end":"17:30","local_start":"16:30","in_work_hours":true},{"end":"2026-08-03 10:30","name":"B","zone":"Europe/London","start":"2026-08-03 09:30","burden":false,"weekday":1,"local_end":"10:30","local_start":"09:30","in_work_hours":true}],"utc_end":"2026-08-03 09:30:00","lunch_hit":false,"utc_start":"2026-08-03 08:30:00","burden_count":0,"duration_min":60,"in_work_count":2,"total_members":2,"score_breakdown":{"comfort":100,"overlap":100,"weights":{"comfort":0.25,"overlap":0.5,"fairness":0.25},"fairness":100,"lunch_penalty":0}}],"filters":{"top_n":2,"step_min":30,"date_range":["2026-08-03","2026-08-04"],"avoid_lunch":true,"duration_min":60,"respect_holidays":false},"returned":2,"reference_utc":"2026-08-03 00:00:00","fairness_loaded":false,"total_candidates":62,"skipped_holiday_days":0}}

节假日查询

查询指定国家节假日

查询指定国家的法定节假日。只传 country 时返回该国全年节假日列表（可用 year 指定年份）；同时传 country 与 date 时进入单日判断模式，返回该日期是否为节假日。

调用方式：在接口地址后拼接 ?key=您的API密钥 即可直接调用；也可改用 Authorization: Bearer 或 X-App-Key 请求头传递，避免密钥出现在访问日志中。

GET http://www.shujuyu.cn/v1/api/time/holidays JSON

请求参数

参数名	类型	必填	说明
key	string	是	您的API密钥，可在个人中心获取
country	string	是	ISO-3166 alpha-2 国家代码，如 CN/US/JP（自动转大写）
year	integer	否	年份，仅在未传 date 时生效；不传则使用当前年份
date	string	否	判断日期（Y-m-d）；传入后进入单日判断模式，忽略 year

返回参数说明

参数名	类型	说明
code	integer	状态码，200 表示成功
msg	string	返回消息
data	object	业务数据
data.country	string	国家代码（列表模式）
data.year	integer	年份（列表模式）
data.total	integer	节假日总数（列表模式）
data.list	array	节假日列表（列表模式）
data.list[]	object	单个节假日
data.list[].date	string	日期
data.list[].name	string	节日名称
data.list[].weekday	integer	星期（1-7）
data.list[].weekday_name	string	星期英文名
data.list[].country	string	国家代码
data.is_holiday	boolean	是否为节假日（单日判断模式，传 date 时返回）
data.name	string	节日名称，非节假日时为 null（单日判断模式，传 date 时返回）

请求示例

返回示例

{"msg":"success","code":200,"data":{"list":[{"date":"2026-01-01","name":"元旦","country":"CN","weekday":4,"weekday_name":"Thursday"},{"date":"2026-02-17","name":"春节初一","country":"CN","weekday":2,"weekday_name":"Tuesday"},{"date":"2026-02-18","name":"春节初二","country":"CN","weekday":3,"weekday_name":"Wednesday"}],"year":2026,"total":17,"country":"CN"}}

时间戳转换

时间戳与日期互转

时间戳与日期时间互转。传 timestamp（别名 ts）按 Unix 时间戳解析，数值大于等于 10^11 时按毫秒处理；传 date 按日期时间字符串解析；两者都不传则使用当前时间。zone 指定解析所用时区，默认 Asia/Shanghai。

调用方式：在接口地址后拼接 ?key=您的API密钥 即可直接调用；也可改用 Authorization: Bearer 或 X-App-Key 请求头传递，避免密钥出现在访问日志中。

GET http://www.shujuyu.cn/v1/api/time/timestamp JSON

请求参数

参数名	类型	必填	说明
key	string	是	您的API密钥，可在个人中心获取
timestamp	integer	否	Unix 时间戳，别名 ts；大于等于 10^11 视为毫秒；与 date 均不传时返回当前时间
date	string	否	日期时间字符串（Y-m-d H:i:s）
zone	string	否	解析所用时区，默认 Asia/Shanghai，别名 timezone

返回参数说明

参数名	类型	说明
code	integer	状态码，200 表示成功
msg	string	返回消息
data	object	业务数据
data.timestamp	integer	Unix 时间戳（秒）
data.timestamp_ms	integer	Unix 时间戳（毫秒）
data.timezone	string	解析所用时区
data.datetime	string	日期时间
data.date	string	日期
data.time	string	时间
data.iso	string	ISO 8601 时间
data.weekday	integer	星期（1-7）
data.weekday_name	string	星期中文名
data.day_of_year	integer	一年中的第几天
data.week	integer	一年中的第几周
data.offset	string	UTC 偏移
data.dst	boolean	是否处于夏令时
data.utc	object	对应的 UTC 时间
data.utc.datetime	string	UTC 日期时间
data.utc.iso	string	UTC ISO 8601 时间

请求示例

返回示例

{"msg":"success","code":200,"data":{"dst":false,"iso":"2026-08-01T12:00:00+08:00","utc":{"iso":"2026-08-01T04:00:00+00:00","datetime":"2026-08-01 04:00:00"},"date":"2026-08-01","time":"12:00:00","week":31,"offset":"+08:00","weekday":6,"datetime":"2026-08-01 12:00:00","timezone":"Asia/Shanghai","timestamp":1785556800,"day_of_year":213,"timestamp_ms":1785556800000,"weekday_name":"星期六"}}

批量时间转换

批量转换最多 10 条

批量跨时区时间转换，单次最多 10 条，超出直接报错（4004）。每项需包含 from/datetime/to，可选 format；单项失败不影响整体，失败项会返回 index、error 与 error_msg。

调用方式：在接口地址后拼接 ?key=您的API密钥 即可直接调用；也可改用 Authorization: Bearer 或 X-App-Key 请求头传递，避免密钥出现在访问日志中。

POST http://www.shujuyu.cn/v1/api/time/batch JSON

请求参数

参数名	类型	必填	说明
key	string	是	您的API密钥，可在个人中心获取
items	array	是	转换项数组，每项含 from/datetime/to（可选 format），最多 10 条，超出直接报错（4004）

返回参数说明

参数名	类型	说明
code	integer	状态码，200 表示成功
msg	string	返回消息
data	object	业务数据
data.total	integer	提交的转换项总数
data.returned	integer	本次实际返回条数
data.succeeded	integer	成功条数
data.failed	integer	失败条数
data.truncated	boolean	保留字段，当前恒为 false（超过 10 条时直接返回 4004 错误，不会截断）
data.max_limit	integer	单次允许的最大条数
data.list	array	各转换项结果
data.list[]	object	单个转换项结果
data.list[].index	integer	对应请求 items 中的下标
data.list[].from	object	源时间信息
data.list[].from.zone	string	源时区
data.list[].from.datetime	string	源时间
data.list[].from.iso	string	源时间 ISO 8601 格式
data.list[].from.offset	string	UTC 偏移
data.list[].from.dst	boolean	是否处于夏令时
data.list[].results	array	目标时区转换结果
data.list[].results[]	object	单个目标时区结果
data.list[].results[].zone	string	目标时区
data.list[].results[].datetime	string	转换后的时间
data.list[].results[].iso	string	转换后时间的 ISO 8601 格式
data.list[].results[].offset	string	UTC 偏移
data.list[].results[].dst	boolean	是否处于夏令时
data.list[].error	string	失败原因代码，成功时不存在
data.list[].error_msg	string	失败原因描述，成功时不存在

请求示例

返回示例

{"msg":"success","code":200,"data":{"list":[{"from":{"dst":false,"iso":"2026-08-01T12:00:00+08:00","zone":"Asia/Shanghai","offset":"+08:00","datetime":"2026-08-01 12:00:00"},"index":0,"results":[{"dst":false,"iso":"2026-08-01T04:00:00+00:00","zone":"UTC","offset":"+00:00","datetime":"2026-08-01 04:00:00"}]},{"from":{"dst":false,"iso":"2026-08-01T12:00:00+08:00","zone":"Asia/Shanghai","offset":"+08:00","datetime":"2026-08-01 12:00:00"},"index":1,"results":[{"dst":false,"iso":"2026-08-01T13:00:00+09:00","zone":"Asia/Tokyo","offset":"+09:00","datetime":"2026-08-01 13:00:00"}]}],"total":2,"failed":0,"returned":2,"max_limit":10,"succeeded":2,"truncated":false}}

跨时区时长

计算两个时区时刻的时间间隔

计算两个不同时区时刻之间的时间间隔，返回秒数、绝对值、方向、可读描述及年月日时分秒拆分，并检测区间内是否跨越夏令时切换。四个参数 start_datetime、start_zone、end_datetime、end_zone 均必填，可放在请求体或查询串中。

调用方式：在接口地址后拼接 ?key=您的API密钥 即可直接调用；也可改用 Authorization: Bearer 或 X-App-Key 请求头传递，避免密钥出现在访问日志中。

POST http://www.shujuyu.cn/v1/api/time/duration JSON

请求参数

参数名	类型	必填	说明
key	string	是	您的API密钥，可在个人中心获取
start_datetime	string	是	开始时间（Y-m-d H:i:s）
start_zone	string	是	开始时区
end_datetime	string	是	结束时间（Y-m-d H:i:s）
end_zone	string	是	结束时区

返回参数说明

参数名	类型	说明
code	integer	状态码，200 表示成功
msg	string	返回消息
data	object	业务数据
data.start	object	开始时刻信息
data.start.zone	string	开始时区
data.start.datetime	string	开始时间
data.start.offset	string	UTC 偏移
data.start.dst	boolean	是否处于夏令时
data.end	object	结束时刻信息
data.end.zone	string	结束时区
data.end.datetime	string	结束时间
data.end.offset	string	UTC 偏移
data.end.dst	boolean	是否处于夏令时
data.duration_seconds	integer	间隔秒数（结束时刻减开始时刻，可为负）
data.duration_abs	integer	间隔秒数的绝对值
data.direction	string	方向：+ 表示结束晚于开始，- 表示早于开始
data.human	string	可读的时间间隔描述
data.breakdown	object	按年月日时分秒拆分的间隔
data.breakdown.years	integer	年
data.breakdown.months	integer	月
data.breakdown.days	integer	日
data.breakdown.hours	integer	时
data.breakdown.minutes	integer	分
data.breakdown.seconds	integer	秒
data.dst_transition	object	夏令时切换检测结果
data.dst_transition.has_transition	boolean	区间内是否发生夏令时切换
data.dst_transition.transitions	array	切换点列表，无切换时为空数组

请求示例

返回示例

{"msg":"success","code":200,"data":{"end":{"dst":true,"zone":"America/New_York","offset":"-04:00","datetime":"2026-08-01 09:00:00"},"human":"12小时","start":{"dst":false,"zone":"Asia/Shanghai","offset":"+08:00","datetime":"2026-08-01 09:00:00"},"breakdown":{"days":0,"hours":12,"years":0,"months":0,"minutes":0,"seconds":0},"direction":"+","duration_abs":43200,"dst_transition":{"transitions":[],"has_transition":false},"duration_seconds":43200}}

团队状态看板

查看多成员在某一时刻的本地状态

给定一个 UTC 参考时刻，返回每名成员的本地时间、星期、UTC 偏移、夏令时状态与其所处状态（工作 / 午休 / 下班 / 睡眠），并汇总各状态人数。members 必填，2-10 人，每项含 name/zone，可选 work_start/work_end（默认 09:00-18:00）。

调用方式：在接口地址后拼接 ?key=您的API密钥 即可直接调用；也可改用 Authorization: Bearer 或 X-App-Key 请求头传递，避免密钥出现在访问日志中。

POST http://www.shujuyu.cn/v1/api/time/status JSON

请求参数

参数名	类型	必填	说明
key	string	是	您的API密钥，可在个人中心获取
members	array	是	成员数组，每项含 name/zone，可选 work_start/work_end（默认 09:00-18:00），非空且最多 10 人
reference_utc	string	否	参考 UTC 时刻（Y-m-d H:i:s），不传则使用服务器当前时间

返回参数说明

参数名	类型	说明
code	integer	状态码，200 表示成功
msg	string	返回消息
data	object	业务数据
data.reference_utc	string	本次查询的 UTC 基准时间
data.reference_iso	string	UTC 基准时间的 ISO 8601 格式
data.members	array	各成员状态列表
data.members[]	object	单个成员状态
data.members[].name	string	成员名称
data.members[].zone	string	成员时区
data.members[].local_time	string	本地时间
data.members[].local_time_short	string	本地时间（时:分）
data.members[].weekday	integer	星期（1-7）
data.members[].weekday_name	string	星期英文名
data.members[].offset	string	UTC 偏移
data.members[].dst	boolean	是否处于夏令时
data.members[].work_start	string	工作时段的开始时刻
data.members[].work_end	string	工作时段的结束时刻
data.members[].state	string	状态：working/lunch/off_duty/sleeping
data.members[].state_reason	string	状态判定依据
data.summary	object	各状态人数汇总
data.summary.working	integer	工作中人数
data.summary.lunch	integer	午休中人数
data.summary.off_duty	integer	下班（非睡眠）人数
data.summary.sleeping	integer	睡眠中人数
data.total	integer	成员总数

请求示例

返回示例

{"msg":"success","code":200,"data":{"total":2,"members":[{"dst":false,"name":"A","zone":"Asia/Shanghai","state":"working","offset":"+08:00","weekday":1,"work_end":"18:00","local_time":"2026-08-03 16:00:00","work_start":"09:00","state_reason":"in_work_hours","weekday_name":"Monday","local_time_short":"16:00"},{"dst":true,"name":"B","zone":"Europe/London","state":"working","offset":"+01:00","weekday":1,"work_end":"18:00","local_time":"2026-08-03 09:00:00","work_start":"09:00","state_reason":"in_work_hours","weekday_name":"Monday","local_time_short":"09:00"}],"summary":{"lunch":0,"working":2,"off_duty":0,"sleeping":0},"reference_iso":"2026-08-03T08:00:00+00:00","reference_utc":"2026-08-03 08:00:00"}}

工作时段重叠

计算多成员的工作时段重叠区间

计算多名成员在指定 UTC 日期内的工作时段重叠区间，返回重叠窗口的起止时间与总时长，以及每位成员的工作时段。members 必填，2-10 人。

调用方式：在接口地址后拼接 ?key=您的API密钥 即可直接调用；也可改用 Authorization: Bearer 或 X-App-Key 请求头传递，避免密钥出现在访问日志中。

POST http://www.shujuyu.cn/v1/api/time/overlap JSON

请求参数

参数名	类型	必填	说明
key	string	是	您的API密钥，可在个人中心获取
members	array	是	成员数组，每项含 name/zone，可选 work_start/work_end（默认 09:00-18:00），非空且最多 10 人
date_utc	string	否	UTC 日期（Y-m-d），不传则使用服务器当前 UTC 日期

返回参数说明

参数名	类型	说明
code	integer	状态码，200 表示成功
msg	string	返回消息
data	object	业务数据
data.date_utc	string	计算所使用的 UTC 日期
data.overlap_windows	array	重叠窗口列表
data.overlap_windows[]	object	单个重叠窗口
data.overlap_windows[].start_utc	string	窗口开始（UTC）
data.overlap_windows[].end_utc	string	窗口结束（UTC）
data.overlap_windows[].duration_min	integer	窗口时长（分钟）
data.overlap_minutes	integer	重叠总分钟数
data.overlap_hours	number	重叠总小时数
data.members	array	各成员的工作时段
data.members[]	object	单个成员工作时段
data.members[].name	string	成员名称
data.members[].zone	string	成员时区
data.members[].work_start	string	工作时段的开始时刻
data.members[].work_end	string	工作时段的结束时刻
data.candidate_ranges	integer	参与计算的候选时段数量

请求示例

返回示例

{"msg":"success","code":200,"data":{"members":[{"name":"A","zone":"Asia/Shanghai","work_end":"18:00","work_start":"09:00"},{"name":"B","zone":"Europe/London","work_end":"18:00","work_start":"09:00"}],"date_utc":"2026-08-03","overlap_hours":2,"overlap_minutes":120,"overlap_windows":[{"end_utc":"2026-08-03 10:00:00","start_utc":"2026-08-03 08:00:00","duration_min":120}],"candidate_ranges":6}}

确认会议时段

记录一次已确认的会议时段

确认并记录一次会议时段，返回会议标识、UTC 起止时间与各成员的本地起止时间。记录会写入会议流水，并作为公平性评分的依据。members 必填，slot_start_utc / slot_end_utc 必填，meeting_id 可选（不传时由服务端生成）。

调用方式：在接口地址后拼接 ?key=您的API密钥 即可直接调用；也可改用 Authorization: Bearer 或 X-App-Key 请求头传递，避免密钥出现在访问日志中。

POST http://www.shujuyu.cn/v1/api/time/meet-confirm JSON

请求参数

参数名	类型	必填	说明
key	string	是	您的API密钥，可在个人中心获取
members	array	是	参会成员数组，每项含 name/zone，非空
slot_start_utc	string	是	会议开始时（UTC）
slot_end_utc	string	是	会议结束时（UTC）
meeting_id	string	否	会议标识，不传时由服务端生成

返回参数说明

参数名	类型	说明
code	integer	状态码，200 表示成功
msg	string	返回消息
data	object	业务数据
data.meeting_id	string	会议标识
data.slot_start_utc	string	会议开始时（UTC）
data.slot_end_utc	string	会议结束时（UTC）
data.members	array	各成员的本地时间
data.members[]	object	单个成员的本地时间
data.members[].name	string	成员名称
data.members[].zone	string	成员时区
data.members[].local_start	string	本地开始时刻
data.members[].local_end	string	本地结束时刻
data.members[].burden	boolean	该成员是否承担非常规时段负担
data.recorded	integer	本次写入的记录条数

请求示例

返回示例

{"msg":"success","code":200,"data":{"members":[{"name":"A","zone":"Asia/Shanghai","burden":false,"local_end":"17:00:00","local_start":"16:00:00"},{"name":"B","zone":"Europe/London","burden":false,"local_end":"10:00:00","local_start":"09:00:00"}],"recorded":2,"meeting_id":"demo-20260803","slot_end_utc":"2026-08-03 09:00:00","slot_start_utc":"2026-08-03 08:00:00"}}

会议公平性统计

查询各成员的会议负担统计

返回各成员的会议负担统计（会议总数、非常规时段会议数、负担比例及最近一次会议时间），按负担会议数与会议总数降序排列。member_key 可选，格式为「成员名@时区」，不传则返回全部成员；limit 可选，默认 20，取值范围 1-20。

调用方式：在接口地址后拼接 ?key=您的API密钥 即可直接调用；也可改用 Authorization: Bearer 或 X-App-Key 请求头传递，避免密钥出现在访问日志中。

GET http://www.shujuyu.cn/v1/api/time/meet-stats JSON

请求参数

参数名	类型	必填	说明
key	string	是	您的API密钥，可在个人中心获取
member_key	string	否	成员键（成员名@时区），不传则返回全部成员
limit	integer	否	返回条数，默认 20；小于 1 或大于 20 按 20 处理

返回参数说明

参数名	类型	说明
code	integer	状态码，200 表示成功
msg	string	返回消息
data	object	业务数据
data.members	array	成员负担统计列表
data.members[]	object	单个成员统计
data.members[].member_key	string	成员键（成员名@时区）
data.members[].zone	string	成员时区
data.members[].total_meetings	integer	参与的会议总数
data.members[].burden_meetings	integer	非常规时段的会议数
data.members[].burden_rate	number	负担比例（非常规时段会议数 / 会议总数）
data.members[].last_meeting_utc	string	最近一次会议时间（UTC）
data.members[].updated_at	string	统计更新时间
data.returned	integer	本次实际返回条数
data.total_meetings_log	integer	会议流水总条数
data.total_burden_log	integer	非常规时段流水总条数
data.limit	integer	本次生效的返回条数上限

请求示例

返回示例

{"msg":"success","code":200,"data":{"limit":10,"members":[{"zone":"America/New_York","member_key":"Bob@America/New_York","updated_at":"2026-09-09 01:32:49","burden_rate":1,"total_meetings":3,"burden_meetings":3,"last_meeting_utc":"2026-08-01 09:00:00"}],"returned":1,"total_burden_log":3,"total_meetings_log":3}}

重置公平性统计

清除会议流水与负担统计

清除会议流水与成员负担统计。member_key 可选，格式为「成员名@时区」，不传则清空全部成员的数据（此时 reset_member_key 返回 *）。该操作不可撤销，请谨慎调用。

调用方式：在接口地址后拼接 ?key=您的API密钥 即可直接调用；也可改用 Authorization: Bearer 或 X-App-Key 请求头传递，避免密钥出现在访问日志中。

POST http://www.shujuyu.cn/v1/api/time/meet-reset JSON

请求参数

参数名	类型	必填	说明
key	string	是	您的API密钥，可在个人中心获取
member_key	string	否	成员键（成员名@时区），不传则清空全部成员数据

返回参数说明

参数名	类型	说明
code	integer	状态码，200 表示成功
msg	string	返回消息
data	object	业务数据
data.reset_member_key	string	被重置的成员键，全部重置时为 *

请求示例

返回示例

{"msg":"success","code":200,"data":{"reset_member_key":"Bob@America/New_York"}}

时间格式化与本地化

按预设或自定义格式输出时间

将指定时区的时间按预设或自定义格式输出，并返回本地化的星期、月份、时段等文案（支持 zh / en / ja）。zone 与 datetime 必填；format 可为预设名（iso8601 / rfc3339 / rfc2822 / human / date / time / stamp），也可传 PHP 原生日期格式串，不传则使用默认格式；locale 默认 zh。

调用方式：在接口地址后拼接 ?key=您的API密钥 即可直接调用；也可改用 Authorization: Bearer 或 X-App-Key 请求头传递，避免密钥出现在访问日志中。

POST http://www.shujuyu.cn/v1/api/time/format JSON

请求参数

参数名	类型	必填	说明
key	string	是	您的API密钥，可在个人中心获取
zone	string	是	时区名
datetime	string	是	待格式化的时间（Y-m-d H:i:s）
locale	string	否	本地化语言：zh / en / ja，默认 zh；传入其它值按 zh 处理
format	string	否	格式：预设名（iso8601/rfc3339/rfc2822/human/date/time/stamp）或 PHP 原生日期格式串，默认 human

返回参数说明

参数名	类型	说明
code	integer	状态码，200 表示成功
msg	string	返回消息
data	object	业务数据
data.zone	string	时区名
data.datetime	string	原始时间
data.iso	string	ISO 8601 时间
data.offset	string	UTC 偏移
data.dst	boolean	是否处于夏令时
data.locale	string	生效的本地化语言
data.format_preset	string	命中的预设名，使用自定义格式时为 null
data.format_used	string	实际使用的 PHP 日期格式串
data.formatted	string	格式化后的时间
data.localized	object	本地化文案
data.localized.weekday_short	string	星期简写
data.localized.weekday_long	string	星期全称
data.localized.month_name	string	月份名称
data.localized.period	string	上午 / 下午
data.localized.use_24h	boolean	是否使用 24 小时制
data.localized.human	string	自然语言描述
data.available_presets	array	可用预设名列表
data.available_locales	array	可用语言列表
data.available_presets[]	string	可用预设名
data.available_locales[]	string	可用语言代码

请求示例

返回示例

{"msg":"success","code":200,"data":{"dst":false,"iso":"2026-08-01T12:00:00+08:00","zone":"Asia/Shanghai","locale":"zh","offset":"+08:00","datetime":"2026-08-01 12:00:00","formatted":"2026-08-01 12:00:00 (CST)","localized":{"human":"星期六 2026年8月1日 12:00:00","period":"下午","use_24h":true,"month_name":"8月","weekday_long":"星期六","weekday_short":"周六"},"format_used":"Y-m-d H:i:s (T)","format_preset":"human","available_locales":["zh","en","ja"],"available_presets":["iso8601","rfc3339","rfc2822","human","date","time","stamp"]}}

产品说明

产品概述

世界时间与时区转换服务，支持会议时段推荐与节假日查询。

使用场景

数据查询：快速集成世界时间与时区转换到您的应用中

业务系统：将世界时间与时区转换数据嵌入业务流程

开发工具：通过 API 接口获取开发工具数据

数据分析：基于世界时间与时区转换数据进行分析和决策

费用计算

按次计费单价

¥0.001 / 次

每次调用接口从账户余额中扣除相应费用，VIP 用户可享折扣

扣费优先级

免费额度

次数包

余额扣费

计费方式详解

1 免费额度

· 接口每日免费额度已关闭
· VIP 用户月度免费额度：
· 个人版：每月 5000 次，本接口月上限 5000 次
· 专业版：每月 30000 次，本接口月上限 30000 次
· 企业版：每月 200000 次，本接口月上限 200000 次
· 账户如有注册/活动赠送的免费次数，会优先于接口免费额度扣减
· VIP 月度免费额度仅适用于单次售价不高于 ¥0.0800/次的接口；接口每日免费额度按接口配置执行
VIP 月度免费额度每月重置，未使用部分不累计至下月。

2 次数包

预付费购买固定调用次数，最高可省 20%（相对按次付费），用完为止。
次数包为独立计费，不与 VIP 折扣叠加。
请在有效期内使用，过期后未使用的次数不可再用。

3 余额扣费

按次从账户余额扣除费用；所有用户可享量折扣，VIP 用户额外享 VIP 折扣。
扣费公式：实际扣费 = 接口单价 × (1 - VIP 折扣比例 - 量折扣比例)，并受总折扣上限和最低利润率保护约束
VIP 折扣：个人版9折专业版8折企业版7折
量折扣：月付费调用 ≥1000 次享 2%、月付费调用 ≥10000 次享 5%、月付费调用 ≥20000 次享 10%
· 量折扣按账号当月全部接口的付费调用次数统计，达到更高档位时按更高档位计算
总折扣上限：VIP 折扣 + 量折扣合计不超过 50%
最低利润率保护：折后价不得低于成本价 × (1 + 15%)；若接口售价本身低于该保护价，则取消折扣并按售价计费
余额不足时调用将失败，请及时充值。

次数包方案

方案名称	调用次数	价格	折算单价	比按次付费节省	有效期
100次调用包	100 次	¥0.1	¥0.0010/次	-	365 天
500次调用包	500 次	¥0.475	¥0.00095/次	省5%	365 天
1000次调用包	1000 次	¥0.9	¥0.0009/次	省10%	365 天
5000次调用包	5000 次	¥4.25	¥0.00085/次	省15%	365 天
10000次调用包	10000 次	¥8	¥0.0008/次	省20%	365 天

VIP 权益对比

等级	每月免费次数	本接口月免费上限	折扣	VIP 折后单价
免费版	按接口配置	—	-	¥0.001/次
个人版	5000 次	5000 次	10%	¥0.0009/次
专业版	30000 次	30000 次	20%	¥0.0008/次
企业版推荐	200000 次	200000 次	30%	¥0.0007/次

* VIP 月度免费额度每月重置。每月免费次数为账号级 VIP 月额度，本接口月免费上限为其中对本接口的限制（接口可单独设置上限或关闭）。VIP 折扣仅适用于余额扣费方式，VIP 折后单价不含量折扣。本接口已关闭接口级月度免费额度（不影响 VIP 月度免费额度）。接口每日免费额度已关闭。

费用计算示例

* 以下示例未包含量折扣，量折扣按账号当月全部接口的付费调用量另行计算。

示例1：普通用户按次付费

调用 1000 次，费用 = 0.001 × 1000 = ¥1.00

示例2：个人版用户按次付费（仅 VIP 折扣，已考虑最低利润率保护）

调用 1000 次，折扣约 10%，费用 = 0.001 × (1 - 10%) × 1000 ≈ ¥0.90

示例3：购买「500次调用包」次数包

支付 ¥0.475，获得 500 次调用，折算单价 ¥0.00095/次

同等次数按次付费需 ¥0.50，次数包可节省 ¥0.025

错误码说明

错误码	说明	解决方案
200	请求成功	-
400000	请求参数错误	检查参数名、格式与取值
401000	认证失败	检查 Authorization: Bearer 密钥是否正确、是否过期
402000	账户余额不足	充值后重试
403000	无访问权限	确认密钥权限、接口范围与 IP 白名单是否满足要求
404001	接口或端点不存在	检查 API 与端点的请求路径
409000	请求冲突	请稍后重试
422000	参数校验失败	检查参数格式与取值
429000	请求频率或额度超限	降低调用频率，或升级套餐提升额度
500000	服务器内部错误	携带响应中的 request_id 联系技术支持
502000	服务暂时不可用	稍后重试
503000	服务暂时不可用	稍后重试
504000	请求超时	稍后重试

更新日志

暂无更新日志