Dla programistów

Darmowe API stref czasowych

Ten sam silnik, który napędza Hourora, w postaci zwykłego JSON: czas w dowolnym miejscu, przeliczenia uwzględniające czas letni, każda strefa IANA i jej zmiany czasu. Bez klucza, bez rejestracji.

W skrócie

Bazowy URL: https://hourora.app/api/v1
Format: JSON (UTF-8), tylko żądania GET
Uwierzytelnianie: Brak: bez klucza, bez rejestracji, bez plików cookie
CORS: Otwarte dla każdego źródła, więc można je wywoływać z przeglądarki
Limit żądań: 120 żądań na minutę na klienta
Dane o czasie: IANA tzdata 2026e, skompilowane przez Hourora
Opis do odczytu maszynowego: Dokument OpenAPI 3.1

Wypróbuj na żywo

Wybierz przykład lub edytuj ścieżkę, a następnie wyślij. Żądanie trafia z Twojej przeglądarki bezpośrednio do API.

Odpowiedź

Tutaj pojawi się odpowiedź.

Endpointy

Każdy endpoint odpowiada na GET w formacie JSON. Czasy są w formacie ISO 8601; przesunięcia podawane są w minutach na wschód od UTC (Nowy Jork zimą to −300) oraz jako tekst (−05:00).

Aktualny czas

GET/api/v1/time

Aktualny czas w strefie czasowej lub mieście: czas lokalny, przesunięcie względem UTC, skrót, czas letni i najbliższa zmiana czasu. Bez parametrów: UTC.

Parametry

Nazwa	Znaczenie
`tz`opcjonalny	Nazwa strefy czasowej IANA, np. Europe/London. Aliasy, takie jak Asia/Calcutta, są akceptowane, a odpowiedź zawiera aktualną nazwę.
`city`opcjonalny	Slug miasta zamiast tz, np. london (slugi znajdziesz przez /cities).

Przykładowe żądanie

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

Przykładowa odpowiedź

{
  "zone": "Europe/London",
  "local": "2026-10-15T15:16:54",
  "iso": "2026-10-15T15:16:54+01:00",
  "offsetMinutes": 60,
  "offset": "+01:00",
  "utcOffset": "UTC+1",
  "abbreviation": "BST",
  "dst": true,
  "city": null,
  "utc": "2026-10-15T14:16:54.702Z",
  "unixMs": 1792073814702,
  "date": "2026-10-15",
  "time": "15:16:54",
  "weekday": "Thursday",
  "dayOfYear": 288,
  "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"
}

Rzeczywista odpowiedź tego serwera.

Przelicz czas

GET/api/v1/convert

Czas zegarowy w jednej strefie pokazany w innej. Informuje, gdy czas wypada w luce przy zmianie czasu (nie istnieje) lub w nakładce (występuje dwa razy).

Parametry

Nazwa	Znaczenie
`from`wymagany	Strefa (lub slug miasta), w której odczytywany jest czas.
`to`wymagany	Strefa (lub slug miasta), w której ma zostać pokazany.
`time`opcjonalny	Czas zegarowy w strefie from, YYYY-MM-DDTHH:mm (sekundy opcjonalne, bez przesunięcia), 1970–2060. Domyślnie: teraz.

Przykładowe żądanie

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

Przykładowa odpowiedź

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

Rzeczywista odpowiedź tego serwera.

Lista stref czasowych

GET/api/v1/zones

Każda strefa czasowa IANA z aktualnym przesunięciem względem UTC, skrótem, stanem czasu letniego, krajami i głównym miastem.

Parametry

Nazwa	Znaczenie
`country`opcjonalny	Kod kraju ISO 3166, np. GB, aby zostawić tylko ten kraj.

Przykładowe żądanie

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

Przykładowa odpowiedź

{
  "asOf": "2026-10-15T14:16:54.702Z",
  "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"
    }
  ]
}

Rzeczywista odpowiedź tego serwera; listy skrócone do pierwszych 3 elementów.

Jedna strefa czasowa

GET/api/v1/zones/{id}

