Dành cho nhà phát triển

API múi giờ miễn phí

Chính bộ máy vận hành Hourora, dưới dạng JSON thuần: giờ ở bất cứ đâu, chuyển đổi có tính đến giờ mùa hè, mọi múi giờ IANA và các lần đổi giờ của chúng. Không cần khóa, không cần đăng ký.

Tổng quan

URL gốc: https://hourora.app/api/v1
Định dạng: JSON (UTF-8), chỉ yêu cầu GET
Xác thực: Không cần: không khóa, không đăng ký, không cookie
CORS: Mở cho mọi nguồn (origin), nên bạn có thể gọi từ trình duyệt
Giới hạn tần suất: 120 yêu cầu mỗi phút cho mỗi máy khách
Dữ liệu thời gian: IANA tzdata 2026e, do Hourora biên dịch
Mô tả máy đọc được: Tài liệu OpenAPI 3.1

Thử trực tiếp

Chọn một ví dụ hoặc sửa đường dẫn, rồi gửi đi. Yêu cầu đi thẳng từ trình duyệt của bạn đến API.

Phản hồi

Phản hồi sẽ hiển thị ở đây.

Các endpoint

Mọi endpoint đều trả lời yêu cầu GET bằng JSON. Thời gian theo ISO 8601; độ lệch (offset) tính bằng phút về phía đông của UTC (New York vào mùa đông là −300) và cũng được viết dưới dạng văn bản (−05:00).

Giờ hiện tại

GET/api/v1/time

Giờ hiện tại ở một múi giờ hoặc thành phố: giờ địa phương, độ lệch UTC, chữ viết tắt, giờ mùa hè và lần đổi giờ tiếp theo. Không có tham số: UTC.

Tham số

Tên	Ý nghĩa
`tz`tùy chọn	Tên múi giờ IANA, ví dụ Europe/London. Các bí danh như Asia/Calcutta được chấp nhận và trả về tên hiện hành.
`city`tùy chọn	Slug thành phố thay cho tz, ví dụ london (tìm slug bằng /cities).

Yêu cầu mẫu

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

Phản hồi mẫu

{
  "zone": "Europe/London",
  "local": "2026-10-14T01:58:05",
  "iso": "2026-10-14T01:58:05+01:00",
  "offsetMinutes": 60,
  "offset": "+01:00",
  "utcOffset": "UTC+1",
  "abbreviation": "BST",
  "dst": true,
  "city": null,
  "utc": "2026-10-14T00:58:05.097Z",
  "unixMs": 1791939485097,
  "date": "2026-10-14",
  "time": "01:58:05",
  "weekday": "Wednesday",
  "dayOfYear": 287,
  "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"
}

Phản hồi thật từ máy chủ này.

Chuyển đổi giờ

GET/api/v1/convert

Một mốc giờ đồng hồ ở múi giờ này được hiển thị ở múi giờ khác. Cho biết khi mốc giờ rơi vào khoảng trống giờ mùa hè (không tồn tại) hoặc khoảng chồng lấn (xảy ra hai lần).

Tham số

Tên	Ý nghĩa
`from`bắt buộc	Múi giờ (hoặc slug thành phố) dùng để đọc mốc giờ.
`to`bắt buộc	Múi giờ (hoặc slug thành phố) để hiển thị mốc giờ.
`time`tùy chọn	Giờ đồng hồ trong múi giờ from, YYYY-MM-DDTHH:mm (giây tùy chọn, không có độ lệch), 1970–2060. Mặc định: bây giờ.

Yêu cầu mẫu

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

Phản hồi mẫu

{
  "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"
}

Phản hồi thật từ máy chủ này.

Danh sách múi giờ

GET/api/v1/zones

Mọi múi giờ IANA với độ lệch UTC hiện tại, chữ viết tắt, trạng thái giờ mùa hè, các quốc gia và thành phố chính.

Tham số

Tên	Ý nghĩa
`country`tùy chọn	Mã quốc gia ISO 3166, ví dụ GB, để chỉ giữ quốc gia đó.

Yêu cầu mẫu

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

Phản hồi mẫu

{
  "asOf": "2026-10-14T00:58:05.097Z",
  "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"
    }
  ]
}

Phản hồi thật từ máy chủ này; danh sách được rút gọn còn 3 mục đầu tiên.

Một múi giờ

GET/api/v1/zones/{id}

