REST API

TimeDate Developer API

22 REST endpoints. IANA-accurate timezone data. 33,000+ cities. 120+ countries. Free tier — no key required to start.

Base URL & Response format

BASE URL

https://timedate.org/api/v1

ALL RESPONSES

{
  "status": "ok",
  "data": { ... },
  "meta": {
    "request_id": "...",
    "elapsed_ms": 12
  }
}

Rate limits

Tier	Limit	Auth
Free	100 req/min	No key needed
API key	1,000 req/min	X-API-Key: your-key

Need higher rate limits?

API keys unlock 1,000 req/min. Free during beta — request yours in seconds.

Get API key →

Quick start

cURL

curl "https://timedate.org/api/v1/time/America/New_York"

JavaScript

const res = await fetch('https://timedate.org/api/v1/time/America/New_York')
const { data } = await res.json()
console.log(data.current_time) // "2026-03-18T14:32:00"

Python

import requests
r = requests.get('https://timedate.org/api/v1/time/America/New_York')
print(r.json()['data']['current_time'])

Endpoints (22)

Method	Endpoint	Description
GET	/api/v1/time/:timezone	Current time for a timezone
GET	/api/v1/time/convert	Convert datetime between timezones
GET	/api/v1/context	Full context: time + DST + sun + moon (agent-optimised)
GET	/api/v1/context/:slug	City context by slug: city info + time + sun + moon
GET	/api/v1/timezone/:tz	Timezone info, DST, next transition
GET	/api/v1/timezone/list	All IANA timezones
GET	/api/v1/city/search	Search cities by name (33K+ cities)
GET	/api/v1/city/top	Top cities by population
GET	/api/v1/city/:slug	City details by slug
GET	/api/v1/city/:slug/nearby	Nearby cities (PostGIS radius search)
GET	/api/v1/holidays/:country/:year	Public holidays by country + year
GET	/api/v1/holidays/countries	List of supported countries (120+)
GET	/api/v1/holidays/upcoming	Upcoming holidays across countries
GET	/api/v1/sun	Sunrise, sunset, golden hour, day length
GET	/api/v1/moon	Moon phase, illumination, emoji
GET	/api/v1/date/diff	Date difference in days/weeks/months
GET	/api/v1/date/add	Add/subtract duration from a date
GET	/api/v1/date/business-days	Business days between two dates
GET	/api/v1/date/week-number	ISO week number for a date
POST	/api/v1/meeting/suggest	Fair meeting times across timezones
POST	/api/v1/meeting/score	Score fairness of a specific meeting slot
POST	/api/v1/batch	Batch multiple requests in one call

Full schema, request params, and response examples in the OpenAPI spec.

Embeddable Clock Widget

Add a live ticking clock to your website with a simple iframe. Configure timezone, theme, size, and more.

Get embed code →

Building with AI?

Use the TimeDate MCP server to give Claude or Cursor real-time time and timezone data. One npx command to install.

View MCP docs →