Per sviluppatori

Un’API per i fusi orari gratuita

Lo stesso motore che fa funzionare Hourora, in semplice JSON: l’ora ovunque, conversioni che tengono conto dell’ora legale, ogni fuso IANA e i suoi cambi d’ora. Senza chiave, senza registrazione.

In breve

URL di base: https://hourora.app/api/v1
Formato: JSON (UTF-8), solo richieste GET
Autenticazione: Nessuna: niente chiave, niente registrazione, niente cookie
CORS: Aperta a ogni origine, quindi puoi chiamarla dal browser
Limite di frequenza: 120 richieste al minuto per client
Dati orari: IANA tzdata 2026e, compilato da Hourora
Descrizione leggibile dalle macchine: Documento OpenAPI 3.1

Provala dal vivo

Scegli un esempio o modifica il percorso, poi invialo. La richiesta va direttamente dal tuo browser all’API.

Risposta

La risposta compare qui.

Gli endpoint

Ogni endpoint risponde a GET con JSON. Gli orari sono in ISO 8601; gli scarti sono minuti a est di UTC (New York in inverno è −300) e sono scritti anche come testo (−05:00).

Ora attuale

GET/api/v1/time

L’ora attuale in un fuso orario o in una città: ora locale, scarto da UTC, abbreviazione, ora legale e prossimo cambio d’ora. Senza parametri: UTC.

Parametri

Nome	Significato
`tz`facoltativo	Nome IANA del fuso orario, ad es. Europe/London. Gli alias come Asia/Calcutta sono accettati e la risposta usa il nome attuale.
`city`facoltativo	Slug della città al posto di tz, ad es. london (trova gli slug con /cities).

Richiesta di esempio

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

Risposta di esempio

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

Risposta reale di questo server.

Converti un orario

GET/api/v1/convert

Un orario di un fuso mostrato in un altro. Segnala quando l’orario cade in un buco dell’ora legale (non esiste) o in una sovrapposizione (si verifica due volte).

Parametri

Nome	Significato
`from`obbligatorio	Fuso (o slug della città) in cui si legge l’orario.
`to`obbligatorio	Fuso (o slug della città) in cui mostrarlo.
`time`facoltativo	Orario nel fuso from, YYYY-MM-DDTHH:mm (secondi facoltativi, senza scarto), 1970–2060. Predefinito: adesso.

Richiesta di esempio

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

Risposta di esempio

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

Risposta reale di questo server.

Elenca i fusi orari

GET/api/v1/zones

Ogni fuso orario IANA con scarto attuale da UTC, abbreviazione, stato dell’ora legale, paesi e città principale.

Parametri

Nome	Significato
`country`facoltativo	Codice paese ISO 3166, ad es. GB, per tenere solo quel paese.

Richiesta di esempio

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

Risposta di esempio

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

Risposta reale di questo server; elenchi ridotti ai primi 3 elementi.

Un fuso orario

GET/api/v1/zones/{id}

Un fuso IANA: i suoi alias, paesi e città, lo scarto attuale, il prossimo cambio d’ora e tutti i cambi di un dato anno.

Parametri

Nome	Significato
`id`nel percorso	Nome IANA del fuso; mantieni la barra o codificala come %2F.
`year`facoltativo	Anno di cui elencare i cambi d’ora, 1970–2060. Predefinito: quest’anno.

Richiesta di esempio

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

Risposta di esempio

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

Risposta reale di questo server; elenchi ridotti ai primi 3 elementi.

Cerca città

GET/api/v1/cities

Le città il cui nome corrisponde, prima le corrispondenze migliori e le città più grandi, ciascuna con paese, coordinate e fuso orario.

Parametri

Nome	Significato
`q`obbligatorio	Parte del nome di una città, accenti facoltativi (al massimo 80 caratteri).
`limit`facoltativo	Quanti risultati, 1–50. Predefinito: 10.
`country`facoltativo	Codice paese ISO 3166, ad es. GB, per tenere solo quel paese.

Richiesta di esempio

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

Risposta di esempio

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

Risposta reale di questo server.

Una città

GET/api/v1/cities/{slug}

Una città tramite il suo slug, con lo scarto attuale del suo fuso orario e il prossimo cambio d’ora.

Parametri

Nome	Significato
`slug`nel percorso	Slug della città, ad es. tokyo.

Richiesta di esempio

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

Risposta di esempio

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

Risposta reale di questo server.

Dalle coordinate al fuso orario

GET/api/v1/lookup

