# World Clock API

Read-only JSON API for IANA-accurate world time, served by a single Cloudflare Worker.

- Base URL: `https://time.cogpu.com`
- Auth: none
- CORS: `Access-Control-Allow-Origin: *`
- Cache: `no-store` (always live)

## GET /api/time

Local time for every city in the index — the same payload that powers the web UI. Includes live UTC offset, day-part and day offset against a reference timezone.

| Param | Type | Description |
| --- | --- | --- |
| `tz` | string | Reference timezone used to compute `dayDelta` ("+1 day" / "Same day"). Any valid IANA name. Default `UTC`. |
| `city` | string | Filter by city name. Repeat the parameter or comma-separate: `?city=Tokyo&city=Paris` / `?city=Tokyo,Paris`. |
| `q` | string | Free-text search across city, country and timezone (e.g. `?q=asia/`). |
| `sort` | string | `offset` (UTC offset, default) · `name` (A–Z) · `hour` (local wall clock). |
| `limit` | number | Cap the number of returned cities. |

```bash
curl -s "https://time.cogpu.com/api/time?city=Tokyo,Paris&tz=Asia/Tokyo"
```

```json
{
  "now": "2026-09-09T11:10:00.000Z",
  "baseTimeZone": "Asia/Tokyo",
  "count": 2,
  "cities": [
    {
      "city": "Tokyo", "country": "Japan", "tz": "Asia/Tokyo",
      "hour": 20, "minute": 10, "second": 0, "weekday": "Wed",
      "date": "9 Sep", "offsetMinutes": 540, "offset": "UTC+9",
      "dayDelta": 0, "dayProgress": 84.03,
      "phase": "Evening", "phaseIcon": "🌆"
    },
    {
      "city": "Paris", "country": "France", "tz": "Europe/Paris",
      "hour": 13, "minute": 10, "second": 0, "weekday": "Wed",
      "date": "9 Sep", "offsetMinutes": 120, "offset": "UTC+2",
      "dayDelta": 0, "dayProgress": 54.86,
      "phase": "Midday", "phaseIcon": "🌤"
    }
  ]
}
```

## GET /api/now

Current time in any single IANA timezone, resolved with full DST rules. Lightweight — use it instead of `/api/time` when you only need one zone.

| Param | Type | Description |
| --- | --- | --- |
| `tz` | string | Any IANA timezone name, e.g. `Asia/Kathmandu`, `America/New_York`. Default `UTC`. |
| `format` | string | `json` (default) or `text` — `text` returns a one-line `2026-09-09 16:55:35 UTC+5:45`. |

```bash
curl -s "https://time.cogpu.com/api/now?tz=Asia/Kathmandu"
```

```json
{
  "timezone": "Asia/Kathmandu",
  "epoch": 1789000000,
  "epochMs": 1789000000000,
  "iso": "2026-09-09T16:55:35+05:45",
  "date": "Wed, 9 Sep 2026",
  "time": "16:55:35",
  "hour": 16, "minute": 55, "second": 35,
  "weekday": "Wed", "day": 9, "month": "Sep", "year": 2026,
  "offset": "UTC+5:45", "offsetMinutes": 345,
  "phase": "Afternoon", "phaseIcon": "🌇"
}
```

## GET /api/cities

The city index itself: name, country, IANA timezone and current offset. Handy for building your own picker or autocomplete.

| Param | Type | Description |
| --- | --- | --- |
| `q` | string | Search across city, country and timezone. |
| `limit` | number | Cap the number of results. |
| `offsets` | boolean | Set to `1` to include the live UTC offset of each city. |

```bash
curl -s "https://time.cogpu.com/api/cities?q=asia&limit=3"
```

```json
{
  "count": 3,
  "cities": [
    { "city": "Dubai", "country": "UAE", "tz": "Asia/Dubai", "offset": "UTC+4", "offsetMinutes": 240 },
    { "city": "Riyadh", "country": "Saudi Arabia", "tz": "Asia/Riyadh", "offset": "UTC+3", "offsetMinutes": 180 },
    { "city": "Karachi", "country": "Pakistan", "tz": "Asia/Karachi", "offset": "UTC+5", "offsetMinutes": 300 }
  ]
}
```

## GET /api/convert

Convert one instant into one or many timezones. Accepts an ISO 8601 string or a Unix epoch (seconds or milliseconds). Defaults to `now`.

| Param | Type | Description |
| --- | --- | --- |
| `time` | string | ISO 8601 (`2026-12-25T09:00:00Z`) or Unix epoch in seconds / milliseconds. Default: now. |
| `from` | string | Timezone the `time` value is expressed in, when it carries no offset. Default `UTC`. |
| `to` | string | Required. Target timezone(s), comma-separated. |

```bash
curl -s "https://time.cogpu.com/api/convert?time=2026-12-25T09:00:00Z&from=UTC&to=Asia/Tokyo,America/New_York"
```

```json
{
  "input": { "time": "2026-12-25T09:00:00Z", "from": "UTC", "instant": "2026-12-25T09:00:00.000Z" },
  "count": 2,
  "results": [
    { "tz": "Asia/Tokyo", "iso": "2026-12-25T18:00:00+09:00", "date": "Fri, 25 Dec 2026",
      "time": "18:00:00", "offset": "UTC+9", "offsetMinutes": 540, "phase": "Night" },
    { "tz": "America/New_York", "iso": "2026-12-25T04:00:00-05:00", "date": "Fri, 25 Dec 2026",
      "time": "04:00:00", "offset": "UTC-5", "offsetMinutes": -300, "phase": "Night" }
  ]
}
```

## GET /openapi.json

Machine-readable OpenAPI 3.1 description of every endpoint above. Import it into Postman, Insomnia, or generate a typed client with openapi-generator.

```bash
curl -s "https://time.cogpu.com/openapi.json"
```

```json
{
  "openapi": "3.1.0",
  "info": { "title": "ColorOS 16 World Clock API", "version": "1.0.0" },
  "paths": { "/api/time": { "get": { "summary": "Time for every city" } }, "..." : {} }
}
```

## GET /api/docs

This documentation rendered as plain Markdown (`text/markdown`) — easy to pipe into a terminal or paste into a README.

```bash
curl -s "https://time.cogpu.com/api/docs"
```

```json
# World Clock API

Base URL: https://<your-worker>.workers.dev
Auth: none · CORS: enabled (Access-Control-Allow-Origin: *)

## GET /api/time
Local time for every city ...
```

---

Times are computed with `Intl.DateTimeFormat` on the full IANA database;
offsets are derived per-instant, so DST transitions are handled automatically.