Một múi giờ IANA: các bí danh, quốc gia và thành phố, độ lệch hiện tại, lần đổi giờ tiếp theo và mọi lần đổi giờ trong một năm nhất định.

Tham số

Tên	Ý nghĩa
`id`trong đường dẫn	Tên múi giờ IANA; giữ nguyên dấu gạch chéo hoặc mã hóa thành %2F.
`year`tùy chọn	Năm cần liệt kê các lần đổi giờ, 1970–2060. Mặc định: năm nay.

Yêu cầu mẫu

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

Phản hồi mẫu

{
  "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-13T20:58:05",
    "iso": "2026-10-13T20:58:05-04:00",
    "offsetMinutes": -240,
    "offset": "-04:00",
    "utcOffset": "UTC-4",
    "abbreviation": "EDT",
    "dst": true,
    "utc": "2026-10-14T00:58:05.097Z",
    "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"
}

Phản hồi thật từ máy chủ này; danh sách được rút gọn còn 3 mục đầu tiên.

Tìm thành phố

GET/api/v1/cities

Các thành phố có tên khớp, ưu tiên kết quả khớp nhất và thành phố lớn nhất, kèm quốc gia, tọa độ và múi giờ của từng nơi.

Tham số

Tên	Ý nghĩa
`q`bắt buộc	Một phần tên thành phố, dấu không bắt buộc (tối đa 80 ký tự).
`limit`tùy chọn	Số kết quả, 1–50. Mặc định 10.
`country`tùy chọn	Mã quốc gia ISO 3166, ví dụ GB, để chỉ giữ quốc gia đó.

Yêu cầu mẫu

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

Phản hồi mẫu

{
  "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"
    }
  ]
}

Phản hồi thật từ máy chủ này.

Một thành phố

GET/api/v1/cities/{slug}

Một thành phố theo slug, kèm độ lệch hiện tại của múi giờ và lần đổi giờ tiếp theo.

Tham số

Tên	Ý nghĩa
`slug`trong đường dẫn	Slug thành phố, ví dụ tokyo.

Yêu cầu mẫu

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

Phản hồi mẫu

{
  "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-14T09:58:05",
    "iso": "2026-10-14T09:58:05+09:00",
    "offsetMinutes": 540,
    "offset": "+09:00",
    "utcOffset": "UTC+9",
    "abbreviation": "JST",
    "dst": false,
    "utc": "2026-10-14T00:58:05.097Z"
  },
  "nextTransition": null,
  "tzdata": "2026e"
}

Phản hồi thật từ máy chủ này.

Tọa độ sang múi giờ

GET/api/v1/lookup

Thành phố có trong danh sách gần nhất với một vĩ độ và kinh độ, cùng múi giờ của nó. Đây là ước lượng: ranh giới múi giờ không được mô phỏng.

Tham số

Tên	Ý nghĩa
`lat`bắt buộc	Vĩ độ theo độ thập phân, từ −90 đến 90.
`lng`bắt buộc	Kinh độ theo độ thập phân, từ −180 đến 180.

Yêu cầu mẫu

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

Phản hồi mẫu

{
  "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-14T02:58:05",
    "iso": "2026-10-14T02:58:05+02:00",
    "offsetMinutes": 120,
    "offset": "+02:00",
    "utcOffset": "UTC+2",
    "abbreviation": "CEST",
    "dst": true,
    "utc": "2026-10-14T00:58:05.097Z"
  },
  "tzdata": "2026e"
}

Phản hồi thật từ máy chủ này.

Phiên bản dữ liệu

GET/api/v1/tzdata

Câu trả lời đến từ bản phát hành nào của cơ sở dữ liệu múi giờ IANA, và lần gần nhất Hourora cập nhật dữ liệu.

Tham số

Không có tham số.

Yêu cầu mẫu

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

Phản hồi mẫu

{
  "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."
}

Phản hồi thật từ máy chủ này.

Lỗi

Lỗi cũng là JSON: mã trạng thái HTTP, một mã ổn định cho chương trình của bạn và một thông báo cho người đọc.

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

Trạng thái	Mã	Khi nào
400	`missing_parameter, invalid_parameter`	Thiếu tham số hoặc tham số không đúng định dạng mong đợi.
404	`unknown_zone, unknown_city, unknown_country, not_found`	Không có múi giờ, thành phố, quốc gia hoặc endpoint như vậy.
429	`rate_limited`	Máy khách của bạn gửi quá nhiều yêu cầu; hãy chờ số giây ghi trong Retry-After.
500	`internal_error`	Đã xảy ra lỗi ở phía chúng tôi. Vui lòng thử lại sau.

