EN
Aller au contenu

API de fuseau horaire

Une requête. Vous avez déjà une clé unmap, et vous avez une coordonnée. La réponse est le fuseau IANA et le décalage UTC à un instant.

Chaque requête a besoin d'une clé d'API ; voir Authentification. Une recherche réussie compte pour un appel normal. Aucun forfait supplémentaire à activer.

curl "https://api.unmap.dev/timezone?lat=51.0447&lon=-114.0719&key=um_live_..."
const timezone = await unmap.timezone.lookup([-114.0719, 51.0447]);

La coordonnée du SDK est [longitude, latitude]. Les paramètres HTTP sont lat et lon.

Recherche

GET /timezone
ParamètreObligatoireDescription
latouiLatitude, de −90 à 90.
lonouiLongitude, de −180 à 180.
atnonInstant ISO 8601, par exemple 2026-07-01T18:00:00Z. Absent, c'est l'heure actuelle.
{
  "timezone": "America/Edmonton",
  "offset": "-06:00",
  "offsetSeconds": -21600,
  "dst": true
}

Cet exemple est Calgary le 2026-07-01T18:00:00Z, encore à l'heure d'été. Après le 2026-11-01, America/Edmonton reste à UTC−6 et dst est faux.

timezone est un identifiant IANA. offset est le décalage UTC à at, ±HH:MM. offsetSeconds compte les secondes à l'est d'UTC. dst indique si cet instant est à l'heure d'été.

at change le décalage. Il ne change pas le fuseau du point : les limites sont celles du jeu actuel, et un instant historique utilise quand même le fuseau d'aujourd'hui pour cette coordonnée.

Avec un instant

curl "https://api.unmap.dev/timezone?lat=51.0447&lon=-114.0719&at=2025-12-15T18:00:00Z&key=um_live_..."
const timezone = await unmap.timezone.lookup([-114.0719, 51.0447], {
  at: new Date("2025-12-15T18:00:00Z"),
});

Coordonnées refusées

Une coordonnée hors limites est refusée. Elle n'est pas ramenée dans l'intervalle.

{ "error": "lat must be between -90 and 90", "code": "invalid_coordinate" }

Un lat ou un lon absent porte le même code. Un at qui n'est pas un instant ISO 8601 donne un 400 avec invalid_timestamp. Un 400 n'est pas facturé.

Océan

Les polygones océaniques du jeu de limites sont des zones Etc/GMT. Etc/GMT+7 est sept heures à l'ouest d'UTC : le signe suit la convention POSIX, à l'inverse du champ offset.

Un point qui ne tombe dans aucun polygone reçoit la zone nautique de 15° de sa longitude, également une zone Etc/GMT. La recherche n'emprunte pas le fuseau du pays le plus proche.

Couverture et versions

La recherche est mondiale. Une coordonnée à moins d'environ la moitié de 1/125° d'une limite, soit environ 500 m, peut revenir dans le fuseau voisin. Les règles viennent de la base IANA. Les limites viennent de timezone-boundary-builder, dérivé d'OpenStreetMap. Les deux sont versionnés séparément : une nouvelle publication IANA n'attend pas un nouveau fichier de limites.

GET /timezone/meta

{ "tzdb": "2026d", "boundaries": "2026d", "generatedAt": "2026-09-21T00:00:00Z" }

/timezone/meta est authentifié et limité en débit, et il n'est pas facturé. generatedAt est le moment où la paire active a été promue. Un jour sans changement en amont ne le déplace pas.

Les deux publications sont vérifiées chaque jour. Une publication changée est compilée, vérifiée sur un jeu de points mondiaux, puis publiée comme un objet immuable. L'objet précédent reste, donc un retour arrière est un changement de manifeste. Les mentions des jeux de données sont sur la page attribution.