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. Long-form editorial content is not part of the API.

List cities

GET /v1/cities

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

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.

Example

curl "https://api.timezone.io/v1/cities?country=US&sort=name" \
  -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" }
    }
  ],
  "meta": {
    "current_page": 1,
    "per_page": 25,
    "total": 1,
    "tzdb_version": "2026a",
    "generated_at": "2026-05-31T12:00:00+00:00"
  },
  "links": {
    "first": "https://api.timezone.io/v1/cities?country=US&sort=name&page=1",
    "last": "https://api.timezone.io/v1/cities?country=US&sort=name&page=1",
    "prev": null,
    "next": null
  }
}

Retrieve a city

GET /v1/cities/{slug}

Fetch a single city by its unique slug (new-york). An unknown slug returns 404.

Query parameters

Parameter	Type	Description
`at`	string	The moment to compute `current` and `sun` for: an ISO-8601 datetime or a Unix timestamp. Default now.

Response

Field	Description
`coordinates`	`{latitude, longitude}`.
`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.

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

{
  "data": {
    "slug": "new-york",
    "name": "New York",
    "is_capital": false,
    "coordinates": { "latitude": 40.7128, "longitude": -74.006 },
    "country": { "code": "US", "name": "United States" },
    "timezone": { "iana": "America/New_York", "abbreviation": "EDT", "display_name": "New York" },
    "current": {
      "datetime": "2026-06-21T08:00:00-04:00",
      "utc_datetime": "2026-06-21T12:00:00Z",
      "utc_offset": "-04:00",
      "utc_offset_seconds": -14400,
      "abbreviation": "EDT",
      "name": "Eastern Daylight Time",
      "is_dst": true
    },
    "sun": {
      "sunrise": "2026-06-21T05:25:00-04:00",
      "sunset": "2026-06-21T20:31:00-04:00",
      "daylight_minutes": 906
    },
    "links": {
      "self": "https://api.timezone.io/v1/cities/new-york",
      "timezone": "https://api.timezone.io/v1/timezones/America/New_York",
      "country": "https://api.timezone.io/v1/countries/US",
      "web": "https://timezone.io/cities/new-york"
    }
  },
  "meta": {
    "tzdb_version": "2026a",
    "generated_at": "2026-05-31T12:00:00+00:00"
  }
}

See Errors for the full list of responses.