Jedna strefa IANA: jej aliasy, kraje i miasta, aktualne przesunięcie, najbliższa zmiana czasu i wszystkie zmiany w danym roku.

Parametry

Nazwa	Znaczenie
`id`w ścieżce	Nazwa strefy IANA; zachowaj ukośnik lub zakoduj go jako %2F.
`year`opcjonalny	Rok, którego zmiany czasu mają zostać wymienione, 1970–2060. Domyślnie: bieżący rok.

Przykładowe żądanie

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

Przykładowa odpowiedź

{
  "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-15T10:16:54",
    "iso": "2026-10-15T10:16:54-04:00",
    "offsetMinutes": -240,
    "offset": "-04:00",
    "utcOffset": "UTC-4",
    "abbreviation": "EDT",
    "dst": true,
    "utc": "2026-10-15T14:16:54.702Z",
    "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"
}

Rzeczywista odpowiedź tego serwera; listy skrócone do pierwszych 3 elementów.

Wyszukiwanie miast

GET/api/v1/cities

Miasta o pasującej nazwie, najpierw najlepiej dopasowane i największe, każde z krajem, współrzędnymi i strefą czasową.

Parametry

Nazwa	Znaczenie
`q`wymagany	Fragment nazwy miasta, znaki diakrytyczne opcjonalne (maks. 80 znaków).
`limit`opcjonalny	Liczba wyników, 1–50. Domyślnie 10.
`country`opcjonalny	Kod kraju ISO 3166, np. GB, aby zostawić tylko ten kraj.

Przykładowe żądanie

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

Przykładowa odpowiedź

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

Rzeczywista odpowiedź tego serwera.

Jedno miasto

GET/api/v1/cities/{slug}

Jedno miasto według sluga, z aktualnym przesunięciem jego strefy czasowej i najbliższą zmianą czasu.

Parametry

Nazwa	Znaczenie
`slug`w ścieżce	Slug miasta, np. tokyo.

Przykładowe żądanie

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

Przykładowa odpowiedź

{
  "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-15T23:16:54",
    "iso": "2026-10-15T23:16:54+09:00",
    "offsetMinutes": 540,
    "offset": "+09:00",
    "utcOffset": "UTC+9",
    "abbreviation": "JST",
    "dst": false,
    "utc": "2026-10-15T14:16:54.702Z"
  },
  "nextTransition": null,
  "tzdata": "2026e"
}

Rzeczywista odpowiedź tego serwera.

Strefa czasowa ze współrzędnych

GET/api/v1/lookup

Najbliższe miasto z listy dla podanej szerokości i długości geograficznej oraz jego strefa czasowa. To przybliżenie: granice stref nie są modelowane.

Parametry

Nazwa	Znaczenie
`lat`wymagany	Szerokość geograficzna w stopniach dziesiętnych, od −90 do 90.
`lng`wymagany	Długość geograficzna w stopniach dziesiętnych, od −180 do 180.

Przykładowe żądanie

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

Przykładowa odpowiedź

{
  "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-15T16:16:54",
    "iso": "2026-10-15T16:16:54+02:00",
    "offsetMinutes": 120,
    "offset": "+02:00",
    "utcOffset": "UTC+2",
    "abbreviation": "CEST",
    "dst": true,
    "utc": "2026-10-15T14:16:54.702Z"
  },
  "tzdata": "2026e"
}

Rzeczywista odpowiedź tego serwera.

Wersja danych

GET/api/v1/tzdata

Z którego wydania bazy stref czasowych IANA pochodzą odpowiedzi i kiedy Hourora ostatnio zaktualizowała dane.

Parametry

Brak parametrów.

Przykładowe żądanie

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

Przykładowa odpowiedź

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

Rzeczywista odpowiedź tego serwera.

Błędy

Błąd to również JSON: status HTTP, stały kod dla programu i komunikat dla ludzi.

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

Status	Kody	Kiedy
400	`missing_parameter, invalid_parameter`	Brakuje parametru lub ma on nieoczekiwaną postać.
404	`unknown_zone, unknown_city, unknown_country, not_found`	Nie ma takiej strefy czasowej, miasta, kraju ani endpointu.
429	`rate_limited`	Zbyt wiele żądań od Twojego klienta; odczekaj liczbę sekund podaną w Retry-After.
500	`internal_error`	Coś poszło nie tak po naszej stronie. Spróbuj ponownie później.