Cách hoạt động

Giới hạn và bộ nhớ đệm

Mỗi máy khách có thể gửi tối đa 120 yêu cầu mỗi phút, cho phép tăng đột biến trong thời gian ngắn. Vượt quá mức đó, API trả về 429 kèm header Retry-After. Giới hạn này bảo vệ một dịch vụ miễn phí; nếu cần nhiều hơn, hãy dùng bộ nhớ đệm.

Mỗi phản hồi cho biết có thể lưu vào bộ nhớ đệm trong bao lâu (Cache-Control). Giờ hiện tại không bao giờ được lưu đệm; danh sách múi giờ, thông tin thành phố và tra cứu tọa độ được lưu năm phút; tìm kiếm thành phố và chuyển đổi một mốc giờ cụ thể được lưu một ngày.

Đang làm một chiếc đồng hồ? Lấy độ lệch một lần, cho đồng hồ chạy cục bộ, và lấy lại sau lần đổi giờ tiếp theo mà phản hồi cho biết. Không cần truy vấn mỗi giây.

Câu trả lời đến từ đâu

Độ lệch, chữ viết tắt và các lần đổi giờ lấy từ bản sao cơ sở dữ liệu múi giờ IANA do chính Hourora biên dịch, bản phát hành 2026e, cho giai đoạn 1970–2060. Ngoài khoảng đó, dữ liệu tích hợp sẵn của máy chủ được sử dụng, có thể cũ hơn.

Phép chuyển đổi xử lý rõ ràng các điểm biên của giờ mùa hè: một mốc giờ bị bỏ qua khi đồng hồ được vặn tới được báo là khoảng trống, và một mốc giờ xảy ra hai lần khi đồng hồ được vặn lùi được báo là khoảng chồng lấn, kèm cả hai thời điểm.

Tra cứu tọa độ trả về thành phố gần nhất trong khoảng 7.200 thành phố có trong danh sách và múi giờ của thành phố đó. Gần biên giới, trên biển hoặc ở vùng thưa dân, kết quả có thể khác với múi giờ thực sự áp dụng tại điểm đó.

Điều khoản sử dụng

Miễn phí cho mục đích cá nhân và thương mại. Không cần khóa, không cần tài khoản.
Ghi nguồn được hoan nghênh nhưng không bắt buộc: một liên kết đến hourora.app gần nơi dữ liệu xuất hiện.
Cung cấp nguyên trạng, không có thỏa thuận mức dịch vụ (SLA) hay cam kết về tính sẵn sàng. Không dùng ở nơi mà giờ sai hoặc thiếu có thể gây hại.
Câu trả lời theo IANA tzdata 2026e. Khi các chính phủ thay đổi giờ, dữ liệu được cập nhật cùng bản phát hành IANA tiếp theo.
Phiên bản 1 luôn tương thích: có thể thêm trường mới, không có gì bị xóa hay đổi tên. Các thay đổi không tương thích sẽ có ở /api/v2.
Vui lòng tuân thủ giới hạn tần suất và lưu phản hồi vào bộ nhớ đệm. Lưu lượng lạm dụng có thể bị chặn.

Câu hỏi

Điều nên biết

API của Hourora có thật sự miễn phí không?

Có. Không cần khóa, không cần tài khoản và không có gói trả phí. Giới hạn tần suất cho mỗi máy khách giúp dịch vụ công bằng cho mọi người.

Tôi có thể gọi API từ JavaScript trong trình duyệt không?

Có. Mọi endpoint đều cho phép yêu cầu khác nguồn từ bất kỳ trang web nào (CORS), và không cần thông tin xác thực.

API xử lý giờ mùa hè như thế nào?

Mỗi câu trả lời được tính cho đúng thời điểm theo các quy tắc IANA. Endpoint convert còn cho bạn biết khi một mốc giờ được yêu cầu không tồn tại (khi vặn đồng hồ tới) hoặc xảy ra hai lần (khi vặn đồng hồ lùi).

Tra cứu theo tọa độ chính xác đến mức nào?

API trả về múi giờ của thành phố có trong danh sách gần nhất, đúng ở hầu hết mọi nơi có người sinh sống. API không mô phỏng ranh giới múi giờ, nên có thể sai ở gần biên giới hoặc trên biển.