Pentru dezvoltatori

Un API pentru fusuri orare gratuit

Același motor pe care rulează Hourora, ca JSON simplu: ora oriunde, conversii care țin cont de ora de vară, fiecare fus IANA și schimbările lui de oră. Fără cheie, fără înregistrare.

Pe scurt

URL de bază: https://hourora.app/api/v1
Format: JSON (UTF-8), doar cereri GET
Autentificare: Niciuna: fără cheie, fără înregistrare, fără cookie-uri
CORS: Deschis pentru orice origine, deci îl poți apela din browser
Limită de cereri: 120 de cereri pe minut pentru fiecare client
Date despre oră: IANA tzdata 2026e, compilat de Hourora
Descriere pentru programe: Document OpenAPI 3.1

Încearcă în timp real

Alege un exemplu sau editează calea, apoi trimite cererea. Cererea pleacă din browserul tău direct către API.

Răspuns

Răspunsul apare aici.

Endpointurile

Fiecare endpoint răspunde la GET cu JSON. Orele sunt în format ISO 8601; decalajele sunt în minute la est de UTC (New York iarna are −300) și sunt scrise și ca text (−05:00).

Ora curentă

GET/api/v1/time

Ora curentă într-un fus orar sau oraș: ora locală, decalajul față de UTC, abrevierea, ora de vară și următoarea schimbare a orei. Fără parametri: UTC.

Parametri

Nume	Semnificație
`tz`opțional	Numele fusului orar IANA, de ex. Europe/London. Aliasurile precum Asia/Calcutta sunt acceptate, iar răspunsul folosește numele actual.
`city`opțional	Slugul orașului în loc de tz, de ex. london (găsești sluguri cu /cities).

Exemplu de cerere

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

Exemplu de răspuns

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

Răspuns real de la acest server.

Convertește o oră

GET/api/v1/convert

O oră de ceas dintr-un fus afișată în altul. Semnalează când ora cade într-un gol de la schimbarea orei (nu există) sau într-o suprapunere (apare de două ori).

Parametri

Nume	Semnificație
`from`obligatoriu	Fusul (sau slugul orașului) în care este citită ora.
`to`obligatoriu	Fusul (sau slugul orașului) în care este afișată.
`time`opțional	Ora de ceas în fusul from, YYYY-MM-DDTHH:mm (secundele sunt opționale, fără decalaj), 1970–2060. Implicit: acum.

Exemplu de cerere

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

Exemplu de răspuns

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

Răspuns real de la acest server.

Lista fusurilor orare

GET/api/v1/zones

Fiecare fus orar IANA, cu decalajul curent față de UTC, abrevierea, starea orei de vară, țările și orașul principal.

Parametri

Nume	Semnificație
`country`opțional	Codul de țară ISO 3166, de ex. GB, pentru a păstra doar acea țară.

Exemplu de cerere

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

Exemplu de răspuns

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

Răspuns real de la acest server; listele sunt scurtate la primele 3 elemente.

Un fus orar

GET/api/v1/zones/{id}

Un fus IANA: aliasurile, țările și orașele sale, decalajul actual, următoarea schimbare a orei și toate schimbările dintr-un an dat.

Parametri

Nume	Semnificație
`id`în cale	Numele fusului IANA; păstrează bara oblică sau codific-o ca %2F.
`year`opțional	Anul pentru care se listează schimbările orei, 1970–2060. Implicit: anul curent.

Exemplu de cerere

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

Exemplu de răspuns

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

Răspuns real de la acest server; listele sunt scurtate la primele 3 elemente.

Caută orașe

GET/api/v1/cities

Orașele al căror nume se potrivește, întâi cele mai bune potriviri și cele mai mari orașe, fiecare cu țara, coordonatele și fusul orar.

Parametri

Nume	Semnificație
`q`obligatoriu	O parte din numele orașului, diacriticele sunt opționale (cel mult 80 de caractere).
`limit`opțional	Câte rezultate, 1–50. Implicit 10.
`country`opțional	Codul de țară ISO 3166, de ex. GB, pentru a păstra doar acea țară.

Exemplu de cerere

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

Exemplu de răspuns

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

Răspuns real de la acest server.

Un oraș

GET/api/v1/cities/{slug}

Un oraș după slug, cu decalajul actual al fusului său orar și următoarea schimbare a orei.

Parametri

Nume	Semnificație
`slug`în cale	Slugul orașului, de ex. tokyo.

Exemplu de cerere

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

Exemplu de răspuns

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

Răspuns real de la acest server.

Fus orar după coordonate

GET/api/v1/lookup

Cel mai apropiat oraș din listă față de o latitudine și o longitudine, plus fusul său orar. O aproximare: granițele fusurilor nu sunt modelate.

