面向开发者

免费的时区 API

驱动 Hourora 的同一引擎，以纯 JSON 形式提供：任意地点的时间、考虑夏令时的换算、每个 IANA 时区及其时钟调整。无需密钥，无需注册。

概览

基础 URL: https://hourora.app/api/v1
格式: JSON（UTF-8），仅限 GET 请求
身份验证: 无：无需密钥、注册或 Cookie
CORS: 对所有来源开放，可直接在浏览器中调用
速率限制: 每个客户端每分钟120次请求
时间数据: IANA tzdata 2026e，由 Hourora 编译
机器可读描述: OpenAPI 3.1 文档

在线试用

选择一个示例或编辑路径，然后发送。请求将从您的浏览器直接发送到 API。

响应

响应将显示在这里。

端点

每个端点都以 JSON 响应 GET 请求。时间采用 ISO 8601；偏移量以 UTC 以东的分钟数表示（冬季的纽约为 −300），同时以文本形式给出（−05:00）。

当前时间

GET/api/v1/time

某个时区或城市的当前时间：当地时间、UTC 偏移量、缩写、夏令时状态及下一次时钟调整。不带参数时返回 UTC。

参数

名称	含义
`tz`可选	IANA 时区名称，例如 Europe/London。也接受 Asia/Calcutta 等别名，并以当前名称返回。
`city`可选	用城市 slug 代替 tz，例如 london（可通过 /cities 查找 slug）。

请求示例

curl "https://hourora.app/api/v1/time?tz=Europe/London"

响应示例

{
  "zone": "Europe/London",
  "local": "2026-10-13T22:55:34",
  "iso": "2026-10-13T22:55:34+01:00",
  "offsetMinutes": 60,
  "offset": "+01:00",
  "utcOffset": "UTC+1",
  "abbreviation": "BST",
  "dst": true,
  "city": null,
  "utc": "2026-10-13T21:55:34.558Z",
  "unixMs": 1791928534558,
  "date": "2026-10-13",
  "time": "22:55:34",
  "weekday": "Tuesday",
  "dayOfYear": 286,
  "isoWeek": 42,
  "dstObserved": true,
  "nextTransition": {
    "at": "2026-10-25T01:00:00.000Z",
    "unixMs": 1792890000000,
    "type": "dst-end",
    "fromOffsetMinutes": 60,
    "toOffsetMinutes": 0,
    "shiftMinutes": -60,
    "fromAbbreviation": "BST",
    "toAbbreviation": "GMT",
    "localBefore": "2026-10-25T02:00:00",
    "localAfter": "2026-10-25T01:00:00"
  },
  "tzdata": "2026e"
}

来自本服务器的真实响应。

时间换算

GET/api/v1/convert

将一个时区的挂钟时间换算为另一个时区的时间。若该时间落在夏令时跳空（不存在）或重叠（出现两次）区间，会予以说明。

参数

名称	含义
`from`必填	读取时间所用的时区（或城市 slug）。
`to`必填	要换算到的时区（或城市 slug）。
`time`可选	from 时区的挂钟时间，格式 YYYY-MM-DDTHH:mm（秒可选，不带偏移量），范围1970–2060。默认：现在。

请求示例

curl "https://hourora.app/api/v1/convert?from=America/New_York&to=Asia/Kolkata&time=2026-10-16T15:00"

响应示例

{
  "status": "ok",
  "requested": "2026-10-16T15:00:00",
  "utc": "2026-10-16T19:00:00.000Z",
  "unixMs": 1792177200000,
  "from": {
    "zone": "America/New_York",
    "local": "2026-10-16T15:00:00",
    "iso": "2026-10-16T15:00:00-04:00",
    "offsetMinutes": -240,
    "offset": "-04:00",
    "utcOffset": "UTC-4",
    "abbreviation": "EDT",
    "dst": true
  },
  "to": {
    "zone": "Asia/Kolkata",
    "local": "2026-10-17T00:30:00",
    "iso": "2026-10-17T00:30:00+05:30",
    "offsetMinutes": 330,
    "offset": "+05:30",
    "utcOffset": "UTC+5:30",
    "abbreviation": "IST",
    "dst": false,
    "dayOffset": 1
  },
  "differenceMinutes": 570,
  "tzdata": "2026e"
}

