Developers — TimeFYI

02 — REST API

Base URL

https://timefyi.com/api/

All endpoints return JSON with Content-Type: application/json. No authentication required. CORS enabled for browser requests.

Endpoint Reference

#	Endpoint	Description	Cache
1	`GET /api/`	API root — service info and endpoint directory	none
2	`GET /api/search/?q={query}`	Search across cities, countries, glossary, and guides	5m
3	`GET /api/cities/`	List featured cities (100). Use `?all=1` for all 6,000+	1h
4	`GET /api/city/{slug}/`	City detail with current time, sun info, coordinates	1h
5	`GET /api/countries/`	List all 196 countries with timezone data	1h
6	`GET /api/country/{slug}/`	Country detail with timezones and top 20 cities	1h
7	`GET /api/v1/time/{timezone_id}/`	Current time for any IANA timezone (use hyphens, e.g. `America-New_York`)	1m
8	`GET /api/compare/?city1=&city2=`	Compare two cities — time difference, sun info, business hours overlap	5m
9	`GET /api/glossary/{slug}/`	Glossary term definition, category, and related terms	1h
10	`GET /api/guide/{series}/{slug}/`	Guide detail with table of contents and related guides	1h
11	`GET /api/openapi.json`	OpenAPI 3.1.0 specification (CORS enabled)	none

GET

City Detail

Get full city detail with live current time, sunrise/sunset, and coordinates.

/api/city/{slug}/

Example

curl https://timefyi.com/api/city/seoul/

{
  "name": "Seoul",
  "slug": "seoul",
  "url": "/time/seoul/",
  "country": {
    "name": "South Korea",
    "slug": "south-korea",
    "iso_code": "KR",
    "flag_emoji": "🇰🇷"
  },
  "timezone": "Asia/Seoul",
  "latitude": 37.5665,
  "longitude": 126.978,
  "population": 9776000,
  "elevation": 38,
  "is_capital": true,
  "is_featured": true,
  "current_time": {
    "datetime": "2026-03-05T15:30:00+09:00",
    "timezone_abbr": "KST",
    "utc_offset": "+09:00",
    "utc_offset_hours": 9.0,
    "is_dst": false
  },
  "sun": {
    "sunrise": "2026-03-05T06:48:00+09:00",
    "sunset": "2026-03-05T18:22:00+09:00",
    "dawn": "2026-03-05T06:20:00+09:00",
    "dusk": "2026-03-05T18:50:00+09:00",
    "day_length_seconds": 41640,
    "is_daytime": true
  }
}

GET

Search

Search across cities, countries, glossary terms, and guides. Minimum 2 characters.

/api/search/?q={query}

Example

curl "https://timefyi.com/api/search/?q=tokyo"

{
  "results": [
    {"name": "Tokyo", "slug": "tokyo", "type": "city", "url": "/time/tokyo/"},
    {"name": "Japan", "slug": "japan", "type": "country", "url": "/country/japan/"},
    {"name": "JST", "slug": "jst", "type": "glossary", "url": "/glossary/jst/"}
  ],
  "total": 3
}

GET

Time Lookup

Get the current time for any IANA timezone. Use hyphens instead of slashes in the timezone ID.

/api/v1/time/{timezone_id}/

Example

curl https://timefyi.com/api/v1/time/America-New_York/

{
  "timezone": "America/New_York",
  "abbreviation": "EST",
  "utc_offset": "-05:00",
  "utc_offset_hours": -5.0,
  "datetime": "2026-03-05T01:30:00-05:00",
  "is_dst": false
}

GET

Compare Cities

Compare two cities with time difference, current times, sun info, and business hours overlap.

/api/compare/?city1={slug}&city2={slug}

Example

curl "https://timefyi.com/api/compare/?city1=seoul&city2=new-york"

{
  "city_a": {
    "name": "Seoul",
    "slug": "seoul",
    "country": "South Korea",
    "timezone": "Asia/Seoul",
    "current_time": "2026-03-05T15:30:00+09:00",
    "utc_offset": "+09:00",
    "is_dst": false,
    "sun": {"sunrise": "2026-03-05T06:48:00+09:00", "sunset": "2026-03-05T18:22:00+09:00", "day_length_seconds": 41640, "is_daytime": true}
  },
  "city_b": {
    "name": "New York",
    "slug": "new-york",
    "country": "United States",
    "timezone": "America/New_York",
    "current_time": "2026-03-05T01:30:00-05:00",
    "utc_offset": "-05:00",
    "is_dst": false,
    "sun": {"sunrise": "2026-03-05T06:19:00-05:00", "sunset": "2026-03-05T17:54:00-05:00", "day_length_seconds": 41700, "is_daytime": false}
  },
  "difference": {
    "hours": 14,
    "display": "+14:00",
    "city_a_ahead": true
  },
  "business_hours_overlap_utc": ["00:00", "01:00", "02:00"],
  "business_hours_overlap_count": 3
}

