WorldClock API Documentation

Start with one request. Then use the endpoint reference for parameters, response properties, HTTP errors, rate limits, caching and code examples.

Introduction

The WorldClock API is a read-only JSON API. Clean public routes use /api/v1/…; WordPress REST aliases use the same handlers, so calculations do not diverge.

Quick Start

cURL

curl -s 'https://worldclock.to/api/v1/time?timezone=Asia/Karachi'

A successful response contains success, data and meta. Point-in-time fields are generated at request time.

Authentication

Public read-only access is currently enabled. The server also supports an optional Bearer-key model for controlled access.

Header architecture

Authorization: Bearer YOUR_API_KEY

Real secrets are stored server-side as one-way hashes and are never injected into frontend JavaScript by the theme.

Response Format

Success

{
    "success": true,
    "data": [],
    "meta": {
        "version": "v1",
        "timezone": "UTC",
        "timestamp": 1788946200
    }
}

Error

{
    "success": false,
    "error": {
        "code": "INVALID_TIMEZONE",
        "message": "The supplied timezone is invalid."
    }
}

Error Codes

Code	HTTP	Meaning
`INVALID_TIMEZONE`	400	Timezone is not a valid IANA identifier.
`MISSING_PARAMETER`	400	A required field is missing.
`CITY_NOT_FOUND`	404	No matching city was found.
`COUNTRY_NOT_FOUND`	404	No matching country was found.
`AUTH_REQUIRED`	401	A valid Bearer key is required.
`RATE_LIMIT_EXCEEDED`	429	Configured fair-use limit reached.
`MAINTENANCE`	503	API maintenance mode is active.

Rate Limits & Fair Use

Current configuration: 60 requests/minute and 5000 requests/day per anonymous client or API key. These limits are editable in WordPress and may be changed as capacity and usage evolve.

Caching

Country and city directory responses change slowly and can be cached aggressively. Time responses describe the instant of the request. Sun/moon responses for a fixed date/location can be cached by date and parameters.

CORS & Security

Only GET and OPTIONS are exposed by the public API. Inputs are validated and sanitised, errors do not disclose server paths or secrets, and CORS origins are configurable in the WordPress admin.

Examples

Every endpoint page includes cURL, JavaScript, PHP and Python examples plus a live Explorer for trying parameters without an external API tool.

Open API Explorer

Changelog & API Status

Review backwards-compatible releases in the API changelog and check live endpoint health on the API status page.

API FAQ

Does the API rely on a third-party time API?

No. Core time, timezone, location, sun and moon responses are generated from WorldClock’s own bundled data, PHP/IANA timezone rules and internal calculation code.

Can a future v2 break v1?

A future v2 may introduce a different contract, but published v1 response shapes are not silently replaced with breaking structures.

Can I use the API from a browser?

Yes, when your origin is allowed by the administrator’s CORS configuration. Never expose a private API key in public frontend code.

Documentation Notes

Start with the quick-start request below, then use the endpoint documentation for parameters, response fields, errors, caching and examples in cURL, JavaScript, PHP and Python.