# Local-time clock: guide for AI agents

© 2026 Aesthetic Vulpes (github.com/didvc). Code AGPL-3.0-only.

This endpoint returns an SVG clock showing the current time in a chosen time zone, with optional annotations (city, UTC offset, date, working-hours status). The time is drawn by the server and kept running by CSS inside the image, so it ticks without scripts. No API keys, no user data.

## Endpoint

```
GET https://readmes.pages.dev/clock[/<token>[/<token>...]][.svg]
```

- Response: `image/svg+xml`, never cached (`Cache-Control: no-store`).
- Tokens are case-insensitive and order-independent; at most 16.
- An unknown token returns HTTP 200 with an error badge and `X-Clock-Error: unknown option #N`.
- Time zone tokens are IANA names, lowercased, with `/` replaced by `-` (Asia/Tokyo becomes `asia-tokyo`). 418 zones are available.

## Tokens

### Time zone

| Token | Meaning |
|---|---|
| `<zone>` | IANA time zone, lowercased, with / written as -. Examples: asia-tokyo, europe-berlin, america-new_york, america-argentina-buenos_aires. |
| `utc` | Coordinated Universal Time (default). |
| `utc+9`, `utc-5`, `utc+0530` | A fixed offset from UTC, without daylight saving time. |

### Clock

| Token | Meaning |
|---|---|
| `digital`, `analog` | Clock style (default digital). |
| `12h`, `24h` | Hour format for the digital clock (default 24h). |
| `seconds` | Show seconds (a second hand on the analog clock). |
| `size-N` | Size in pixels, 16 to 96 (default 40); also in rem, e.g. size-2rem (1rem = 16px). |
| `px` | Pin the image to exact pixels. By default it is sized in rem, so it grows with the reader's browser font size. |

### Annotation

| Token | Meaning |
|---|---|
| `label-city`, `label-local`, `label-my`, `nolabel` | First line: "Tokyo" (default), "Local time in Tokyo", "My time in Tokyo", or nothing. |
| `nooffset` | Hide the UTC offset, which is shown by default. |
| `date` | Add the weekday and date. |
| `work-H-H` | Working hours, e.g. work-9-18. Adds a live status line: working hours, off hours, weekend or probably asleep. |
| `sleep-H-H` | Sleeping hours for the status line (default sleep-23-7). |
| `days-mon-fri`, `everyday` | Which days are working days (default Monday to Friday). |
| `kaomoji` | Add a small face to the status line. Without work hours it shows morning, daytime, evening or night. |

### Look

| Token | Meaning |
|---|---|
| `card` | Rounded card background. |
| `border-N` | Card border in pixels, 0 to 8; implies card. |
| `color-RRGGBB` | Accent and time color as 3 or 6 hex digits without #. |
| `auto`, `light`, `dark`, `transparent` | Theme (default auto). |

## Examples

| Goal | URL |
|---|---|
| Tokyo, digital | https://readmes.pages.dev/clock/asia-tokyo |
| Berlin, analog with seconds and working hours | https://readmes.pages.dev/clock/europe-berlin/analog/seconds/work-9-17 |
| New York, 12-hour with date | https://readmes.pages.dev/clock/america-new_york/12h/date |
| Fixed offset UTC+5:30 with kaomoji | https://readmes.pages.dev/clock/utc+0530/kaomoji |

```markdown
![My local time](https://readmes.pages.dev/clock/asia-tokyo/work-9-18/card)
```

## Guidance for agents

- Map a user's city to the IANA zone name, not to a fixed offset, so daylight saving time is handled.
- Add alt text such as "My local time" when embedding.
- This is a best-effort free demo without warranty. Do not send automated high-volume traffic.

## More

- URL builder and option tables: https://readmes.pages.dev/clock/help
- Source, license and disclaimer: https://github.com/profile-readme/local-time-profile-clock