GET

Country Detail

Country detail with timezones, DST info, and top cities.

/api/country/{slug}/

Example

curl https://timefyi.com/api/country/japan/

{
  "name": "Japan",
  "slug": "japan",
  "url": "/country/japan/",
  "iso_code": "JP",
  "flag_emoji": "🇯🇵",
  "capital": "Tokyo",
  "continent": "Asia",
  "population": 125800000,
  "area_km2": 377975,
  "currency_code": "JPY",
  "phone_code": "+81",
  "has_dst": false,
  "timezones": ["Asia/Tokyo"],
  "cities": [
    {"name": "Tokyo", "slug": "tokyo", "timezone": "Asia/Tokyo", "population": 13960000, "is_capital": true},
    {"name": "Osaka", "slug": "osaka", "timezone": "Asia/Tokyo", "population": 2753000, "is_capital": false}
  ],
  "city_count": 42
}

GET

Glossary Term

Glossary term definition, category, and related terms.

/api/glossary/{slug}/

Example

curl https://timefyi.com/api/glossary/utc/

{
  "term": "UTC",
  "slug": "utc",
  "url": "/glossary/utc/",
  "definition": "Coordinated Universal Time (UTC) is the primary time standard by which the world regulates clocks and time.",
  "category": "Standard",
  "related_terms": ["gmt", "iana-timezone", "utc-offset"]
}

03 — Packages & CLI

Python Package

Use TimeFYI offline with the Python package. Pure Python, zero dependencies.

Install

pip install timefyi

Example

from timefyi import get_current_time, get_time_difference

# Current time in a timezone
now = get_current_time("America/New_York")
print(now)  # 2026-03-05T01:30:00-05:00

# Time difference between two timezones
diff = get_time_difference("Asia/Seoul", "America/New_York")
print(diff)  # 14 hours

PyPI · GitHub · v0.1.0

npm Package

TypeScript/JavaScript timezone engine with zero dependencies. Works in Node.js, Deno, Bun, and browsers.

Install

npm install timefyi

Example

import { getCurrentTime, getTimeDifference } from "timefyi";

// Current time in a timezone
const now = getCurrentTime("America/New_York");
console.log(now); // 2026-03-05T01:30:00-05:00

// Time difference between timezones
const diff = getTimeDifference("Asia/Seoul", "America/New_York");
console.log(diff); // 14

timefyi npm demo — Node.js REPL with timezone conversion

npm · GitHub

Command-Line Interface

Timezone tools in your terminal.

Install & Use

pip install "timefyi[cli]"

timefyi now America/New_York          # Current time in New York
timefyi diff Asia/Seoul America/New_York  # Time difference
timefyi convert 15:00 Asia/Seoul America/New_York  # Convert time

TimeFYI CLI demo — showing timezone lookups, time difference, and conversion in terminal

MCP Server

Add timezone tools to any AI assistant that supports Model Context Protocol.

Install

pip install "timefyi[mcp]"

claude_desktop_config.json

{
  "mcpServers": {
    "timefyi": {
      "command": "python",
      "args": ["-m", "timefyi.mcp_server"]
    }
  }
}

Available tools

current_time time_difference convert_time business_hours_overlap sun_info

04 — Data Feeds

RSS & Atom Feeds

Subscribe to guide feeds to receive updates when new timezone guides are published. Both RSS 2.0 and Atom 1.0 formats are available.

RSS 2.0 /guides/feed/

Standard RSS feed. Compatible with all feed readers.

Atom 1.0 /guides/feed/atom/

Atom feed with richer metadata and update timestamps.

Subscribe via command line

# RSS
curl "https://timefyi.com/guides/feed/"

# Atom
curl "https://timefyi.com/guides/feed/atom/"

HTML auto-discovery

Feed readers automatically discover our feeds via <link> tags in every page:

<link rel="alternate" type="application/rss+xml"
      title="TimeFYI Guides" href="/guides/feed/">
<link rel="alternate" type="application/atom+xml"
      title="TimeFYI Guides" href="/guides/feed/atom/">

05 — AI / LLM

AI / LLM Integration

