TimeandTool Public API Documentation

Name: TimeandTool Public API
Author: TimeandTool

A free, edge-deployed REST API for time and date data. Returns JSON. CORS is enabled on all endpoints — call it directly from the browser or any server.

Base URL

timeandtool.com

Protocol

HTTPS only

Free tier

100 req / min

Response format

JSON

Authentication

All endpoints on the free tier are accessible without an API key. For higher rate limits, include your API key in the Authorization header:

http

Authorization: Bearer ct_live_your_api_key_here

Get an API key by creating a free account. No credit card required.

Rate limits

Rate limits are applied per IP address (unauthenticated) or per API key (authenticated). When you exceed the limit, the API returns HTTP 429 Too Many Requests.

Plan	Requests / min	Requests / day	Price
Free (no key)	100	1,000	$0
Starter	500	10,000	$9 / mo
Pro	2,000	100,000	$29 / mo

Error format

All errors return a JSON body with an error field describing the problem.

json

{
  "error": "country parameter is required"
}

HTTP status	Meaning
200 OK	Request succeeded.
400 Bad Request	Missing or invalid parameter.
404 Not Found	Resource not found (e.g. unknown country).
429 Too Many Requests	Rate limit exceeded.
500 Internal Server Error	Unexpected server error.
502 Bad Gateway	Upstream data provider error.

GET/api/v1/holidays

Public holidays for a country and year

Returns the list of official public holidays for a given ISO 3166-1 alpha-2 country code and year. Data is sourced from the Nager.Date open dataset and cached daily.

Parameters

Parameter	Type	Required	Description
country	string	Yes	ISO 3166-1 alpha-2 country code, e.g. US, GB, DE.
year	integer	No	4-digit year. Defaults to the current year.

Example request

http

GET /api/v1/holidays?country=US&year=2026

Try it: /api/v1/holidays?country=US&year=2026

Example response

json

{
  "country": "US",
  "year": 2026,
  "holidays": [
    {
      "date": "2026-01-01",
      "localName": "New Year's Day",
      "name": "New Year's Day",
      "countryCode": "US",
      "fixed": true,
      "global": true
    },
    {
      "date": "2026-07-04",
      "localName": "Independence Day",
      "name": "Independence Day",
      "countryCode": "US",
      "fixed": true,
      "global": true
    }
  ]
}

Code examples

javascript

const res = await fetch(
  "https://www.timeandtool.com/api/v1/holidays?country=US&year=2026"
);
const { holidays } = await res.json();
console.log(holidays[0].name); // "New Year's Day"

python

import httpx

resp = httpx.get(
    "https://www.timeandtool.com/api/v1/holidays",
    params={"country": "US", "year": 2026},
)
data = resp.json()
print(data["holidays"][0]["name"])  # New Year's Day

GET/api/v1/timezone

Current time and UTC offset for a timezone

Returns the current date, time, UTC offset, and Unix timestamp for any valid IANA timezone identifier. Useful for real-time timezone conversion.

Parameters

Parameter	Type	Required	Description
tz	string	Yes	IANA timezone identifier, e.g. America/New_York, Europe/London, Asia/Tokyo.

Example request

http

GET /api/v1/timezone?tz=America/New_York

Try it: /api/v1/timezone?tz=America/New_York

Example response

json

{
  "timezone": "America/New_York",
  "datetime": "Friday, March 13, 2026 at 10:30:00 AM EDT",
  "iso": "2026-03-13T15:30:00.000Z",
  "offset": "GMT-4",
  "unixTimestamp": 1773657000
}

Code examples

javascript

const res = await fetch(
  "https://www.timeandtool.com/api/v1/timezone?tz=America/New_York"
);
const data = await res.json();
console.log(data.datetime); // "Friday, March 13, 2026 at 10:30:00 AM EDT"

python

import httpx

resp = httpx.get(
    "https://www.timeandtool.com/api/v1/timezone",
    params={"tz": "America/New_York"},
)
data = resp.json()
print(data["offset"])   # GMT-4
print(data["iso"])      # 2026-03-13T15:30:00.000Z

GET/api/v1/date/diff

Difference between two dates

Calculates the difference between two ISO 8601 dates. Returns total days, approximate years/months/days breakdown, and totals in hours and minutes.

Parameters