Jak to działa

Limity i pamięć podręczna

Każdy klient może wysłać do 120 żądań na minutę, przy czym dozwolone są krótkie serie. Powyżej tego limitu API odpowiada kodem 429 z nagłówkiem Retry-After. Limit chroni darmową usługę; jeśli potrzebujesz więcej, korzystaj z pamięci podręcznej.

Każda odpowiedź określa, jak długo można ją przechowywać w pamięci podręcznej (Cache-Control). Aktualny czas nigdy nie jest buforowany; listy stref, szczegóły miast i wyszukiwanie po współrzędnych – przez pięć minut; wyszukiwanie miast i przeliczenia konkretnego czasu – przez dobę.

Budujesz zegar? Pobierz przesunięcie raz, odliczaj lokalnie i pobierz je ponownie po najbliższej zmianie czasu, o której informuje odpowiedź. Nie trzeba odpytywać API co sekundę.

Skąd pochodzą odpowiedzi

Przesunięcia, skróty i zmiany czasu pochodzą z własnej, skompilowanej przez Hourora kopii bazy stref czasowych IANA, wydanie 2026e, dla lat 1970–2060. Poza tym zakresem używane są wbudowane dane serwera, które mogą być starsze.

Przeliczenia jawnie rozstrzygają przypadki brzegowe zmiany czasu: czas pomijany przy przestawieniu zegarów do przodu jest zgłaszany jako luka (gap), a czas występujący dwa razy przy cofnięciu zegarów – jako nakładka (overlap), z obydwoma momentami.

Wyszukiwanie po współrzędnych zwraca najbliższe z około 7200 miast z listy i strefę tego miasta. W pobliżu granicy, na morzu lub na słabo zaludnionym obszarze może się ona różnić od strefy faktycznie obowiązującej w danym punkcie.

Warunki korzystania

Bezpłatne do użytku prywatnego i komercyjnego. Bez klucza i bez konta.
Podanie źródła jest mile widziane, ale nie wymagane: link do hourora.app w pobliżu miejsca, w którym wyświetlane są dane.
Udostępniane w stanie „takim, jakie jest”, bez umowy SLA ani gwarancji dostępności. Nie używaj go tam, gdzie błędny lub brakujący czas mógłby wyrządzić szkodę.
Odpowiedzi są zgodne z IANA tzdata 2026e. Gdy rządy zmieniają czas, dane są aktualizowane wraz z kolejnym wydaniem IANA.
Wersja 1 pozostaje kompatybilna: mogą dochodzić nowe pola, nic nie jest usuwane ani nie zmienia nazwy. Zmiany niekompatybilne pojawiłyby się jako /api/v2.
Prosimy o przestrzeganie limitu żądań i buforowanie odpowiedzi. Ruch nadużywający usługi może być blokowany.

Pytania

Warto wiedzieć

Czy API Hourora jest naprawdę darmowe?

Tak. Nie ma klucza, konta ani płatnego planu. Limit żądań na klienta sprawia, że usługa pozostaje uczciwa dla wszystkich.

Czy mogę wywoływać je z JavaScriptu w przeglądarce?

Tak. Każdy endpoint akceptuje żądania cross-origin z dowolnej witryny (CORS) i nie wymaga danych uwierzytelniających.

Jak API obsługuje czas letni?

Każda odpowiedź jest obliczana dla dokładnego momentu na podstawie reguł IANA. Endpoint convert informuje też, gdy żądany czas zegarowy nie istnieje (przestawienie zegarów do przodu) lub występuje dwa razy (cofnięcie zegarów).

Jak dokładne jest wyszukiwanie po współrzędnych?

Zwraca strefę czasową najbliższego miasta z listy, co jest poprawne niemal wszędzie, gdzie mieszkają ludzie. Nie modeluje granic stref, więc może się mylić w pobliżu granicy lub na morzu.