TimeFYI provides machine-readable content summaries following the llms.txt standard. These endpoints help AI models understand and reference our content.

/llms.txt text/plain

Concise summary of TimeFYI's content structure and key pages. Designed for AI models to quickly understand what the site offers and how it is organized.

/llms-full.txt text/plain

Extended version with complete URL patterns, i18n language codes, and page-level structure. Use this for deeper indexing and cross-referencing.

*.md endpoints text/markdown

Append .md to any page URL to get a clean Markdown version. Ideal for AI ingestion, RAG pipelines, and documentation toolchains.

# Markdown output for any page
curl "https://timefyi.com/time/seoul/.md"
curl "https://timefyi.com/glossary/utc/.md"
curl "https://timefyi.com/country/japan/.md"

AI Crawler Policy: Our robots.txt explicitly allows GPTBot, ClaudeBot, and Google-Extended crawlers.

06 — SEO & Standards

SEO & Standards

Standard endpoints for search engines, crawlers, and security researchers.

Endpoint	Standard	Description
/sitemap.xml	Sitemaps 0.9	Sitemap index with 16 per-section sitemaps covering all content types
/robots.txt	REP	Crawler directives with explicit AI bot permissions
/.well-known/security.txt	RFC 9116	Security vulnerability reporting contact information
/llms.txt	llms.txt	AI-readable site summary for LLM ingestion

Structured Data (JSON-LD)

Every page includes JSON-LD structured data for rich search results:

+ WebSite — with SearchAction for sitelinks search box
+ BreadcrumbList — navigation breadcrumbs on all pages
+ CollectionPage — index/list pages with numberOfItems
+ Article — guide pages with author, dates, and word count
+ DefinedTerm — glossary terms with definitions
+ WebApplication — interactive tools (converter, calculator, timer)

Internationalization

All content pages include hreflang alternate links for 15 languages: English (default), Korean, Japanese, Chinese (Simplified), Spanish, French, German, Portuguese, Russian, Arabic, Hindi, Thai, Vietnamese, Indonesian, and Turkish.

07 — OpenAPI

OpenAPI Specification

A machine-readable OpenAPI 3.1.0 specification is available for all 11 JSON API endpoints. Use it with Swagger UI, Postman, or code generators.

Download openapi.json

Fetch via command line

# Download the OpenAPI spec
curl "https://timefyi.com/api/openapi.json" -o openapi.json

# Pretty-print
curl -s "https://timefyi.com/api/openapi.json" | python -m json.tool

08 — Rate Limits

Rate Limits & Usage

Our APIs are free to use with no authentication required. To ensure fair access for everyone, please follow these guidelines:

+ Keep requests under 60 requests per minute per IP address
+ Include a descriptive User-Agent header identifying your application
+ Cache responses locally when possible — API responses include Cache-Control headers
+ For bulk data access, use the sitemap to discover all URLs, then use the .md endpoints
+ CORS is enabled on all API endpoints for browser-based requests

If you need higher-volume access or have integration questions, reach out via the contact in our security.txt.

09 — Quick Reference

Quick Reference

API Root /api/

Search /api/search/?q=...

City Detail /api/city/{slug}/

Country Detail /api/country/{slug}/

Cities List /api/cities/

Countries List /api/countries/

Time Lookup /api/v1/time/{tz}/

Compare /api/compare/?city1=&city2=

Glossary Term /api/glossary/{slug}/

Guide Detail /api/guide/{s}/{g}/

OpenAPI Spec /api/openapi.json

RSS Feed /guides/feed/

Atom Feed /guides/feed/atom/

llms.txt /llms.txt

Python pip install timefyi

npm npm install timefyi

CLI pip install "timefyi[cli]"

MCP pip install "timefyi[mcp]"

Site	Domain	Focus
UnitFYI	unitfyi.com	Unit conversion for 220 units across 20 categories
TimeFYI	timefyi.com	World clock, timezone converter, sunrise & sunset times
HolidayFYI	holidayfyi.com	Public holidays & observances for 200+ countries
NameFYI	namefyi.com	Name origins, romanization, and cultural naming traditions

Developer Documentation

Base URL

Endpoint Reference

City Detail

Search

Time Lookup

Compare Cities

Country Detail

Glossary Term

Python Package

npm Package

Command-Line Interface

MCP Server

RSS & Atom Feeds

AI / LLM Integration

SEO & Standards

Structured Data (JSON-LD)

Internationalization

OpenAPI Specification

Rate Limits & Usage

Quick Reference