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. The verification link opens your dashboard with your first token already created. (Signed up another way? Open API keys in the app and create one.)
  3. Copy it now — it is shown once. The dashboard also has this page's first request with your token filled in.

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": "2026d",
        "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.