来自本服务器的真实响应。

时区列表

GET/api/v1/zones

所有 IANA 时区及其当前 UTC 偏移量、缩写、夏令时状态、所属国家和主要城市。

参数

名称	含义
`country`可选	ISO 3166 国家代码，例如 GB，仅保留该国家。

请求示例

curl "https://hourora.app/api/v1/zones?country=GB"

响应示例

{
  "asOf": "2026-10-13T21:55:34.558Z",
  "count": 1,
  "tzdata": "2026e",
  "zones": [
    {
      "id": "Europe/London",
      "offsetMinutes": 60,
      "offset": "+01:00",
      "utcOffset": "UTC+1",
      "abbreviation": "BST",
      "dst": true,
      "countries": [
        "GB",
        "GG",
        "IM"
      ],
      "mainCity": "London"
    }
  ]
}

来自本服务器的真实响应；列表已缩短为前3项。

单个时区

GET/api/v1/zones/{id}

一个 IANA 时区：别名、国家和城市、当前偏移量、下一次时钟调整，以及指定年份内的所有调整。

参数

名称	含义
`id`位于路径中	IANA 时区名称；保留斜杠或编码为 %2F。
`year`可选	要列出时钟调整的年份，1970–2060。默认：今年。

请求示例

curl "https://hourora.app/api/v1/zones/America%2FNew_York?year=2027"

响应示例

{
  "id": "America/New_York",
  "aliases": [
    "US/Eastern"
  ],
  "countries": [
    {
      "code": "US",
      "name": "United States"
    }
  ],
  "cities": [
    {
      "slug": "new-york",
      "name": "New York"
    },
    {
      "slug": "philadelphia",
      "name": "Philadelphia"
    },
    {
      "slug": "miami",
      "name": "Miami"
    }
  ],
  "now": {
    "zone": "America/New_York",
    "local": "2026-10-13T17:55:34",
    "iso": "2026-10-13T17:55:34-04:00",
    "offsetMinutes": -240,
    "offset": "-04:00",
    "utcOffset": "UTC-4",
    "abbreviation": "EDT",
    "dst": true,
    "utc": "2026-10-13T21:55:34.558Z",
    "standardOffsetMinutes": -300,
    "dstObserved": true
  },
  "nextTransition": {
    "at": "2026-11-01T06:00:00.000Z",
    "unixMs": 1793512800000,
    "type": "dst-end",
    "fromOffsetMinutes": -240,
    "toOffsetMinutes": -300,
    "shiftMinutes": -60,
    "fromAbbreviation": "EDT",
    "toAbbreviation": "EST",
    "localBefore": "2026-11-01T02:00:00",
    "localAfter": "2026-11-01T01:00:00"
  },
  "year": 2027,
  "dstObservedInYear": true,
  "transitions": [
    {
      "at": "2027-03-14T07:00:00.000Z",
      "unixMs": 1805007600000,
      "type": "dst-start",
      "fromOffsetMinutes": -300,
      "toOffsetMinutes": -240,
      "shiftMinutes": 60,
      "fromAbbreviation": "EST",
      "toAbbreviation": "EDT",
      "localBefore": "2027-03-14T02:00:00",
      "localAfter": "2027-03-14T03:00:00"
    },
    {
      "at": "2027-11-07T06:00:00.000Z",
      "unixMs": 1825567200000,
      "type": "dst-end",
      "fromOffsetMinutes": -240,
      "toOffsetMinutes": -300,
      "shiftMinutes": -60,
      "fromAbbreviation": "EDT",
      "toAbbreviation": "EST",
      "localBefore": "2027-11-07T02:00:00",
      "localAfter": "2027-11-07T01:00:00"
    }
  ],
  "tzdata": "2026e"
}

来自本服务器的真实响应；列表已缩短为前3项。

搜索城市

GET/api/v1/cities

名称匹配的城市，最佳匹配和最大城市优先，每个城市附国家、坐标和时区。

