Countries

Every country and territory in the IANA database, with its identity, default time zone, and a summary of the time zones, named abbreviations, and cities it contains. Long-form editorial content and boundary geometry are not part of the API.

A country can span many UTC offsets, so — unlike a time zone or a city — a country has no single "current time" and these endpoints take no at parameter. The daylight-saving summary is structural: it reports which of the country's zones take part in DST, not whether they happen to be in DST right now.

List countries

GET /v1/countries

Returns a paginated list. Each row is lean: the ISO 3166-1 alpha-2 code, name, slug, flag emoji, and ISO region.

Query parameters

Parameter	Type	Description
`q`	string	Search across name, `iso2`, `iso3`, and slug. Max 100 characters.
`region`	string	Keep one ISO region (`Americas`, `Europe`, `Asia`, `Africa`, `Oceania`). Case-insensitive.
`sub_region`	string	Keep one ISO sub-region (e.g. `Western Europe`). Case-insensitive.
`observes_dst`	boolean	`true`/`false` (also `1`/`0`). Keep countries that have, or lack, any DST-observing zone.
`sort`	string	`name` or `iso2`. 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.

Example

curl "https://api.timezone.io/v1/countries?region=Europe&sort=iso2" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

{
  "data": [
    {
      "iso2": "FR",
      "name": "France",
      "slug": "france",
      "emoji": "🇫🇷",
      "region": "Europe",
      "links": { "self": "https://api.timezone.io/v1/countries/france" }
    }
  ],
  "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/countries?region=Europe&sort=iso2&page=1",
    "last": "https://api.timezone.io/v1/countries?region=Europe&sort=iso2&page=1",
    "prev": null,
    "next": null
  }
}

Retrieve a country

GET /v1/countries/{iso2|slug}

Fetch a single country by its unique slug (united-states) or its ISO 3166-1 alpha-2 iso2 code (US, case-insensitive). Both are unique, so there is never any ambiguity; an unknown value returns 404.

Query parameters

Parameter	Type	Description
`include`	string	Comma-separated related data to embed: `timezones`, `abbreviations`.

Response

Field	Description
`iso2` / `iso3` / `numeric_code`	The ISO 3166-1 codes.
`region` / `sub_region`	The ISO region and sub-region.
`default_timezone`	The country's primary time zone as `{iana, display_name}`, or `null`.
`population`	Latest population from Wikidata, or `null`.
`counts`	Number of `timezones`, distinct `abbreviations`, `cities`, and dependent `dependencies`.
`dst`	`observes` (does any zone take part in DST), and the split of zones `timezones_in_dst` (take part) vs `timezones_without_dst` (do not). Structural — not a current-moment reading.
`dependencies`	Dependent territories as `[{code, name, slug}]`.
`links`	Related API URLs (`self`, `timezones`, `cities`) plus `web`, the human-readable page.

curl https://api.timezone.io/v1/countries/united-states \
  -H "Authorization: Bearer YOUR_API_TOKEN"

{
  "data": {
    "iso2": "US",
    "iso3": "USA",
    "numeric_code": "840",
    "name": "United States",
    "slug": "united-states",
    "emoji": "🇺🇸",
    "region": "Americas",
    "sub_region": "Northern America",
    "population": 331000000,
    "default_timezone": { "iana": "America/New_York", "display_name": "New York" },
    "counts": { "timezones": 29, "abbreviations": 11, "cities": 48, "dependencies": 6 },
    "dst": { "observes": true, "timezones_in_dst": 23, "timezones_without_dst": 6 },
    "dependencies": [
      { "code": "PR", "name": "Puerto Rico", "slug": "puerto-rico" }
    ],
    "links": {
      "self": "https://api.timezone.io/v1/countries/united-states",
      "timezones": "https://api.timezone.io/v1/timezones?country=US",
      "cities": "https://api.timezone.io/v1/cities?country=US",
      "web": "https://timezone.io/countries/united-states"
    }
  },
  "meta": {
    "tzdb_version": "2026a",
    "generated_at": "2026-05-31T12:00:00+00:00"
  }
}

Use ?include=timezones to embed the country's time zones as lean rows, or ?include=abbreviations to embed its distinct named time zones. See Errors for the full list of responses.