Parameter	Type	Required	Description
from	string	Yes	Start date in YYYY-MM-DD format.
to	string	Yes	End date in YYYY-MM-DD format.

Example request

http

GET /api/v1/date/diff?from=2026-01-01&to=2026-12-31

Try it: /api/v1/date/diff?from=2026-01-01&to=2026-12-31

Example response

json

{
  "from": "2026-01-01",
  "to": "2026-12-31",
  "totalDays": 364,
  "years": 0,
  "months": 12,
  "days": 4,
  "totalHours": 8736,
  "totalMinutes": 524160
}

Code examples

javascript

const res = await fetch(
  "https://www.timeandtool.com/api/v1/date/diff?from=2026-01-01&to=2026-12-31"
);
const { totalDays, years, months } = await res.json();
console.log(`${years}y ${months}m — ${totalDays} days`);

python

import httpx

resp = httpx.get(
    "https://www.timeandtool.com/api/v1/date/diff",
    params={"from": "2026-01-01", "to": "2026-12-31"},
)
data = resp.json()
print(f"{data['totalDays']} days total")

GET/api/v1/sun

Sunrise, sunset, and solar noon for a location

Returns sunrise, sunset, and solar noon times in UTC for any latitude/longitude on a given date. Handles polar regions (sun never rises or never sets).

Parameters

Parameter	Type	Required	Description
lat	number	Yes	Latitude in decimal degrees, e.g. 40.71.
lng	number	Yes	Longitude in decimal degrees, e.g. -74.01.
date	string	No	Date in YYYY-MM-DD format. Defaults to today (UTC).

Example request

http

GET /api/v1/sun?lat=40.71&lng=-74.01&date=2026-03-13

Try it: /api/v1/sun?lat=40.71&lng=-74.01&date=2026-03-13

Example response

json

{
  "date": "2026-03-13",
  "lat": 40.71,
  "lng": -74.01,
  "sunrise": "10:59 UTC",
  "sunset": "23:03 UTC",
  "solarNoon": "17:01 UTC",
  "daylightHours": 12.07
}

Code examples

javascript

const res = await fetch(
  "https://www.timeandtool.com/api/v1/sun?lat=40.71&lng=-74.01&date=2026-03-13"
);
const { sunrise, sunset, daylightHours } = await res.json();
console.log(`Sunrise: ${sunrise}, Sunset: ${sunset}`);

python

import httpx

resp = httpx.get(
    "https://www.timeandtool.com/api/v1/sun",
    params={"lat": 40.71, "lng": -74.01, "date": "2026-03-13"},
)
data = resp.json()
print(f"Sunrise: {data['sunrise']}, Daylight: {data['daylightHours']}h")

GET/api/v1/weather

Current weather and 5-day forecast for a location

Proxies the Open-Meteo forecast API. Returns current conditions (temperature, humidity, wind speed, weather code) and a 5-day hourly/daily forecast. Data is cached for 15 minutes.

Parameters

Parameter	Type	Required	Description
lat	number	Yes	Latitude in decimal degrees.
lng	number	Yes	Longitude in decimal degrees.

Example request

http

GET /api/v1/weather?lat=40.71&lng=-74.01

Try it: /api/v1/weather?lat=40.71&lng=-74.01

Example response

json

{
  "current": {
    "temperature_2m": 8.4,
    "relative_humidity_2m": 62,
    "apparent_temperature": 5.1,
    "weather_code": 3,
    "wind_speed_10m": 14.2,
    "wind_direction_10m": 270,
    "surface_pressure": 1015.3
  },
  "daily": {
    "temperature_2m_max": [
      10.1,
      12.4,
      9.8,
      11.2,
      13.5
    ],
    "temperature_2m_min": [
      3.2,
      4.1,
      2.9,
      5,
      6.3
    ]
  }
}

Code examples

javascript

const res = await fetch(
  "https://www.timeandtool.com/api/v1/weather?lat=40.71&lng=-74.01"
);
const data = await res.json();
console.log(data.current.temperature_2m, "°C");

python

import httpx

resp = httpx.get(
    "https://www.timeandtool.com/api/v1/weather",
    params={"lat": 40.71, "lng": -74.01},
)
data = resp.json()
print(data["current"]["temperature_2m"], "°C")

Ready to build?

The free tier requires no signup. For higher limits, create a free account and grab an API key.

Get API Key API overview