参数

名称	含义
`q`必填	城市名称的一部分，重音符号可省略（最多80个字符）。
`limit`可选	结果数量，1–50。默认10。
`country`可选	ISO 3166 国家代码，例如 GB，仅保留该国家。

请求示例

curl "https://hourora.app/api/v1/cities?q=lond&limit=3"

响应示例

{
  "query": "lond",
  "count": 3,
  "total": 7,
  "cities": [
    {
      "slug": "london",
      "name": "London",
      "asciiName": "London",
      "country": {
        "code": "GB",
        "name": "United Kingdom"
      },
      "region": "Westminster",
      "zone": "Europe/London",
      "lat": 51.5,
      "lng": -0.1167,
      "population": 7994105,
      "capital": true,
      "url": "https://hourora.app/en/london"
    },
    {
      "slug": "londrina",
      "name": "Londrina",
      "asciiName": "Londrina",
      "country": {
        "code": "BR",
        "name": "Brazil"
      },
      "region": "Paraná",
      "zone": "America/Sao_Paulo",
      "lat": -23.3,
      "lng": -51.18,
      "population": 496035,
      "capital": false,
      "url": "https://hourora.app/en/londrina"
    },
    {
      "slug": "london-ontario",
      "name": "London",
      "asciiName": "London",
      "country": {
        "code": "CA",
        "name": "Canada"
      },
      "region": "Ontario",
      "zone": "America/Toronto",
      "lat": 42.97,
      "lng": -81.25,
      "population": 340900,
      "capital": false,
      "url": "https://hourora.app/en/london-ontario"
    }
  ]
}

来自本服务器的真实响应。

单个城市

GET/api/v1/cities/{slug}

按 slug 查询一个城市，附其时区当前的偏移量及下一次时钟调整。

参数

名称	含义
`slug`位于路径中	城市 slug，例如 tokyo。

请求示例

curl "https://hourora.app/api/v1/cities/tokyo"

响应示例

{
  "slug": "tokyo",
  "name": "Tokyo",
  "asciiName": "Tokyo",
  "country": {
    "code": "JP",
    "name": "Japan"
  },
  "region": "Tokyo",
  "zone": "Asia/Tokyo",
  "lat": 35.685,
  "lng": 139.7514,
  "population": 22006300,
  "capital": true,
  "url": "https://hourora.app/en/tokyo",
  "now": {
    "zone": "Asia/Tokyo",
    "local": "2026-10-14T06:55:34",
    "iso": "2026-10-14T06:55:34+09:00",
    "offsetMinutes": 540,
    "offset": "+09:00",
    "utcOffset": "UTC+9",
    "abbreviation": "JST",
    "dst": false,
    "utc": "2026-10-13T21:55:34.558Z"
  },
  "nextTransition": null,
  "tzdata": "2026e"
}

来自本服务器的真实响应。

坐标查时区

GET/api/v1/lookup

距给定经纬度最近的已收录城市及其时区。这是近似结果：未对时区边界建模。

参数

名称	含义
`lat`必填	纬度，十进制度数，−90 至 90。
`lng`必填	经度，十进制度数，−180 至 180。

请求示例

curl "https://hourora.app/api/v1/lookup?lat=48.85&lng=2.35"

响应示例

{
  "query": {
    "lat": 48.85,
    "lng": 2.35
  },
  "approximate": true,
  "method": "nearest listed city (great-circle distance); time-zone borders are not modelled",
  "distanceKm": 2.2,
  "city": {
    "slug": "paris",
    "name": "Paris",
    "asciiName": "Paris",
    "country": {
      "code": "FR",
      "name": "France"
    },
    "region": "Île-de-France",
    "zone": "Europe/Paris",
    "lat": 48.8667,
    "lng": 2.3333,
    "population": 4957589,
    "capital": true,
    "url": "https://hourora.app/en/paris"
  },
  "zone": "Europe/Paris",
  "now": {
    "zone": "Europe/Paris",
    "local": "2026-10-13T23:55:34",
    "iso": "2026-10-13T23:55:34+02:00",
    "offsetMinutes": 120,
    "offset": "+02:00",
    "utcOffset": "UTC+2",
    "abbreviation": "CEST",
    "dst": true,
    "utc": "2026-10-13T21:55:34.558Z"
  },
  "tzdata": "2026e"
}

