Untuk pengembang

API zona waktu gratis

Mesin yang sama yang menjalankan Hourora, dalam bentuk JSON biasa: waktu di mana pun, konversi yang memperhitungkan waktu musim panas (DST), setiap zona IANA dan pergantian jamnya. Tanpa kunci, tanpa pendaftaran.

Sekilas

URL dasar: https://hourora.app/api/v1
Format: JSON (UTF-8), hanya permintaan GET
Autentikasi: Tidak ada: tanpa kunci, tanpa pendaftaran, tanpa cookie
CORS: Terbuka untuk semua origin, sehingga bisa dipanggil dari browser
Batas permintaan: 120 permintaan per menit per klien
Data waktu: IANA tzdata 2026e, dikompilasi oleh Hourora
Deskripsi yang dapat dibaca mesin: Dokumen OpenAPI 3.1

Coba langsung

Pilih contoh atau ubah path, lalu kirim. Permintaan dikirim dari browser Anda langsung ke API.

Respons

Respons akan muncul di sini.

Daftar endpoint

Setiap endpoint menjawab GET dengan JSON. Waktu dalam format ISO 8601; offset dinyatakan dalam menit ke timur UTC (New York pada musim dingin adalah −300) dan juga ditulis sebagai teks (−05:00).

Waktu sekarang

GET/api/v1/time

Waktu sekarang di suatu zona waktu atau kota: waktu lokal, offset UTC, singkatan, waktu musim panas, dan pergantian jam berikutnya. Tanpa parameter: UTC.

Parameter

Nama	Arti
`tz`opsional	Nama zona waktu IANA, mis. Europe/London. Alias seperti Asia/Calcutta diterima dan dijawab dengan nama yang berlaku saat ini.
`city`opsional	Slug kota sebagai pengganti tz, mis. london (cari slug dengan /cities).

Contoh permintaan

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

Contoh respons

{
  "zone": "Europe/London",
  "local": "2026-10-14T02:01:15",
  "iso": "2026-10-14T02:01:15+01:00",
  "offsetMinutes": 60,
  "offset": "+01:00",
  "utcOffset": "UTC+1",
  "abbreviation": "BST",
  "dst": true,
  "city": null,
  "utc": "2026-10-14T01:01:15.054Z",
  "unixMs": 1791939675054,
  "date": "2026-10-14",
  "time": "02:01:15",
  "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"
}

Respons nyata dari server ini.

Konversi waktu

GET/api/v1/convert

Waktu jam dinding di satu zona ditampilkan di zona lain. Melaporkan jika waktu tersebut jatuh pada celah DST (tidak ada) atau tumpang-tindih DST (terjadi dua kali).

Parameter

Nama	Arti
`from`wajib	Zona (atau slug kota) tempat waktu dibaca.
`to`wajib	Zona (atau slug kota) tempat waktu ditampilkan.
`time`opsional	Waktu jam dinding di zona from, YYYY-MM-DDTHH:mm (detik opsional, tanpa offset), 1970–2060. Bawaan: sekarang.

Contoh permintaan

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

Contoh respons

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

Respons nyata dari server ini.

Daftar zona waktu

GET/api/v1/zones

Setiap zona waktu IANA beserta offset UTC saat ini, singkatan, status waktu musim panas, negara, dan kota utamanya.

Parameter

Nama	Arti
`country`opsional	Kode negara ISO 3166, mis. GB, untuk menampilkan negara itu saja.

Contoh permintaan

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

Contoh respons

{
  "asOf": "2026-10-14T01:01:15.054Z",
  "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"
    }
  ]
}

Respons nyata dari server ini; daftar dipersingkat menjadi 3 item pertama.

Satu zona waktu

GET/api/v1/zones/{id}

Satu zona IANA: alias, negara dan kotanya, offset saat ini, pergantian jam berikutnya, dan setiap pergantian dalam tahun tertentu.

Parameter

Nama	Arti
`id`di path	Nama zona IANA; pertahankan garis miring atau enkode sebagai %2F.
`year`opsional	Tahun yang pergantian jamnya ingin dicantumkan, 1970–2060. Bawaan: tahun ini.

Contoh permintaan

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

Contoh respons

{
  "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-13T21:01:15",
    "iso": "2026-10-13T21:01:15-04:00",
    "offsetMinutes": -240,
    "offset": "-04:00",
    "utcOffset": "UTC-4",
    "abbreviation": "EDT",
    "dst": true,
    "utc": "2026-10-14T01:01:15.054Z",
    "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"
}

Respons nyata dari server ini; daftar dipersingkat menjadi 3 item pertama.

Cari kota

GET/api/v1/cities

Kota yang namanya cocok, dengan kecocokan terbaik dan kota terbesar lebih dulu, masing-masing dengan negara, koordinat, dan zona waktunya.

Parameter

Nama	Arti
`q`wajib	Bagian dari nama kota, aksen opsional (maksimal 80 karakter).
`limit`opsional	Jumlah hasil, 1–50. Bawaan 10.
`country`opsional	Kode negara ISO 3166, mis. GB, untuk menampilkan negara itu saja.

Contoh permintaan

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

Contoh respons

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

Respons nyata dari server ini.

Satu kota

GET/api/v1/cities/{slug}

Satu kota berdasarkan slug-nya, dengan offset zona waktunya saat ini dan pergantian jam berikutnya.

Parameter

Nama	Arti
`slug`di path	Slug kota, mis. tokyo.

Contoh permintaan

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

Contoh respons

{
  "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-14T10:01:15",
    "iso": "2026-10-14T10:01:15+09:00",
    "offsetMinutes": 540,
    "offset": "+09:00",
    "utcOffset": "UTC+9",
    "abbreviation": "JST",
    "dst": false,
    "utc": "2026-10-14T01:01:15.054Z"
  },
  "nextTransition": null,
  "tzdata": "2026e"
}

