Cities

Major cities worldwide, each tied to a country and an IANA time zone. Every city carries a live current time and a live sun block — sunrise, sunset, and daylight length computed from its coordinates for the moment you ask about.

At a glance

Endpoint What you get
GET /v1/cities Paginated, searchable list — identity, country, zone, compact current block.
GET /v1/cities/{slug} One city: live local time plus sunrise, sunset, and daylight length.

List cities

GET /v1/cities

Returns a paginated list of lean rows: identity, country, time zone, and a compact current block.

Example — search-as-you-type city lookup

A "what time is it in…" search box sends whatever the user has typed so far; q matches anywhere in the name or slug:

curl "https://api.timezone.io/v1/cities?q=york" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

{
    "data": [
        {
            "slug": "new-york",
            "name": "New York",
            "is_capital": false,
            "country": { "code": "US", "name": "United States" },
            "timezone": { "iana": "America/New_York", "abbreviation": "EDT" },
            "current": { "utc_offset": "-04:00", "is_dst": true },
            "links": { "self": "https://api.timezone.io/v1/cities/new-york" }
        },
        {
            "slug": "new-york-city",
            "name": "New York City",
            "is_capital": false,
            "country": { "code": "US", "name": "United States" },
            "timezone": { "iana": "America/New_York", "abbreviation": "EDT" },
            "current": { "utc_offset": "-04:00", "is_dst": true },
            "links": { "self": "https://api.timezone.io/v1/cities/new-york-city" }
        }
    ],
    "meta": {
        "current_page": 1,
        "per_page": 25,
        "total": 2,
        "tzdb_version": "2025.2",
        "generated_at": "2026-06-12T09:00:00+00:00"
    },
    "links": {
        "first": "https://api.timezone.io/v1/cities?q=york&page=1",
        "last": "https://api.timezone.io/v1/cities?q=york&page=1",
        "prev": null,
        "next": null
    }
}

The row already carries enough to render a result line — name, country, and live offset — so you only fetch the detail endpoint once the user picks one.

Query parameters

Parameter Type Description
q string Search across name and slug. Max 100 characters.
country string Filter by ISO 3166-1 alpha-2 country code (e.g. US). Case-insensitive.
timezone string Filter by IANA identifier (e.g. America/New_York).
is_capital boolean true/false (also 1/0).
sort string name or offset (the zone's standard UTC offset). Prefix with - for descending. Default name.
detail string concise (default) or full. full returns the detail shape per row.
per_page integer Results per page, 1–100. Default 25.
page integer Page number, 1 or greater. Default 1.

Sunrise, sunset, and daylight are computed live and are not available as sort keys.

Retrieve a city

GET /v1/cities/{slug}

Fetch a single city by its unique slug (tokyo). An unknown slug returns 404.

Example — sunrise and sunset for a weather widget

A dashboard wants Tokyo's daylight window for the June solstice. Pass the date as at; sun comes back computed for that day, in Tokyo's own offset:

curl "https://api.timezone.io/v1/cities/tokyo?at=2026-06-21T00:00:00Z" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

{
    "data": {
        "slug": "tokyo",
        "name": "Tokyo",
        "is_capital": true,
        "population": 9733276,
        "coordinates": { "latitude": 35.689487, "longitude": 139.691711 },
        "country": { "code": "JP", "name": "Japan" },
        "timezone": {
            "iana": "Asia/Tokyo",
            "abbreviation": "JST",
            "display_name": "Tokyo"
        },
        "current": {
            "datetime": "2026-06-21T09:00:00+09:00",
            "utc_datetime": "2026-06-21T00:00:00Z",
            "utc_offset": "+09:00",
            "utc_offset_seconds": 32400,
            "abbreviation": "JST",
            "name": "Japan Standard Time",
            "is_dst": false
        },
        "sun": {
            "sunrise": "2026-06-21T04:25:37+09:00",
            "sunset": "2026-06-21T19:00:20+09:00",
            "daylight_minutes": 875
        },
        "links": {
            "self": "https://api.timezone.io/v1/cities/tokyo",
            "timezone": "https://api.timezone.io/v1/timezones/Asia/Tokyo",
            "country": "https://api.timezone.io/v1/countries/JP",
            "web": "https://timezone.io/cities/tokyo"
        }
    },
    "meta": {
        "tzdb_version": "2025.2",
        "generated_at": "2026-06-12T09:00:00+00:00"
    }
}

Query parameters

Parameter Type Description
at string The moment to compute current and sun for: an ISO-8601 datetime, or a Unix timestamp in seconds within years 2000–2100. Default now.

Response fields

Field Description
coordinates {latitude, longitude}.
population Population from Wikidata/GeoNames, or null.
timezone {iana, abbreviation, display_name} — the city's time zone.
current The live local time state: datetime, utc_datetime, utc_offset(+seconds), abbreviation, name, is_dst.
sun Live sunrise/sunset (offset-stamped, or null inside the polar circles) and daylight_minutes (1440 polar day, 0 polar night).
links Related API URLs (self, timezone, country) plus web, the human-readable page.

Going deeper

  • Polar edge cases are explicit. Inside the polar circles the sun may not rise or set at all: sunrise/sunset are null and daylight_minutes is 1440 (polar day) or 0 (polar night). Check for null before formatting.
  • sun follows at. Omit at for today's times; pass any date to get that day's — the widget above asks about the solstice three weeks ahead.
  • City time is zone time. A city has no offset of its own; current is computed from its IANA zone, so /cities/tokyo and /timezones/Asia/Tokyo always agree.

See Errors for the full list of responses.