来自本服务器的真实响应。

数据版本

GET/api/v1/tzdata

响应所依据的 IANA 时区数据库版本，以及 Hourora 最近一次更新数据的时间。

参数

无参数。

请求示例

curl "https://hourora.app/api/v1/tzdata"

响应示例

{
  "version": "2026e",
  "source": "IANA Time Zone Database",
  "sourceUrl": "https://www.iana.org/time-zones",
  "dataDate": "2026-10-13",
  "range": {
    "from": "1970-01-01",
    "to": "2060-12-31"
  },
  "zones": 344,
  "links": 253,
  "cities": 7269,
  "note": "Outside the compiled range, offsets fall back to the server runtime's own tzdata."
}

来自本服务器的真实响应。

错误

错误同样以 JSON 返回：HTTP 状态码、供程序使用的固定代码，以及供人阅读的消息。

{
  "error": {
    "code": "unknown_zone",
    "message": "\"Mars/Base\" is not an IANA time zone name. List them with /api/v1/zones."
  }
}

状态	代码	触发情形
400	`missing_parameter, invalid_parameter`	缺少参数或参数格式不符合要求。
404	`unknown_zone, unknown_city, unknown_country, not_found`	不存在该时区、城市、国家或端点。
429	`rate_limited`	您的客户端请求过多；请等待 Retry-After 中给出的秒数。
500	`internal_error`	我们这边出现故障。请稍后重试。

工作原理

限制与缓存

每个客户端每分钟最多可发送120次请求，允许短时突发。超出后，API 将返回429及 Retry-After 响应头。此限制旨在保护免费服务；如需更多请求，请使用缓存。

每个响应都会说明可缓存的时长（Cache-Control）。当前时间从不缓存；时区列表、城市详情和坐标查询缓存五分钟；城市搜索和指定时间的换算缓存一天。

要做一个时钟？只需获取一次偏移量，在本地计时，并在响应告知的下一次时钟调整之后再次获取。无需每秒轮询。

数据从何而来

偏移量、缩写和时钟调整均来自 Hourora 自行编译的 IANA 时区数据库，版本2026e，涵盖1970–2060年。超出此范围时使用服务器内置数据，可能较旧。

换算会明确处理夏令时边界：时钟拨快时被跳过的时间报告为跳空（gap），时钟拨回时出现两次的时间报告为重叠（overlap），并给出两个时刻。

坐标查询返回约7,200个已收录城市中最近的一个及其时区。在边界附近、海上或人烟稀少的地区，结果可能与该地点实际适用的时区不同。

使用条款

个人和商业用途均免费。无需密钥，无需账户。
欢迎注明出处，但不强制：在显示数据的位置附近放一个指向 hourora.app 的链接即可。
按现状提供，不提供服务等级协议，也不保证可用性。请勿用于时间错误或缺失可能造成损害的场景。
响应依据 IANA tzdata 2026e。各国政府调整时制后，数据将随下一个 IANA 版本更新。
版本1保持兼容：可能新增字段，但不会删除或重命名。破坏性变更将以 /api/v2 发布。
请遵守速率限制并缓存响应。滥用流量可能会被封禁。

常见问题

值得了解

Hourora API 真的免费吗？

是的。无需密钥、无需账户，也没有付费套餐。按客户端设置的速率限制可确保所有人公平使用。

可以在浏览器中用 JavaScript 调用吗？

可以。每个端点都允许来自任何网站的跨域请求（CORS），且无需任何凭据。

如何处理夏令时？

每个响应都依据 IANA 规则针对确切时刻计算。convert 端点还会告知所请求的挂钟时间是否不存在（时钟拨快）或出现两次（时钟拨回）。

坐标查询有多准确？

它返回最近的已收录城市所在的时区，在几乎所有有人居住的地方都是正确的。由于未对时区边界建模，在边界附近或海上可能出错。