Geliştiriciler için

Ücretsiz bir saat dilimi API’si

Hourora’yı çalıştıran motorun aynısı, sade JSON olarak: her yerde saat, yaz saatini bilen dönüştürmeler, tüm IANA saat dilimleri ve saat değişiklikleri. Anahtar yok, kayıt yok.

Bir bakışta

Temel URL: https://hourora.app/api/v1
Biçim: JSON (UTF-8), yalnızca GET istekleri
Kimlik doğrulama: Yok: anahtar yok, kayıt yok, çerez yok
CORS: Tüm kaynaklara açık; tarayıcıdan çağırabilirsiniz
İstek sınırı: İstemci başına dakikada 120 istek
Saat verisi: IANA tzdata 2026e, Hourora tarafından derlendi
Makine tarafından okunabilir tanım: OpenAPI 3.1 belgesi

Canlı deneyin

Bir örnek seçin veya yolu düzenleyin, ardından gönderin. İstek tarayıcınızdan doğrudan API’ye gider.

Yanıt

Yanıt burada görünür.

Uç noktalar

Her uç nokta GET isteğine JSON ile yanıt verir. Saatler ISO 8601 biçimindedir; ofsetler UTC’nin doğusundaki dakika cinsindendir (New York kışın −300) ve ayrıca metin olarak da yazılır (−05:00).

Şu anki saat

GET/api/v1/time

Bir saat dilimi veya şehirdeki şu anki saat: yerel saat, UTC farkı, kısaltma, yaz saati ve bir sonraki saat değişikliği. Parametre verilmezse: UTC.

Parametreler

Ad	Anlamı
`tz`isteğe bağlı	IANA saat dilimi adı, ör. Europe/London. Asia/Calcutta gibi takma adlar kabul edilir ve güncel adla yanıtlanır.
`city`isteğe bağlı	tz yerine şehrin kısa adı (slug), ör. london (kısa adları /cities ile bulun).

Örnek istek

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

Örnek yanıt

{
  "zone": "Europe/London",
  "local": "2026-10-13T22:55:51",
  "iso": "2026-10-13T22:55:51+01:00",
  "offsetMinutes": 60,
  "offset": "+01:00",
  "utcOffset": "UTC+1",
  "abbreviation": "BST",
  "dst": true,
  "city": null,
  "utc": "2026-10-13T21:55:51.712Z",
  "unixMs": 1791928551712,
  "date": "2026-10-13",
  "time": "22:55:51",
  "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"
}

Bu sunucudan gerçek yanıt.

Saat dönüştürme

GET/api/v1/convert

Bir saat dilimindeki duvar saatinin başka bir dilimdeki karşılığı. Saatin yaz saati boşluğuna (hiç yaşanmaz) veya çakışmasına (iki kez yaşanır) denk geldiğini bildirir.

Parametreler

Ad	Anlamı
`from`zorunlu	Saatin okunduğu dilim (veya şehrin kısa adı).
`to`zorunlu	Saatin gösterileceği dilim (veya şehrin kısa adı).
`time`isteğe bağlı	from dilimindeki duvar saati, YYYY-MM-DDTHH:mm (saniye isteğe bağlı, ofset yok), 1970–2060. Varsayılan: şimdi.

Örnek istek

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

Örnek yanıt

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

Bu sunucudan gerçek yanıt.

Saat dilimlerini listele

GET/api/v1/zones

Tüm IANA saat dilimleri; şu anki UTC farkı, kısaltması, yaz saati durumu, ülkeleri ve ana şehriyle.

Parametreler

Ad	Anlamı
`country`isteğe bağlı	ISO 3166 ülke kodu, ör. GB; yalnızca o ülkeyi tutmak için.

Örnek istek

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

Örnek yanıt

{
  "asOf": "2026-10-13T21:55:51.712Z",
  "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"
    }
  ]
}

Bu sunucudan gerçek yanıt; listeler ilk 3 öğeyle sınırlandırıldı.

Tek bir saat dilimi

GET/api/v1/zones/{id}

