Cities API

Search, locate and paginate the bundled WorldClock city directory.

GET/api/v1/cities

What It Does

Search, locate and paginate the bundled WorldClock city directory.

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

Parameters

Name	Type	Required	Description
`search`	string	No	Name search. Example: `Kar`
`country`	string	No	Country name, slug or code. Example: `PK`
`timezone`	string	No	Filter by IANA timezone. Example: `Asia/Karachi`
`latitude`	number	No	Latitude used with longitude to sort cities by distance. Example: `24.86`
`longitude`	number	No	Longitude used with latitude to sort cities by distance. Example: `67.01`
`radius_km`	number	No	Optional maximum distance in kilometres when coordinates are supplied. Example: `250`
`page`	integer	No	Page number. Example: `1`
`per_page`	integer	No	Results per page, maximum 100. Example: `25`

Request Examples

cURL

curl -s 'https://worldclock.to/api/v1/cities?search=Kar&country=PK&timezone=Asia/Karachi&latitude=24.86&longitude=67.01&radius_km=250&page=1&per_page=25'

JavaScript

const response = await fetch("https:\/\/worldclock.to\/api\/v1\/cities?search=Kar&country=PK&timezone=Asia\/Karachi&latitude=24.86&longitude=67.01&radius_km=250&page=1&per_page=25");
const result = await response.json();
console.log(result.data);

PHP

$response = wp_remote_get('https://worldclock.to/api/v1/cities?search=Kar&country=PK&timezone=Asia/Karachi&latitude=24.86&longitude=67.01&radius_km=250&page=1&per_page=25');
 = json_decode(wp_remote_retrieve_body(), true);

Python

import requests

response = requests.get("https:\/\/worldclock.to\/api\/v1\/cities?search=Kar&country=PK&timezone=Asia\/Karachi&latitude=24.86&longitude=67.01&radius_km=250&page=1&per_page=25")
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": [
        {
            "name": "Karachi",
            "slug": "karachi",
            "country": "Pakistan",
            "country_code": "PK",
            "timezone": "Asia/Karachi",
            "latitude": 24.8599999999999994315658113919198513031005859375,
            "longitude": 67.0100000000000051159076974727213382720947265625,
            "distance_km": 0.8000000000000000444089209850062616169452667236328125
        }
    ],
    "meta": {
        "version": "v1",
        "page": 1,
        "per_page": 25,
        "total": 1,
        "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[]`	Array of matching city records.
`data[].name`	City display name.
`data[].slug`	Stable city slug used by path endpoints.
`data[].country`	Country display name.
`data[].country_code`	Two-letter country code.
`data[].timezone`	IANA timezone identifier.
`data[].latitude`	Decimal latitude.
`data[].longitude`	Decimal longitude.
`data[].distance_km`	Distance from supplied coordinates when proximity search is used.
`meta.page`	Current result page.
`meta.per_page`	Requested result count per page.
`meta.total`	Number of matching records before pagination.
`meta.total_pages`	Number of pages available at the selected page size.

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.