Quickstart

From zero to your first API response in about two minutes. By the end of this page you will have a token, a working request, and the local time in Tokyo.

1. Get a token#

1. Create a free account and verify your email address.
2. Open API tokens in your settings and create a token.
3. Copy it now — it is shown once.

That token is the only credential you need; it can read every v1 endpoint. The Authentication page covers the details.

2. Make your first request#

Ask the API what time it is in Tokyo right now:

curl https://api.timezone.io/v1/timezones/Asia/Tokyo \
  -H "Authorization: Bearer YOUR_API_TOKEN"

3. Read the response#

{
    "data": {
        "iana": "Asia/Tokyo",
        "display_name": "Tokyo",
        "observes_dst": false,
        "country": { "code": "JP", "name": "Japan" },
        "current": {
            "datetime": "2026-06-12T18:00:00+09:00",
            "utc_datetime": "2026-06-12T09:00:00Z",
            "utc_offset": "+09:00",
            "utc_offset_seconds": 32400,
            "abbreviation": "JST",
            "name": "Japan Standard Time",
            "is_dst": false
        },
        "standard": {
            "utc_offset": "+09:00",
            "utc_offset_seconds": 32400,
            "abbreviation": "JST",
            "name": "Japan Standard Time"
        },
        "dst": { "savings_seconds": 0, "next_transition": null },
        "links": {
            "self": "https://api.timezone.io/v1/timezones/Asia/Tokyo",
            "country": "https://api.timezone.io/v1/countries/JP",
            "web": "https://timezone.io/iana/Asia/Tokyo"
        }
    },
    "meta": {
        "tzdb_version": "2025.2",
        "generated_at": "2026-06-12T09:00:00+00:00"
    }
}

Three things to notice:

• Everything lives under data — every endpoint wraps its payload the same way, with request metadata in meta.
• current is computed live for the moment of your request: the local datetime (offset included), the equivalent UTC instant, and the zone's friendly name.
• links are URLs you can follow — related API resources plus web, the human-readable page on timezone.io.

In your language#

The same request in JavaScript and Python — it is plain HTTPS + JSON, so any HTTP client works:

const response = await fetch('https://api.timezone.io/v1/timezones/Asia/Tokyo', {
    headers: { Authorization: `Bearer ${process.env.TIMEZONE_API_TOKEN}` },
});

const { data } = await response.json();
console.log(`It is ${data.current.datetime} in ${data.display_name}`);

import os
import requests

response = requests.get(
    "https://api.timezone.io/v1/timezones/Asia/Tokyo",
    headers={"Authorization": f"Bearer {os.environ['TIMEZONE_API_TOKEN']}"},
)

data = response.json()["data"]
print(f"It is {data['current']['datetime']} in {data['display_name']}")

Keep the token in an environment variable rather than in code — it is a password.

Where to go next#

• Convert a meeting time across offices — Convert.
• List a country's zones for a picker — Timezones.
• Decode "EST" from a calendar invite — Abbreviations.
• Sunrise and sunset for any city — Cities.
• Skim the Overview for the response envelope and conventions, and Rate limits before you ship anything that loops.