Tek bir IANA saat dilimi: takma adları, ülkeleri ve şehirleri, şu anki farkı, bir sonraki saat değişikliği ve belirli bir yıldaki tüm değişiklikler.

Parametreler

Ad	Anlamı
`id`yolda	IANA dilim adı; eğik çizgiyi koruyun veya %2F olarak kodlayın.
`year`isteğe bağlı	Saat değişikliklerinin listeleneceği yıl, 1970–2060. Varsayılan: bu yıl.

Örnek istek

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

Örnek yanıt

{
  "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:51",
    "iso": "2026-10-13T17:55:51-04:00",
    "offsetMinutes": -240,
    "offset": "-04:00",
    "utcOffset": "UTC-4",
    "abbreviation": "EDT",
    "dst": true,
    "utc": "2026-10-13T21:55:51.712Z",
    "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"
}

Bu sunucudan gerçek yanıt; listeler ilk 3 öğeyle sınırlandırıldı.

Şehir ara

GET/api/v1/cities

Adı eşleşen şehirler; en iyi eşleşmeler ve en büyük şehirler önce, her biri ülkesi, koordinatları ve saat dilimiyle.

Parametreler

Ad	Anlamı
`q`zorunlu	Şehir adının bir kısmı, aksanlar isteğe bağlı (en fazla 80 karakter).
`limit`isteğe bağlı	Sonuç sayısı, 1–50. Varsayılan 10.
`country`isteğe bağlı	ISO 3166 ülke kodu, ör. GB; yalnızca o ülkeyi tutmak için.

Örnek istek

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

Örnek yanıt

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

Bu sunucudan gerçek yanıt.

Tek bir şehir

GET/api/v1/cities/{slug}

Kısa adıyla (slug) tek bir şehir; saat diliminin şu anki farkı ve bir sonraki saat değişikliğiyle.

Parametreler

Ad	Anlamı
`slug`yolda	Şehrin kısa adı, ör. tokyo.

Örnek istek

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

Örnek yanıt

{
  "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:51",
    "iso": "2026-10-14T06:55:51+09:00",
    "offsetMinutes": 540,
    "offset": "+09:00",
    "utcOffset": "UTC+9",
    "abbreviation": "JST",
    "dst": false,
    "utc": "2026-10-13T21:55:51.712Z"
  },
  "nextTransition": null,
  "tzdata": "2026e"
}

Bu sunucudan gerçek yanıt.

Koordinattan saat dilimine

GET/api/v1/lookup

Bir enlem ve boylama en yakın listelenmiş şehir ve onun saat dilimi. Yaklaşık bir sonuçtur: dilim sınırları modellenmez.

Parametreler

Ad	Anlamı
`lat`zorunlu	Ondalık derece cinsinden enlem, −90 ile 90 arası.
`lng`zorunlu	Ondalık derece cinsinden boylam, −180 ile 180 arası.

Örnek istek

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

Örnek yanıt

{
  "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:51",
    "iso": "2026-10-13T23:55:51+02:00",
    "offsetMinutes": 120,
    "offset": "+02:00",
    "utcOffset": "UTC+2",
    "abbreviation": "CEST",
    "dst": true,
    "utc": "2026-10-13T21:55:51.712Z"
  },
  "tzdata": "2026e"
}

Bu sunucudan gerçek yanıt.

Veri sürümü

GET/api/v1/tzdata

Yanıtların hangi IANA saat dilimi veritabanı sürümüne dayandığı ve Hourora’nın verilerini en son ne zaman güncellediği.

Parametreler

Parametre yok.

Örnek istek

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

Örnek yanıt

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

Bu sunucudan gerçek yanıt.

Hatalar

Hata da JSON’dır: HTTP durumu, programınız için sabit bir kod ve insanlar için bir mesaj.

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

Durum	Kodlar	Ne zaman
400	`missing_parameter, invalid_parameter`	Bir parametre eksik veya beklenen biçimde değil.
404	`unknown_zone, unknown_city, unknown_country, not_found`	Böyle bir saat dilimi, şehir, ülke veya uç nokta yok.
429	`rate_limited`	İstemcinizden çok fazla istek geldi; Retry-After içindeki saniye kadar bekleyin.
500	`internal_error`	Bizim tarafımızda bir sorun oluştu. Lütfen daha sonra yeniden deneyin.

