🕐 TimeFYI

Developer Documentation

Comprehensive time and timezone reference for developers, travelers, and remote teams. 500 cities across 196 countries with real-time clocks, sunrise/sunset times, DST tracking, 200 glossary terms, 150 guides, 24 solar terms, 41 timezone abbreviations, 6 interactive tools, and N-squared time difference pages. All times computed on-the-fly via pure-Python TimeEngine.

Quick Start

curl -s "https://timefyi.com/api/city/tokyo/"

API Endpoints

Method Endpoint Description
GET /api/search/ Autocomplete city search
GET /api/city/{slug}/ City detail with current time and sun info
GET /api/country/{slug}/ Country detail with cities
GET /api/cities/ List all cities
GET /api/countries/ List all countries
GET /api/compare/ Time difference between cities
GET /api/v1/time/{timezone_id}/ Current time in a timezone (IANA ID)
GET /api/glossary/{slug}/ Glossary term detail
GET /api/guide/{series}/{slug}/ Guide article detail
GET /api/v1/cities/ Cities (DRF ViewSet, paginated)
GET /api/v1/countries/ Countries (DRF ViewSet, paginated)
GET /api/v1/glossary/ Glossary terms (DRF ViewSet, paginated)
GET /api/v1/guides/ Guides (DRF ViewSet, paginated)
GET /api/v1/tools/ Tools (DRF ViewSet)
GET /api/v1/faqs/ FAQs (DRF ViewSet)
GET /api/v1/search/?q={query} Unified search (DRF)
GET /api/v1/stats/ Site statistics

URL Patterns

Use these patterns to construct URLs programmatically:

/ Homepage — world clock with featured cities (e.g. /)
/worldclock/ World clock with all featured cities (e.g. /worldclock/)
/time/ Browse all cities by region (e.g. /time/)
/time/{slug}/ City detail — current time, sunrise/sunset, timezone info (e.g. /time/new-york/)
/country/{slug}/ Country detail with cities and timezone info (e.g. /country/united-states/)
/timezone/{slug}/ Timezone detail with cities (e.g. /timezone/america-new-york/)
/difference/{city1}-vs-{city2}/ Time difference between two cities (N² pSEO) (e.g. /difference/new-york-vs-tokyo/)
/convert/{tz1}-to-{tz2}/ Timezone conversion tool (e.g. /convert/pst-to-jst/)
/sun/{slug}/ Sunrise/sunset times for a city (e.g. /sun/tokyo/)
/dst/{slug}/ DST schedule for a country (e.g. /dst/united-states/)
/offset/{offset}/ Cities in a UTC offset (e.g. /offset/utc-plus-9/)
/continent/{slug}/ Continental overview (e.g. /continent/asia/)
/abbreviation/{slug}/ Timezone abbreviation detail (e.g. /abbreviation/pst/)
/popular/ Popular city pair comparisons (e.g. /popular/)
/popular/{slug}/ Popular pair detail (e.g. /popular/new-york-vs-london/)
/solar-terms/ 24 East Asian solar terms (e.g. /solar-terms/)
/solar-terms/{slug}/ Solar term detail (e.g. /solar-terms/spring-equinox/)
/calendar/ Calendar with holidays and events (e.g. /calendar/)
/holidays/ Holidays browser (e.g. /holidays/)
/glossary/ Time and timezone glossary index (e.g. /glossary/)
/glossary/{slug}/ Glossary term detail (e.g. /glossary/utc/)
/guides/ In-depth guides on time and timezones (e.g. /guides/)
/guides/{series}/{slug}/ Guide article (e.g. /guides/timezone-basics/what-is-utc/)
/tools/ Interactive time tools index (e.g. /tools/)
/tools/{slug}/ Tool page (e.g. /tools/converter/)
/search/ Search cities, countries, timezones (e.g. /search/?q=tokyo)

Response Format

All endpoints return JSON with pagination:

Example JSON response 
{
  "count": 636,
  "next": "https://example.com/api/v1/items/?page=2",
  "previous": null,
  "results": [
    {"slug": "example", "name": "Example Item", "...": "..."}
  ]
}

OpenAPI Specification

Full API schema available as OpenAPI 3.1.0 JSON. Import into Swagger UI, Postman, or any OpenAPI-compatible tool.

SDK Packages

PyPI
pip install timefyi

Timezone ops, business hours, sunrise/sunset (v0.1.2)

npm
npm install timefyi

TypeScript timezone utilities (v0.1.1)

Embed Widget

Embed data cards on your site: https://widget.timefyi.com
npm install timefyi-embed

Format Support

  • Markdown endpoints: Append .md to any page URL for LLM-friendly markdown output.
  • Internationalization: Content available in 14 languages: ko, ja, zh-hans, es, fr, de, pt, ru, vi, tr, ar, hi, th, id.