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.

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.

At a glance#

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.

Example — region-grouped country dropdown#

A signup form wants its country selector grouped by region, Europe first:

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

{
    "data": [
        {
            "iso2": "AX",
            "name": "Åland Islands",
            "slug": "aland-islands",
            "emoji": "🇦🇽",
            "region": "Europe",
            "links": { "self": "https://api.timezone.io/v1/countries/aland-islands" }
        },
        {
            "iso2": "AL",
            "name": "Albania",
            "slug": "albania",
            "emoji": "🇦🇱",
            "region": "Europe",
            "links": { "self": "https://api.timezone.io/v1/countries/albania" }
        }
    ],
    "meta": {
        "current_page": 1,
        "per_page": 25,
        "total": 53,
        "tzdb_version": "2025.2",
        "generated_at": "2026-06-12T09:00:00+00:00"
    },
    "links": {
        "first": "https://api.timezone.io/v1/countries?region=Europe&sort=name&page=1",
        "last": "https://api.timezone.io/v1/countries?region=Europe&sort=name&page=3",
        "prev": null,
        "next": "https://api.timezone.io/v1/countries?region=Europe&sort=name&page=2"
    }
}

(Remaining rows trimmed.) Repeat per region, or fetch all pages once and cache — country data changes about as often as borders do (see rate limits on caching).

Query parameters#

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.

Example — pre-flight check before scheduling across Australia#

Before offering "9 am Australia time" to a customer, check how fragmented the country actually is. The answer: twelve zones, and only seven of them change their clocks —

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

{
    "data": {
        "iso2": "AU",
        "iso3": "AUS",
        "numeric_code": "036",
        "name": "Australia",
        "slug": "australia",
        "emoji": "🇦🇺",
        "region": "Oceania",
        "sub_region": "Australia and New Zealand",
        "population": null,
        "default_timezone": {
            "iana": "Australia/Sydney",
            "display_name": "Sydney"
        },
        "counts": {
            "timezones": 12,
            "abbreviations": 8,
            "cities": 8,
            "dependencies": 4
        },
        "dst": {
            "observes": true,
            "timezones_in_dst": 7,
            "timezones_without_dst": 5
        },
        "dependencies": [
            {
                "code": "CX",
                "name": "Christmas Island",
                "slug": "christmas-island"
            },
            {
                "code": "CC",
                "name": "Cocos (Keeling) Islands",
                "slug": "cocos-keeling-islands"
            },
            {
                "code": "HM",
                "name": "Heard Island and McDonald Islands",
                "slug": "heard-island-and-mcdonald-islands"
            },
            { "code": "NF", "name": "Norfolk Island", "slug": "norfolk-island" }
        ],
        "links": {
            "self": "https://api.timezone.io/v1/countries/australia",
            "timezones": "https://api.timezone.io/v1/timezones?country=AU",
            "cities": "https://api.timezone.io/v1/cities?country=AU",
            "web": "https://timezone.io/countries/australia"
        }
    },
    "meta": {
        "tzdb_version": "2025.2",
        "generated_at": "2026-06-12T09:00:00+00:00"
    }
}

Reading it: dst.observes: true with a 7/5 split means "Australia time" is genuinely ambiguous — in summer, Sydney and Brisbane disagree by an hour even though both are "Eastern". Follow links.timezones (or pass ?include=timezones) to list the actual zones and let the user pick; default_timezone is the sensible pre-selection.

Query parameters#

Response fields#

Going deeper#

• ?include=timezones embeds the country's zones as lean rows, ?include=abbreviations its distinct named standards, ?include=cities its cities. Combine them: ?include=timezones,cities — one request instead of three.
• Dependencies are separate countries. Puerto Rico is not among the United States' zones or cities — it is its own entry (/countries/puerto-rico), linked from dependencies.
• default_timezone is a convention, not a law — it is the country's most prominent zone, useful as a dropdown pre-selection, never a substitute for asking the user.

See Errors for the full list of responses.