Pour les développeurs

Une API de fuseaux horaires gratuite

Le moteur qui fait tourner Hourora, en JSON simple : l’heure partout, des conversions qui tiennent compte de l’heure d’été, tous les fuseaux IANA et leurs changements d’heure. Sans clé, sans inscription.

En bref

URL de base: https://hourora.app/api/v1
Format: JSON (UTF-8), requêtes GET uniquement
Authentification: Aucune : pas de clé, pas d’inscription, pas de cookies
CORS: Ouverte à toutes les origines : vous pouvez l’appeler depuis un navigateur
Limite de requêtes: 120 requêtes par minute et par client
Données horaires: IANA tzdata 2026e, compilée par Hourora
Description lisible par machine: Document OpenAPI 3.1

Essayer en direct

Choisissez un exemple ou modifiez le chemin, puis envoyez. La requête part directement de votre navigateur vers l’API.

Réponse

La réponse s’affiche ici.

Les endpoints

Chaque endpoint répond aux requêtes GET en JSON. Les heures sont au format ISO 8601 ; les décalages sont exprimés en minutes à l’est d’UTC (New York en hiver : −300) et aussi sous forme de texte (−05:00).

Heure actuelle

GET/api/v1/time

L’heure actuelle dans un fuseau horaire ou une ville : heure locale, décalage par rapport à UTC, abréviation, heure d’été et prochain changement d’heure. Sans paramètre : UTC.

Paramètres

Nom	Signification
`tz`facultatif	Nom de fuseau horaire IANA, par exemple Europe/London. Les alias comme Asia/Calcutta sont acceptés, et la réponse utilise le nom actuel.
`city`facultatif	Slug de ville à la place de tz, par exemple london (trouvez les slugs avec /cities).

Exemple de requête

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

Exemple de réponse