La città elencata più vicina a una latitudine e longitudine, e il suo fuso orario. Un’approssimazione: i confini dei fusi non sono modellati.

Parametri

Nome	Significato
`lat`obbligatorio	Latitudine in gradi decimali, da −90 a 90.
`lng`obbligatorio	Longitudine in gradi decimali, da −180 a 180.

Richiesta di esempio

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

Risposta di esempio

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

Risposta reale di questo server.

Versione dei dati

GET/api/v1/tzdata

Da quale versione del database IANA dei fusi orari provengono le risposte e quando Hourora ha aggiornato i dati l’ultima volta.

Parametri

Nessun parametro.

Richiesta di esempio

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

Risposta di esempio

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

Risposta reale di questo server.

Errori

Anche un errore è JSON: lo stato HTTP, un codice stabile per il tuo programma e un messaggio per le persone.

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

Stato	Codici	Quando
400	`missing_parameter, invalid_parameter`	Un parametro manca o non è nella forma prevista.
404	`unknown_zone, unknown_city, unknown_country, not_found`	Fuso orario, città, paese o endpoint inesistente.
429	`rate_limited`	Troppe richieste dal tuo client; attendi i secondi indicati in Retry-After.
500	`internal_error`	Qualcosa non ha funzionato da parte nostra. Riprova più tardi.

Come funziona

Limiti e cache

Ogni client può inviare fino a 120 richieste al minuto, con brevi picchi consentiti. Oltre questa soglia l’API risponde 429 con un header Retry-After. Il limite protegge un servizio gratuito; se ti serve di più, usa la cache.

Ogni risposta indica per quanto tempo può essere memorizzata in cache (Cache-Control). L’ora attuale non viene mai memorizzata; elenchi dei fusi, dettagli delle città e ricerche per coordinate per cinque minuti; ricerche di città e conversioni di un orario dato per un giorno.

Stai costruendo un orologio? Recupera lo scarto una volta, fai avanzare l’orologio in locale e recuperalo di nuovo dopo il prossimo cambio d’ora indicato nella risposta. Non serve interrogare l’API ogni secondo.

Da dove provengono le risposte

Scarti, abbreviazioni e cambi d’ora provengono dalla copia compilata da Hourora del database IANA dei fusi orari, versione 2026e, per il periodo 1970–2060. Al di fuori di questo intervallo si usano i dati integrati del server, che possono essere meno recenti.

Le conversioni risolvono esplicitamente i casi limite dell’ora legale: un orario saltato quando le lancette vanno avanti viene segnalato come buco, e un orario che si verifica due volte quando tornano indietro viene segnalato come sovrapposizione, con entrambi gli istanti.

La ricerca per coordinate restituisce la più vicina di circa 7200 città elencate e il fuso di quella città. Vicino a un confine, in mare o in una zona poco popolata può differire dal fuso effettivamente in vigore in quel punto.

Condizioni d’uso

Gratuita per uso personale e commerciale. Senza chiave e senza account.
L’attribuzione è gradita, non obbligatoria: un link a hourora.app vicino a dove compaiono i dati.
Fornita così com’è, senza accordo sul livello di servizio né garanzia di disponibilità. Non usarla dove un orario errato o mancante potrebbe causare danni.
Le risposte seguono IANA tzdata 2026e. Quando i governi cambiano i loro orari, i dati vengono aggiornati con la successiva versione IANA.
La versione 1 resta compatibile: possono essere aggiunti nuovi campi, nulla viene rimosso o rinominato. Le modifiche incompatibili arriverebbero come /api/v2.
Rispetta il limite di frequenza e memorizza le risposte in cache. Il traffico abusivo può essere bloccato.

Domande

Utile da sapere

L’API di Hourora è davvero gratuita?

Sì. Non ci sono chiavi, account né piani a pagamento. Un limite di frequenza per client mantiene il servizio equo per tutti.

Posso chiamarla da JavaScript nel browser?

Sì. Ogni endpoint consente richieste cross-origin da qualsiasi sito web (CORS) e non servono credenziali.

Come gestisce l’ora legale?

Ogni risposta è calcolata per l’istante esatto secondo le regole IANA. L’endpoint convert indica anche quando un orario richiesto non esiste (le lancette vanno avanti) o si verifica due volte (le lancette tornano indietro).

Quanto è precisa la ricerca per coordinate?

Restituisce il fuso orario della città elencata più vicina, che è corretto quasi ovunque viva qualcuno. Non modella i confini dei fusi, quindi può sbagliare vicino a un confine o in mare.