For developers

A free time zone API

The same engine that runs Hourora, as plain JSON: the time anywhere, conversions that know about daylight saving, every IANA zone and its clock changes. No key, no sign-up.

At a glance

Base URL: https://hourora.app/api/v1
Format: JSON (UTF-8), GET requests only
Authentication: None: no key, no sign-up, no cookies
CORS: Open to every origin, so you can call it from a browser
Rate limit: 120 requests per minute per client
Time data: IANA tzdata 2026e, compiled by Hourora
Machine-readable description: OpenAPI 3.1 document

Try it live

Pick an example or edit the path, then send it. The request goes from your browser straight to the API.

Response

The response appears here.

The endpoints

Every endpoint answers GET with JSON. Times are ISO 8601; offsets are minutes east of UTC (New York in winter is −300) and also written as text (−05:00).

Current time

GET/api/v1/time

The current time in a time zone or city: local time, UTC offset, abbreviation, daylight saving and the next clock change. Without parameters: UTC.

Parameters

Name	Meaning
`tz`optional	IANA time zone name, e.g. Europe/London. Aliases such as Asia/Calcutta are accepted and answered with the current name.
`city`optional	City slug instead of tz, e.g. london (find slugs with /cities).

Example request

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

Example response

{
  "zone": "Europe/London",
  "local": "2026-10-14T06:00:55",
  "iso": "2026-10-14T06:00:55+01:00",
  "offsetMinutes": 60,
  "offset": "+01:00",
  "utcOffset": "UTC+1",
  "abbreviation": "BST",
  "dst": true,
  "city": null,
  "utc": "2026-10-14T05:00:55.062Z",
  "unixMs": 1791954055062,
  "date": "2026-10-14",
  "time": "06:00:55",
  "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"
}

Real response from this server.

Convert a time

GET/api/v1/convert

A wall-clock time in one zone shown in another. Reports when the time falls in a daylight-saving gap (it does not exist) or overlap (it happens twice).

Parameters

Name	Meaning
`from`required	Zone (or city slug) the time is read in.
`to`required	Zone (or city slug) to show it in.
`time`optional	Wall-clock time in the from zone, YYYY-MM-DDTHH:mm (seconds optional, no offset), 1970–2060. Default: now.

Example request

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

Example response

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

Real response from this server.

List time zones

GET/api/v1/zones

Every IANA time zone with its current UTC offset, abbreviation, daylight-saving state, countries and main city.

Parameters

Name	Meaning
`country`optional	ISO 3166 country code, e.g. GB, to keep only that country.

Example request

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

Example response

{
  "asOf": "2026-10-14T05:00:55.062Z",
  "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"
    }
  ]
}

Real response from this server; lists shortened to the first 3 items.

One time zone

GET/api/v1/zones/{id}

One IANA zone: its aliases, countries and cities, its offset now, the next clock change and every change in a given year.

Parameters

Name	Meaning
`id`in the path	IANA zone name; keep the slash or encode it as %2F.
`year`optional	Year whose clock changes to list, 1970–2060. Default: this year.

Example request

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

Example response

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

Real response from this server; lists shortened to the first 3 items.

Search cities

GET/api/v1/cities

Cities whose name matches, best matches and largest cities first, each with its country, coordinates and time zone.

Parameters

Name	Meaning
`q`required	Part of a city name, accents optional (at most 80 characters).
`limit`optional	How many results, 1–50. Default 10.
`country`optional	ISO 3166 country code, e.g. GB, to keep only that country.

Example request

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

Example response

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

Real response from this server.

One city

GET/api/v1/cities/{slug}

One city by its slug, with its time zone's offset now and the next clock change.

Parameters

Name	Meaning
`slug`in the path	City slug, e.g. tokyo.

Example request

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

Example response

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

Real response from this server.

Coordinates to time zone

GET/api/v1/lookup

The nearest listed city to a latitude and longitude, and its time zone. An approximation: zone borders are not modelled.

Parameters

Name	Meaning
`lat`required	Latitude in decimal degrees, −90 to 90.
`lng`required	Longitude in decimal degrees, −180 to 180.

Example request

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

Example response

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

Real response from this server.

Data version

GET/api/v1/tzdata

Which IANA time zone database release the answers come from, and when Hourora last updated its data.

Parameters

No parameters.

Example request

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

Example response

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

Real response from this server.

Errors

An error is JSON too: the HTTP status, a stable code for your program and a message for people.

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

Status	Codes	When
400	`missing_parameter, invalid_parameter`	A parameter is missing or not in the expected form.
404	`unknown_zone, unknown_city, unknown_country, not_found`	No such time zone, city, country or endpoint.
429	`rate_limited`	Too many requests from your client; wait for the seconds in Retry-After.
500	`internal_error`	Something failed on our side. Please try again later.

How it works

Limits and caching

Each client may send up to 120 requests per minute, with short bursts allowed. Beyond that the API answers 429 with a Retry-After header. The limit protects a free service; if you need more, cache.

Every response says how long it may be cached (Cache-Control). The current time is never cached; zone lists, city details and lookups for five minutes; city searches and conversions of a given time for a day.

Building a clock? Fetch the offset once, tick locally, and fetch again after the next clock change the response tells you about. There is no need to poll every second.

Where the answers come from

Offsets, abbreviations and clock changes come from Hourora's own compiled copy of the IANA time zone database, release 2026e, for 1970–2060. Outside that range the server's built-in data is used, which may be older.

Conversions resolve daylight-saving edges explicitly: a time that is skipped when clocks spring forward is reported as a gap, and a time that happens twice when clocks fall back is reported as an overlap, with both instants.

Coordinate lookup returns the nearest of about 7,200 listed cities and that city's zone. Near a border, at sea or in a sparsely populated area it can differ from the zone that actually applies at the point.

Terms of use

Free for personal and commercial use. No key and no account.
Attribution is appreciated, not required: a link to hourora.app near where the data appears.
Provided as is, without a service-level agreement or guarantee of availability. Do not use it where a wrong or missing time could cause harm.
Answers follow IANA tzdata 2026e. When governments change their clocks, the data is updated with the next IANA release.
Version 1 stays compatible: new fields may be added, nothing is removed or renamed. Breaking changes would come as /api/v2.
Please stay within the rate limit and cache responses. Abusive traffic may be blocked.

Questions

Good to know

Is the Hourora API really free?

Yes. There is no key, no account and no paid tier. A rate limit per client keeps the service fair for everyone.

Can I call it from JavaScript in the browser?

Yes. Every endpoint allows cross-origin requests from any website (CORS), and no credentials are needed.

How does it handle daylight saving time?

Each answer is computed for the exact instant from the IANA rules. The convert endpoint also tells you when a requested wall time does not exist (spring forward) or happens twice (fall back).

How accurate is the coordinates lookup?

It returns the time zone of the nearest listed city, which is right almost everywhere people live. It does not model zone borders, so it can be wrong close to a border or at sea.