Respons nyata dari server ini.

Koordinat ke zona waktu

GET/api/v1/lookup

Kota terdaftar yang terdekat dengan suatu lintang dan bujur, beserta zona waktunya. Ini perkiraan: batas zona tidak dimodelkan.

Parameter

Nama	Arti
`lat`wajib	Lintang dalam derajat desimal, −90 hingga 90.
`lng`wajib	Bujur dalam derajat desimal, −180 hingga 180.

Contoh permintaan

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

Contoh respons

{
  "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-14T03:01:15",
    "iso": "2026-10-14T03:01:15+02:00",
    "offsetMinutes": 120,
    "offset": "+02:00",
    "utcOffset": "UTC+2",
    "abbreviation": "CEST",
    "dst": true,
    "utc": "2026-10-14T01:01:15.054Z"
  },
  "tzdata": "2026e"
}

Respons nyata dari server ini.

Versi data

GET/api/v1/tzdata

Rilis basis data zona waktu IANA yang menjadi sumber jawaban, dan kapan Hourora terakhir memperbarui datanya.

Parameter

Tanpa parameter.

Contoh permintaan

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

Contoh respons

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

Respons nyata dari server ini.

Kesalahan

Kesalahan juga berupa JSON: status HTTP, kode tetap untuk program Anda, dan pesan untuk manusia.

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

Status	Kode	Kapan
400	`missing_parameter, invalid_parameter`	Ada parameter yang hilang atau tidak dalam format yang diharapkan.
404	`unknown_zone, unknown_city, unknown_country, not_found`	Zona waktu, kota, negara, atau endpoint tidak ditemukan.
429	`rate_limited`	Terlalu banyak permintaan dari klien Anda; tunggu selama jumlah detik di Retry-After.
500	`internal_error`	Terjadi kegagalan di pihak kami. Silakan coba lagi nanti.

Cara kerjanya

Batas dan caching

Setiap klien boleh mengirim hingga 120 permintaan per menit, dengan lonjakan singkat yang diperbolehkan. Di atas itu, API menjawab 429 dengan header Retry-After. Batas ini melindungi layanan gratis; jika Anda butuh lebih, gunakan cache.

Setiap respons menyebutkan berapa lama boleh di-cache (Cache-Control). Waktu sekarang tidak pernah di-cache; daftar zona, detail kota, dan pencarian koordinat selama lima menit; pencarian kota dan konversi untuk waktu tertentu selama satu hari.

Membuat jam? Ambil offset sekali, jalankan jam secara lokal, dan ambil lagi setelah pergantian jam berikutnya yang diberitahukan respons. Tidak perlu polling setiap detik.

Dari mana jawabannya berasal

Offset, singkatan, dan pergantian jam berasal dari salinan basis data zona waktu IANA yang dikompilasi sendiri oleh Hourora, rilis 2026e, untuk 1970–2060. Di luar rentang itu, data bawaan server yang dipakai, yang mungkin lebih lama.

Konversi menangani batas waktu musim panas secara eksplisit: waktu yang terlewati saat jam dimajukan dilaporkan sebagai celah, dan waktu yang terjadi dua kali saat jam dimundurkan dilaporkan sebagai tumpang-tindih, dengan kedua instannya.

Pencarian koordinat mengembalikan kota terdekat dari sekitar 7.200 kota terdaftar beserta zona kota itu. Di dekat perbatasan, di laut, atau di daerah yang jarang penduduknya, hasilnya bisa berbeda dari zona yang sebenarnya berlaku di titik tersebut.

Ketentuan penggunaan

Gratis untuk penggunaan pribadi dan komersial. Tanpa kunci dan tanpa akun.
Atribusi dihargai, tetapi tidak wajib: tautan ke hourora.app di dekat tempat data ditampilkan.
Disediakan apa adanya, tanpa perjanjian tingkat layanan (SLA) atau jaminan ketersediaan. Jangan gunakan di tempat waktu yang salah atau tidak tersedia dapat menimbulkan kerugian.
Jawaban mengikuti IANA tzdata 2026e. Ketika pemerintah mengubah jam mereka, data diperbarui dengan rilis IANA berikutnya.
Versi 1 tetap kompatibel: kolom baru dapat ditambahkan, tidak ada yang dihapus atau diganti namanya. Perubahan yang tidak kompatibel akan hadir sebagai /api/v2.
Harap tetap dalam batas permintaan dan simpan respons dalam cache. Lalu lintas yang menyalahgunakan layanan dapat diblokir.

Pertanyaan

Baik untuk diketahui

Apakah API Hourora benar-benar gratis?

Ya. Tidak ada kunci, tidak ada akun, dan tidak ada paket berbayar. Batas permintaan per klien menjaga layanan tetap adil bagi semua orang.

Bisakah saya memanggilnya dari JavaScript di browser?

Bisa. Setiap endpoint mengizinkan permintaan lintas origin dari situs web mana pun (CORS), dan tidak memerlukan kredensial.

Bagaimana API ini menangani waktu musim panas (DST)?

Setiap jawaban dihitung untuk instan yang tepat dari aturan IANA. Endpoint convert juga memberi tahu Anda jika waktu jam dinding yang diminta tidak ada (jam dimajukan) atau terjadi dua kali (jam dimundurkan).

Seberapa akurat pencarian berdasarkan koordinat?

Hasilnya adalah zona waktu kota terdaftar yang terdekat, yang benar hampir di semua tempat yang dihuni orang. Batas zona tidak dimodelkan, jadi hasilnya bisa salah di dekat perbatasan atau di laut.