Nasıl çalışır

Sınırlar ve önbellek

Her istemci, kısa ani artışlara izin verilerek dakikada en fazla 120 istek gönderebilir. Bunun ötesinde API, Retry-After başlığıyla 429 yanıtı verir. Sınır ücretsiz bir hizmeti korur; daha fazlasına ihtiyacınız varsa önbelleğe alın.

Her yanıt ne kadar süre önbellekte tutulabileceğini belirtir (Cache-Control). Şu anki saat asla önbelleğe alınmaz; dilim listeleri, şehir ayrıntıları ve koordinat sorguları beş dakika, şehir aramaları ve belirli bir saatin dönüştürmeleri bir gün önbellekte tutulabilir.

Saat mi yapıyorsunuz? Ofseti bir kez alın, yerel olarak ilerletin ve yanıtın bildirdiği bir sonraki saat değişikliğinden sonra yeniden alın. Her saniye sorgulamaya gerek yok.

Yanıtlar nereden geliyor

Ofsetler, kısaltmalar ve saat değişiklikleri, Hourora’nın IANA saat dilimi veritabanından kendi derlediği kopyadan (sürüm 2026e, 1970–2060) gelir. Bu aralığın dışında sunucunun yerleşik verisi kullanılır; bu veri daha eski olabilir.

Dönüştürmeler yaz saati sınırlarını açıkça çözer: saatler ileri alındığında atlanan bir saat boşluk olarak, saatler geri alındığında iki kez yaşanan bir saat ise her iki anla birlikte çakışma olarak bildirilir.

Koordinat sorgusu, listelenmiş yaklaşık 7.200 şehirden en yakınını ve o şehrin saat dilimini döndürür. Sınıra yakın, denizde veya seyrek nüfuslu bir bölgede, o noktada gerçekte geçerli olan dilimden farklı olabilir.

Kullanım koşulları

Kişisel ve ticari kullanım için ücretsiz. Anahtar ve hesap gerekmez.
Kaynak göstermek zorunlu değil ama memnuniyetle karşılanır: verilerin göründüğü yerin yakınında hourora.app bağlantısı.
Olduğu gibi sunulur; hizmet düzeyi sözleşmesi veya erişilebilirlik garantisi yoktur. Yanlış veya eksik bir saatin zarara yol açabileceği yerlerde kullanmayın.
Yanıtlar IANA tzdata 2026e sürümüne dayanır. Hükümetler saat uygulamalarını değiştirdiğinde veriler bir sonraki IANA sürümüyle güncellenir.
Sürüm 1 uyumlu kalır: yeni alanlar eklenebilir, hiçbir şey kaldırılmaz veya yeniden adlandırılmaz. Uyumluluğu bozan değişiklikler /api/v2 olarak gelir.
Lütfen istek sınırına uyun ve yanıtları önbelleğe alın. Kötüye kullanım niteliğindeki trafik engellenebilir.

Sorular

Bilmekte fayda var

Hourora API’si gerçekten ücretsiz mi?

Evet. Anahtar, hesap veya ücretli paket yok. İstemci başına istek sınırı, hizmetin herkes için adil kalmasını sağlar.

Tarayıcıda JavaScript ile çağırabilir miyim?

Evet. Her uç nokta herhangi bir web sitesinden gelen çapraz kaynak isteklerine (CORS) izin verir ve kimlik bilgisi gerekmez.

Yaz saatini nasıl ele alıyor?

Her yanıt, IANA kurallarına göre tam o an için hesaplanır. convert uç noktası ayrıca istenen duvar saatinin hiç yaşanmadığını (saatler ileri alındığında) veya iki kez yaşandığını (saatler geri alındığında) bildirir.

Koordinat sorgusu ne kadar doğru?

Listelenmiş en yakın şehrin saat dilimini döndürür; bu, insanların yaşadığı hemen her yerde doğrudur. Dilim sınırlarını modellemediği için sınıra yakın yerlerde veya denizde yanlış olabilir.