查看全局 API 说明（请求/响应头、通用 JSON 格式）

时区与时间格式 API

提供当前时间、时区转换与时间戳互转能力

Base URL https://www.resapi.cn/v1/time

简介

用于多时区系统、日志展示、报表时间统一等场景。支持 IANA 时区（如 Asia/Shanghai、UTC、America/New_York）。

GET /v1/time/now

获取指定时区当前时间。

查询参数

名称	类型	必填	说明	示例
tz	string	否	IANA 时区，默认 `Asia/Shanghai`	UTC

响应字段

字段	说明
timezone	时区名
datetime	`YYYY-MM-DD HH:mm:ss`
date	`YYYY-MM-DD`
rfc3339	RFC3339 格式时间
unix / unix_millis	秒/毫秒时间戳
offset	时区偏移（如 `+08:00`）
weekday	英文星期名
iso_week	ISO 周（如 `2026-W23`）

GET /v1/time/convert

将一个时间从源时区转换到目标时区。

查询参数

名称	类型	必填	说明	示例
datetime	string	是	时间字符串	`2026-06-02 21:30:00`
from_tz	string	条件必填	当 `datetime` 不带时区时必填	`Asia/Shanghai`
to_tz	string	是	目标时区	`UTC`

支持的 datetime 格式：

YYYY-MM-DD HH:mm:ss
YYYY-MM-DD HH:mm
YYYY-MM-DD
RFC3339（如 2026-06-02T21:30:00+08:00，此时可不传 from_tz）

GET /v1/time/timestamp

时间戳与日期时间互转。

查询参数

名称	类型	必填	说明	示例
timestamp	string	二选一	10 位秒或 13 位毫秒时间戳	`1717335000`
datetime	string	二选一	时间字符串（同 convert 支持格式）	`2026-06-02 21:30:00`
tz	string	否	时区，默认 `Asia/Shanghai`	`UTC`

timestamp 与 datetime 不能同时传。

GET /v1/time/timezones

返回可用时区列表（含中文名称），用于前端下拉选择或搜索。

查询参数

名称	类型	必填	说明	示例
region	string	否	区域过滤：`utc`/`asia`/`europe`/`africa`/`north_america`/`south_america`/`oceania`	`asia`
q	string	否	模糊搜索（匹配时区值与中文名）	`中国`

响应字段

字段	说明
value	IANA 时区值（传给 `tz`）
label	中文展示名称
region	区域标识

IANA 时区参考（`tz` 参数）