{
  "zone": "Europe/London",
  "local": "2026-10-14T01:56:03",
  "iso": "2026-10-14T01:56:03+01:00",
  "offsetMinutes": 60,
  "offset": "+01:00",
  "utcOffset": "UTC+1",
  "abbreviation": "BST",
  "dst": true,
  "city": null,
  "utc": "2026-10-14T00:56:03.296Z",
  "unixMs": 1791939363296,
  "date": "2026-10-14",
  "time": "01:56:03",
  "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éponse réelle de ce serveur.

Convertir une heure

GET/api/v1/convert

Une heure locale d’un fuseau affichée dans un autre. Signale quand l’heure tombe dans un trou du changement d’heure (elle n’existe pas) ou dans un chevauchement (elle a lieu deux fois).

Paramètres

Nom	Signification
`from`obligatoire	Fuseau (ou slug de ville) dans lequel l’heure est lue.
`to`obligatoire	Fuseau (ou slug de ville) dans lequel l’afficher.
`time`facultatif	Heure locale dans le fuseau from, AAAA-MM-JJTHH:mm (secondes facultatives, sans décalage), 1970–2060. Par défaut : maintenant.

Exemple de requête

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

Exemple de réponse

{
  "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éponse réelle de ce serveur.

Liste des fuseaux horaires

GET/api/v1/zones

Tous les fuseaux horaires IANA avec leur décalage actuel par rapport à UTC, leur abréviation, leur état d’heure d’été, leurs pays et leur ville principale.

Paramètres

Nom	Signification
`country`facultatif	Code pays ISO 3166, par exemple GB, pour ne garder que ce pays.

Exemple de requête

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

Exemple de réponse

{
  "asOf": "2026-10-14T00:56:03.296Z",
  "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éponse réelle de ce serveur ; listes réduites aux 3 premiers éléments.

Un fuseau horaire

GET/api/v1/zones/{id}

Un fuseau IANA : ses alias, pays et villes, son décalage actuel, le prochain changement d’heure et tous les changements d’une année donnée.

Paramètres

Nom	Signification
`id`dans le chemin	Nom de fuseau IANA ; gardez la barre oblique ou encodez-la en %2F.
`year`facultatif	Année dont il faut lister les changements d’heure, 1970–2060. Par défaut : l’année en cours.

Exemple de requête

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

Exemple de réponse

{
  "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:56:03",
    "iso": "2026-10-13T20:56:03-04:00",
    "offsetMinutes": -240,
    "offset": "-04:00",
    "utcOffset": "UTC-4",
    "abbreviation": "EDT",
    "dst": true,
    "utc": "2026-10-14T00:56:03.296Z",
    "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éponse réelle de ce serveur ; listes réduites aux 3 premiers éléments.

Rechercher des villes

GET/api/v1/cities

Les villes dont le nom correspond, les meilleures correspondances et les plus grandes villes d’abord, chacune avec son pays, ses coordonnées et son fuseau horaire.

Paramètres

Nom	Signification
`q`obligatoire	Partie d’un nom de ville, accents facultatifs (80 caractères au maximum).
`limit`facultatif	Nombre de résultats, 1–50. Par défaut : 10.
`country`facultatif	Code pays ISO 3166, par exemple GB, pour ne garder que ce pays.

Exemple de requête

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

Exemple de réponse

{
  "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éponse réelle de ce serveur.

Une ville

GET/api/v1/cities/{slug}

Une ville par son slug, avec le décalage actuel de son fuseau horaire et le prochain changement d’heure.

Paramètres

Nom	Signification
`slug`dans le chemin	Slug de ville, par exemple tokyo.

Exemple de requête

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

Exemple de réponse

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

Réponse réelle de ce serveur.

Des coordonnées au fuseau horaire

GET/api/v1/lookup

La ville répertoriée la plus proche d’une latitude et d’une longitude, et son fuseau horaire. C’est une approximation : les frontières des fuseaux ne sont pas modélisées.

Paramètres

Nom	Signification
`lat`obligatoire	Latitude en degrés décimaux, de −90 à 90.
`lng`obligatoire	Longitude en degrés décimaux, de −180 à 180.

Exemple de requête

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

Exemple de réponse

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

Réponse réelle de ce serveur.

Version des données

GET/api/v1/tzdata

La version de la base de données des fuseaux horaires IANA dont proviennent les réponses, et la date de la dernière mise à jour des données de Hourora.

Paramètres

Aucun paramètre.

Exemple de requête

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

Exemple de réponse

{
  "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éponse réelle de ce serveur.

Erreurs

Une erreur est aussi du JSON : le statut HTTP, un code stable pour votre programme et un message lisible par des humains.

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

Statut	Codes	Quand
400	`missing_parameter, invalid_parameter`	Un paramètre manque ou n’a pas la forme attendue.
404	`unknown_zone, unknown_city, unknown_country, not_found`	Ce fuseau horaire, cette ville, ce pays ou cet endpoint n’existe pas.
429	`rate_limited`	Trop de requêtes de votre client ; attendez le nombre de secondes indiqué dans Retry-After.
500	`internal_error`	Une erreur s’est produite de notre côté. Veuillez réessayer plus tard.

Fonctionnement

Limites et cache

Chaque client peut envoyer jusqu’à 120 requêtes par minute, avec de courtes rafales autorisées. Au-delà, l’API répond 429 avec un en-tête Retry-After. La limite protège un service gratuit ; si vous avez besoin de plus, utilisez un cache.

Chaque réponse indique combien de temps elle peut être mise en cache (Cache-Control). L’heure actuelle n’est jamais mise en cache ; les listes de fuseaux, les fiches de villes et les recherches par coordonnées le sont pendant cinq minutes ; les recherches de villes et les conversions d’une heure donnée, pendant un jour.

Vous créez une horloge ? Récupérez le décalage une fois, faites avancer l’horloge localement, puis interrogez de nouveau l’API après le prochain changement d’heure indiqué dans la réponse. Inutile d’interroger chaque seconde.

D’où viennent les réponses

Les décalages, abréviations et changements d’heure proviennent de la copie compilée par Hourora de la base de données des fuseaux horaires IANA, version 2026e, pour 1970–2060. En dehors de cette période, ce sont les données intégrées du serveur qui sont utilisées, et elles peuvent être plus anciennes.

Les conversions traitent explicitement les bascules de l’heure d’été : une heure sautée quand on avance les horloges est signalée comme un trou, et une heure qui a lieu deux fois quand on les recule est signalée comme un chevauchement, avec les deux instants.

La recherche par coordonnées renvoie la plus proche d’environ 7 200 villes répertoriées et le fuseau de cette ville. Près d’une frontière, en mer ou dans une zone peu peuplée, il peut différer du fuseau réellement en vigueur à cet endroit.

Conditions d’utilisation

Gratuite pour un usage personnel et commercial. Sans clé et sans compte.
Une mention de la source est appréciée mais pas obligatoire : un lien vers hourora.app près de l’endroit où les données apparaissent.
Fournie en l’état, sans accord de niveau de service ni garantie de disponibilité. Ne l’utilisez pas là où une heure erronée ou manquante pourrait causer un préjudice.
Les réponses suivent IANA tzdata 2026e. Lorsque des gouvernements changent leur heure légale, les données sont mises à jour avec la version IANA suivante.
La version 1 reste compatible : de nouveaux champs peuvent être ajoutés, mais rien n’est supprimé ni renommé. Les changements incompatibles arriveraient sous /api/v2.
Merci de respecter la limite de requêtes et de mettre les réponses en cache. Le trafic abusif peut être bloqué.

Questions

Bon à savoir

L’API Hourora est-elle vraiment gratuite ?

Oui. Pas de clé, pas de compte, pas d’offre payante. Une limite de requêtes par client garantit un service équitable pour tous.

Puis-je l’appeler en JavaScript depuis le navigateur ?

Oui. Chaque endpoint accepte les requêtes cross-origin de n’importe quel site (CORS), et aucun identifiant n’est nécessaire.

Comment gère-t-elle l’heure d’été ?

Chaque réponse est calculée pour l’instant exact à partir des règles IANA. L’endpoint convert indique aussi quand une heure locale demandée n’existe pas (passage à l’heure d’été) ou a lieu deux fois (retour à l’heure d’hiver).

Quelle est la précision de la recherche par coordonnées ?

Elle renvoie le fuseau horaire de la ville répertoriée la plus proche, ce qui est juste presque partout où vivent des gens. Elle ne modélise pas les frontières des fuseaux et peut donc se tromper près d’une frontière ou en mer.