Parametri

Nume	Semnificație
`lat`obligatoriu	Latitudinea în grade zecimale, de la −90 la 90.
`lng`obligatoriu	Longitudinea în grade zecimale, de la −180 la 180.

Exemplu de cerere

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

Exemplu de răspuns

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

Răspuns real de la acest server.

Versiunea datelor

GET/api/v1/tzdata

Din ce versiune a bazei de date IANA a fusurilor orare provin răspunsurile și când și-a actualizat Hourora ultima dată datele.

Parametri

Fără parametri.

Exemplu de cerere

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

Exemplu de răspuns

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

Răspuns real de la acest server.

Erori

Și o eroare este JSON: statusul HTTP, un cod stabil pentru programul tău și un mesaj pentru oameni.

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

Status	Coduri	Când
400	`missing_parameter, invalid_parameter`	Un parametru lipsește sau nu are forma așteptată.
404	`unknown_zone, unknown_city, unknown_country, not_found`	Nu există un astfel de fus orar, oraș, țară sau endpoint.
429	`rate_limited`	Prea multe cereri de la clientul tău; așteaptă numărul de secunde din Retry-After.
500	`internal_error`	Ceva nu a funcționat la noi. Te rugăm să încerci din nou mai târziu.

Cum funcționează

Limite și cache

Fiecare client poate trimite până la 120 de cereri pe minut, cu scurte rafale permise. Peste această limită, API-ul răspunde cu 429 și un antet Retry-After. Limita protejează un serviciu gratuit; dacă ai nevoie de mai mult, folosește cache-ul.

Fiecare răspuns indică cât timp poate fi păstrat în cache (Cache-Control). Ora curentă nu este pusă niciodată în cache; listele de fusuri, detaliile orașelor și căutările după coordonate, timp de cinci minute; căutările de orașe și conversiile unei ore date, timp de o zi.

Construiești un ceas? Preia decalajul o dată, avansează ora local și preia-l din nou după următoarea schimbare a orei, despre care te anunță răspunsul. Nu e nevoie să interoghezi API-ul în fiecare secundă.

De unde provin răspunsurile

Decalajele, abrevierile și schimbările orei provin din copia compilată de Hourora a bazei de date IANA a fusurilor orare, versiunea 2026e, pentru 1970–2060. În afara acestui interval se folosesc datele integrate ale serverului, care pot fi mai vechi.

Conversiile tratează explicit marginile orei de vară: o oră sărită când ceasurile se dau înainte este raportată ca gol, iar o oră care apare de două ori când ceasurile se dau înapoi este raportată ca suprapunere, cu ambele momente.

Căutarea după coordonate returnează cel mai apropiat dintre aproximativ 7.200 de orașe listate și fusul acelui oraș. Lângă o graniță, pe mare sau într-o zonă slab populată, acesta poate diferi de fusul care se aplică efectiv în acel punct.

Condiții de utilizare

Gratuit pentru uz personal și comercial. Fără cheie și fără cont.
Menționarea sursei este apreciată, nu obligatorie: un link către hourora.app lângă locul unde apar datele.
Oferit ca atare, fără acord privind nivelul serviciului (SLA) sau garanție de disponibilitate. Nu-l folosi acolo unde o oră greșită sau lipsă ar putea provoca daune.
Răspunsurile urmează IANA tzdata 2026e. Când guvernele schimbă ora, datele sunt actualizate odată cu următoarea versiune IANA.
Versiunea 1 rămâne compatibilă: pot fi adăugate câmpuri noi, nimic nu este eliminat sau redenumit. Modificările incompatibile ar veni ca /api/v2.
Te rugăm să respecți limita de cereri și să păstrezi răspunsurile în cache. Traficul abuziv poate fi blocat.

Întrebări

Bine de știut

Este API-ul Hourora chiar gratuit?

Da. Nu există cheie, cont sau plan plătit. O limită de cereri pentru fiecare client păstrează serviciul echitabil pentru toți.

Îl pot apela din JavaScript în browser?

Da. Fiecare endpoint permite cereri cross-origin de pe orice site (CORS) și nu sunt necesare credențiale.

Cum gestionează ora de vară?

Fiecare răspuns este calculat pentru momentul exact pe baza regulilor IANA. Endpointul convert îți spune și când o oră de ceas cerută nu există (trecerea la ora de vară) sau apare de două ori (revenirea la ora de iarnă).

Cât de precisă este căutarea după coordonate?

Returnează fusul orar al celui mai apropiat oraș din listă, care este corect aproape peste tot unde locuiesc oameni. Nu modelează granițele fusurilor, așa că poate greși lângă o graniță sau pe mare.