/v1/time/* 的 tz 使用 IANA 时区名（建议直接复制）。示例：UTC、Asia/Shanghai、America/New_York。

注：不支持 GMT+8 / UTC+8 这种写法；如果你输入的时区无法被识别，接口会返回 invalid_params。

常用时区（按区域，含中文名称）

UTC

UTC（协调世界时）

亚洲

Asia/Shanghai（中国大陆，北京/上海/广州等）
Asia/Hong_Kong（中国香港）
Asia/Macau（中国澳门）
Asia/Taipei（中国台湾）
Asia/Tokyo（日本，东京）
Asia/Seoul（韩国，首尔）
Asia/Singapore（新加坡）
Asia/Kuala_Lumpur（马来西亚，吉隆坡）
Asia/Jakarta（印度尼西亚，雅加达）
Asia/Bangkok（泰国，曼谷）
Asia/Ho_Chi_Minh（越南，胡志明市）
Asia/Phnom_Penh（柬埔寨，金边）
Asia/Vientiane（老挝，万象）
Asia/Kolkata（印度，加尔各答/新德里）
Asia/Dhaka（孟加拉国，达卡）
Asia/Kathmandu（尼泊尔，加德满都）
Asia/Colombo（斯里兰卡，科伦坡）
Asia/Dubai（阿联酋，迪拜）
Asia/Tehran（伊朗，德黑兰）
Asia/Baku（阿塞拜疆，巴库）
Asia/Yerevan（亚美尼亚，埃里温）
Asia/Riyadh（沙特阿拉伯，利雅得）
Asia/Karachi（巴基斯坦，卡拉奇）
Asia/Almaty（哈萨克斯坦，阿拉木图）
Asia/Bishkek（吉尔吉斯斯坦，比什凯克）
Asia/Ulaanbaatar（蒙古国，乌兰巴托）

欧洲

Europe/London（英国，伦敦）
Europe/Dublin（爱尔兰，都柏林）
Europe/Paris（法国，巴黎）
Europe/Berlin（德国，柏林）
Europe/Madrid（西班牙，马德里）
Europe/Rome（意大利，罗马）
Europe/Amsterdam（荷兰，阿姆斯特丹）
Europe/Zurich（瑞士，苏黎世）
Europe/Stockholm（瑞典，斯德哥尔摩）
Europe/Oslo（挪威，奥斯陆）
Europe/Copenhagen（丹麦，哥本哈根）
Europe/Warsaw（波兰，华沙）
Europe/Prague（捷克，布拉格）
Europe/Vienna（奥地利，维也纳）
Europe/Budapest（匈牙利，布达佩斯）
Europe/Athens（希腊，雅典）
Europe/Istanbul（土耳其，伊斯坦布尔）
Europe/Moscow（俄罗斯，莫斯科）

非洲

Africa/Cairo（埃及，开罗）
Africa/Johannesburg（南非，约翰内斯堡）
Africa/Nairobi（肯尼亚，内罗毕）
Africa/Lagos（尼日利亚，拉各斯）
Africa/Accra（加纳，阿克拉）
Africa/Casablanca（摩洛哥，卡萨布兰卡）

北美洲

America/New_York（美国，纽约）
America/Chicago（美国，芝加哥）
America/Denver（美国，丹佛）
America/Los_Angeles（美国，洛杉矶）
America/Toronto（加拿大，多伦多）
America/Vancouver（加拿大，温哥华）
America/Mexico_City（墨西哥，墨西哥城）

南美洲

America/Sao_Paulo（巴西，圣保罗）
America/Buenos_Aires（阿根廷，布宜诺斯艾利斯）
America/Lima（秘鲁，利马）
America/Bogota（哥伦比亚，波哥大）

大洋洲

Australia/Sydney（澳大利亚，悉尼）
Australia/Perth（澳大利亚，珀斯）
Australia/Adelaide（澳大利亚，阿德莱德）
Australia/Brisbane（澳大利亚，布里斯班）
Australia/Hobart（澳大利亚，霍巴特）
Pacific/Auckland（新西兰，奥克兰）
Pacific/Fiji（斐济）
Pacific/Guam（关岛）

通用错误码

以下错误码适用于平台全部 /v1/* 接口（各接口在「错误代码」Tab 中另有本接口补充说明）。

错误响应格式

HTTP 状态码非 2xx 时，响应体一般为：

{
  "error": {
    "code": "错误码",
    "message": "错误信息"
  }
}

错误码一览

HTTP	code	message	说明
400	invalid_params	参数无效	必填参数缺失、格式不合法或超出允许范围
404	not_found	资源不存在	按编码或 ID 查询时无匹配记录
429	rate_limit_exceeded	请求过于频繁	超过当前 IP 的访问频率限制
500	internal_error	服务器内部错误	服务端或数据库异常，请稍后重试

限流、缓存等 HTTP 响应头含义见上文「响应头说明」。

本接口补充

HTTP	code	message	说明
400	invalid_params	参数无效	时区名错误、时间格式不支持、参数缺失或冲突

请求根地址为 https://www.resapi.cn。每个场景含 7 种语言（cURL → JavaScript → Python → Go → Java → PHP → C#）。

当前时间（指定时区）

GET /v1/time/now?tz=UTC

cURL

curl -s "https://www.resapi.cn/v1/time/now?tz=UTC" -H "Accept: application/json"

JavaScript

const res = await fetch("https://www.resapi.cn/v1/time/now?tz=UTC", {
  headers: { Accept: "application/json" },
});
if (!res.ok) throw new Error(res.statusText);
console.log(await res.json());

Python

import requests

r = requests.get(
    "https://www.resapi.cn/v1/time/now",
    params={"tz": "UTC"},
    headers={"Accept": "application/json"},
    timeout=30,
)
r.raise_for_status()
print(r.json())

Go

package main

import (
	"encoding/json"
	"fmt"
	"log"
	"net/http"
)

func main() {
	url := "https://www.resapi.cn/v1/time/now?tz=UTC"
	req, _ := http.NewRequest(http.MethodGet, url, nil)
	req.Header.Set("Accept", "application/json")
	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		log.Fatal(err)
	}
	defer resp.Body.Close()
	var out map[string]any
	if err := json.NewDecoder(resp.Body).Decode(&out); err != nil {
		log.Fatal(err)
	}
	fmt.Printf("%+v\n", out)
}

Java

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class Example {
    public static void main(String[] args) throws Exception {
        String url = "https://www.resapi.cn/v1/time/now?tz=UTC";
        HttpRequest req = HttpRequest.newBuilder()
            .uri(URI.create(url))
            .header("Accept", "application/json")
            .GET()
            .build();
        HttpResponse<String> res = HttpClient.newHttpClient()
            .send(req, HttpResponse.BodyHandlers.ofString());
        System.out.println(res.body());
    }
}

PHP

<?php
$url = "https://www.resapi.cn/v1/time/now?tz=UTC";
$ctx = stream_context_create([
    "http" => ["header" => "Accept: application/json\r\n"],
]);
$json = file_get_contents($url, false, $ctx);
print_r(json_decode($json, true));

C#

using System.Net.Http.Headers;

var client = new HttpClient();
client.DefaultRequestHeaders.Accept.Add(
    new MediaTypeWithQualityHeaderValue("application/json"));
var json = await client.GetStringAsync("https://www.resapi.cn/v1/time/now?tz=UTC");
Console.WriteLine(json);

时区转换

GET /v1/time/convert?datetime=2026-06-02 21:30:00&from_tz=Asia/Shanghai&to_tz=UTC

cURL

curl -s "https://www.resapi.cn/v1/time/convert?datetime=2026-06-02%2021:30:00&from_tz=Asia/Shanghai&to_tz=UTC" \
  -H "Accept: application/json"

JavaScript

const url = new URL("https://www.resapi.cn/v1/time/convert");
url.searchParams.set("datetime", "2026-06-02 21:30:00");
url.searchParams.set("from_tz", "Asia/Shanghai");
url.searchParams.set("to_tz", "UTC");
const res = await fetch(url, { headers: { Accept: "application/json" } });
if (!res.ok) throw new Error(res.statusText);
console.log(await res.json());

Python

import requests

r = requests.get(
    "https://www.resapi.cn/v1/time/convert",
    params={
        "datetime": "2026-06-02 21:30:00",
        "from_tz": "Asia/Shanghai",
        "to_tz": "UTC",
    },
    headers={"Accept": "application/json"},
    timeout=30,
)
r.raise_for_status()
print(r.json())

Go

url := "https://www.resapi.cn/v1/time/convert?datetime=2026-06-02%2021:30:00&from_tz=Asia/Shanghai&to_tz=UTC"
req, _ := http.NewRequest(http.MethodGet, url, nil)
req.Header.Set("Accept", "application/json")
resp, err := http.DefaultClient.Do(req)
if err != nil {
	log.Fatal(err)
}
defer resp.Body.Close()
var out map[string]any
json.NewDecoder(resp.Body).Decode(&out)
fmt.Printf("%+v\n", out)

Java

String url = "https://www.resapi.cn/v1/time/convert?datetime=2026-06-02%2021:30:00&from_tz=Asia/Shanghai&to_tz=UTC";
HttpRequest req = HttpRequest.newBuilder()
    .uri(URI.create(url))
    .header("Accept", "application/json")
    .GET()
    .build();
HttpResponse<String> res = HttpClient.newHttpClient()
    .send(req, HttpResponse.BodyHandlers.ofString());
System.out.println(res.body());

PHP

<?php
$url = "https://www.resapi.cn/v1/time/convert?datetime=2026-06-02%2021:30:00&from_tz=Asia/Shanghai&to_tz=UTC";
$ctx = stream_context_create([
    "http" => ["header" => "Accept: application/json\r\n"],
]);
$json = file_get_contents($url, false, $ctx);
print_r(json_decode($json, true));

C#

var json = await client.GetStringAsync("https://www.resapi.cn/v1/time/convert?datetime=2026-06-02%2021:30:00&from_tz=Asia/Shanghai&to_tz=UTC");
Console.WriteLine(json);

时间戳互转

GET /v1/time/timestamp?timestamp=1717335000&tz=Asia/Shanghai

cURL

curl -s "https://www.resapi.cn/v1/time/timestamp?timestamp=1717335000&tz=Asia/Shanghai" \
  -H "Accept: application/json"

JavaScript

const res = await fetch("https://www.resapi.cn/v1/time/timestamp?timestamp=1717335000&tz=Asia/Shanghai", {
  headers: { Accept: "application/json" },
});
if (!res.ok) throw new Error(res.statusText);
console.log(await res.json());

Python

r = requests.get(
    "https://www.resapi.cn/v1/time/timestamp",
    params={"timestamp": "1717335000", "tz": "Asia/Shanghai"},
    headers={"Accept": "application/json"},
    timeout=30,
)
r.raise_for_status()
print(r.json())

Go

url := "https://www.resapi.cn/v1/time/timestamp?timestamp=1717335000&tz=Asia/Shanghai"
req, _ := http.NewRequest(http.MethodGet, url, nil)
req.Header.Set("Accept", "application/json")
resp, err := http.DefaultClient.Do(req)
if err != nil {
	log.Fatal(err)
}
defer resp.Body.Close()
var out map[string]any
json.NewDecoder(resp.Body).Decode(&out)
fmt.Printf("%+v\n", out)

Java

String url = "https://www.resapi.cn/v1/time/timestamp?timestamp=1717335000&tz=Asia/Shanghai";
HttpRequest req = HttpRequest.newBuilder()
    .uri(URI.create(url))
    .header("Accept", "application/json")
    .GET()
    .build();
HttpResponse<String> res = HttpClient.newHttpClient()
    .send(req, HttpResponse.BodyHandlers.ofString());
System.out.println(res.body());

PHP

<?php
$url = "https://www.resapi.cn/v1/time/timestamp?timestamp=1717335000&tz=Asia/Shanghai";
$ctx = stream_context_create([
    "http" => ["header" => "Accept: application/json\r\n"],
]);
$json = file_get_contents($url, false, $ctx);
print_r(json_decode($json, true));

C#

var json = await client.GetStringAsync("https://www.resapi.cn/v1/time/timestamp?timestamp=1717335000&tz=Asia/Shanghai");
Console.WriteLine(json);

时区列表（含中文）

GET /v1/time/timezones?region=asia&q=中国

cURL

curl -s "https://www.resapi.cn/v1/time/timezones?region=asia&q=%E4%B8%AD%E5%9B%BD" \
  -H "Accept: application/json"

JavaScript

const url = new URL("https://www.resapi.cn/v1/time/timezones");
url.searchParams.set("region", "asia");
url.searchParams.set("q", "中国");
const res = await fetch(url, { headers: { Accept: "application/json" } });
if (!res.ok) throw new Error(res.statusText);
console.log(await res.json());

Python

r = requests.get(
    "https://www.resapi.cn/v1/time/timezones",
    params={"region": "asia", "q": "中国"},
    headers={"Accept": "application/json"},
    timeout=30,
)
r.raise_for_status()
print(r.json())

Go

url := "https://www.resapi.cn/v1/time/timezones?region=asia&q=%E4%B8%AD%E5%9B%BD"
req, _ := http.NewRequest(http.MethodGet, url, nil)
req.Header.Set("Accept", "application/json")
resp, err := http.DefaultClient.Do(req)
if err != nil {
	log.Fatal(err)
}
defer resp.Body.Close()
var out map[string]any
json.NewDecoder(resp.Body).Decode(&out)
fmt.Printf("%+v\n", out)

Java

String url = "https://www.resapi.cn/v1/time/timezones?region=asia&q=%E4%B8%AD%E5%9B%BD";
HttpRequest req = HttpRequest.newBuilder()
    .uri(URI.create(url))
    .header("Accept", "application/json")
    .GET()
    .build();
HttpResponse<String> res = HttpClient.newHttpClient()
    .send(req, HttpResponse.BodyHandlers.ofString());
System.out.println(res.body());

PHP

<?php
$url = "https://www.resapi.cn/v1/time/timezones?region=asia&q=%E4%B8%AD%E5%9B%BD";
$ctx = stream_context_create([
    "http" => ["header" => "Accept: application/json\r\n"],
]);
$json = file_get_contents($url, false, $ctx);
print_r(json_decode($json, true));

C#

var json = await client.GetStringAsync("https://www.resapi.cn/v1/time/timezones?region=asia&q=%E4%B8%AD%E5%9B%BD");
Console.WriteLine(json);

简介

GET /v1/time/now

查询参数

响应字段

GET /v1/time/convert

查询参数

GET /v1/time/timestamp

查询参数

GET /v1/time/timezones

查询参数

响应字段

IANA 时区参考（tz 参数）

常用时区（按区域，含中文名称）

UTC

亚洲

欧洲

非洲

北美洲

南美洲

大洋洲

通用错误码

错误响应格式

错误码一览

本接口补充

当前时间（指定时区）

cURL

JavaScript

Python

Go

Java

PHP

C#

时区转换

cURL

JavaScript

Python

Go

Java

PHP

C#

时间戳互转

cURL

JavaScript

Python

Go

Java

PHP

C#

时区列表（含中文）

cURL

JavaScript

Python

Go

Java

PHP

C#

IANA 时区参考（`tz` 参数）