Current Time API

Return the server-synchronised current instant in an IANA timezone, city or country.

GET/api/v1/time

What It Does

Return the server-synchronised current instant in an IANA timezone, city or country.

HTTP method: GET
Authentication: Public read-only; Bearer keys supported
Version: v1

Parameters

Name	Type	Required	Description
`timezone`	string	No	IANA timezone identifier. Example: `Asia/Karachi`
`city`	string	No	City name or slug from the WorldClock directory. Example: `Karachi`
`country`	string	No	Country name, slug or two-letter code. Example: `Pakistan`
`latitude`	number	No	Latitude used with longitude to select the nearest bundled city/timezone. Example: `24.86`
`longitude`	number	No	Longitude used with latitude. Example: `67.01`

Request Examples

cURL

curl -s 'https://worldclock.to/api/v1/time?timezone=Asia/Karachi&city=Karachi&country=Pakistan&latitude=24.86&longitude=67.01'

JavaScript

const response = await fetch("https:\/\/worldclock.to\/api\/v1\/time?timezone=Asia\/Karachi&city=Karachi&country=Pakistan&latitude=24.86&longitude=67.01");
const result = await response.json();
console.log(result.data);

PHP

$response = wp_remote_get('https://worldclock.to/api/v1/time?timezone=Asia/Karachi&city=Karachi&country=Pakistan&latitude=24.86&longitude=67.01');
 = json_decode(wp_remote_retrieve_body(), true);

Python

import requests

response = requests.get("https:\/\/worldclock.to\/api\/v1\/time?timezone=Asia\/Karachi&city=Karachi&country=Pakistan&latitude=24.86&longitude=67.01")
response.raise_for_status()
print(response.json()["data"])

Example Response

The values below illustrate the response shape. Live current-time fields are generated dynamically by the endpoint.

JSON

{
    "success": true,
    "data": {
        "timezone": "Asia/Karachi",
        "utc_offset": "+05:00",
        "abbreviation": "PKT",
        "local_time": "2026-09-09T14:30:00+05:00",
        "date": "2026-09-09",
        "time": "14:30:00",
        "unix": 1788946200,
        "dst": false,
        "city": "Karachi",
        "country": "Pakistan"
    },
    "meta": {
        "version": "v1",
        "timezone": "Asia/Karachi",
        "timestamp": 1788946200
    }
}

Response Properties

Every successful response contains success: true, endpoint-specific data, and a meta object. The table below documents the public fields for this endpoint.

Property	Meaning
`success`	Boolean indicating whether the request completed successfully.
`meta.version`	Published API response version.
`meta.timestamp`	Unix timestamp for the API response instant.
`meta.timezone`	Timezone context used by the response.
`meta.rate_limit`	Per-client fair-use limit and remaining-request information on public transports.
`data.timezone`	Resolved IANA timezone identifier.
`data.utc_offset`	Current UTC offset in ±HH:MM form.
`data.abbreviation`	Current timezone abbreviation when PHP/IANA provides one.
`data.local_time`	Current local time in ISO 8601 form.
`data.date`	Current local calendar date.
`data.time`	Current local wall-clock time.
`data.unix`	Unix timestamp for the same instant.
`data.dst`	Whether daylight-saving time is active.
`data.city`	Resolved city when a city or coordinates were used.
`data.country`	Resolved country when available.
`meta.clock_source`	Clock-source description confirming server-synchronised UTC plus IANA timezone rules.

Errors use success: false with a stable machine-readable error code and a safe human-readable message.

Errors & HTTP Status Codes

400 — invalid or missing parameter.
401 — API key required or invalid when key-only access is enabled.
404 — unknown city, country or endpoint.
429 — configured rate limit reached.
503 — API disabled or maintenance mode.

Rate Limits & Caching

Current fair-use configuration is 60 requests per minute and 5000 requests per day. Cache stable directory/calculation responses where appropriate; treat current-time output as point-in-time data.