# Relative Time & Locale Date API
> Humanise timestamps and format dates for any locale and timezone using full ICU. The relative endpoint turns an instant into a localised relative phrase against now (or a given reference time) — "3 hours ago", "vor 3 Stunden", "in 2 days", "il y a 5 minutes" — automatically choosing the best unit from seconds to years. The format endpoint renders a localised date/time string (e.g. "mardi 2 juin 2026 à 15:30" or "2026年6月2日 22:30:00"), honouring the locale (BCP 47), a named IANA timezone, the chosen date and time styles (full/long/medium/short) and 12/24-hour preference, and returns a parts breakdown for custom displays. Pass dates as ISO 8601 or unix timestamps. Everything is computed locally with no network calls. Ideal for internationalised UIs, activity feeds, notifications, comments and dashboards. A relative-time and locale date formatter — distinct from current-time-in-a-timezone (time), the UTC parse/token toolkit (datetime) and number/currency formatting (numberformat). No upstream key, no cache.

## Authentication
All requests require your oanor API key in the `x-oanor-key` header. Get one at https://www.oanor.com/developer/keys.

```bash
curl -H "x-oanor-key: oanor_live_…" "https://api.oanor.com/datelocale-api/..."
```

## Pricing
- **Free** (Free) — 2,060 calls/Mo, 2 req/s
- **Starter** ($6/Mo) — 39,000 calls/Mo, 8 req/s
- **Pro** ($20/Mo) — 208,000 calls/Mo, 20 req/s
- **Mega** ($52/Mo) — 800,000 calls/Mo, 50 req/s

## Endpoints

### Relative Time

#### `GET /v1/format` — Locale + timezone date display

**Parameters:**
- `date` (query, required, string) — The date (ISO/unix) Example: `2026-06-02T13:30:00Z`
- `locale` (query, optional, string) — BCP 47 locale Example: `fr-FR`
- `dateStyle` (query, optional, string) — full, long, medium, short Example: `full`
- `timeStyle` (query, optional, string) — full, long, medium, short Example: `short`
- `timezone` (query, optional, string) — IANA timezone Example: `Europe/Paris`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/datelocale-api/v1/format?date=2026-06-02T13%3A30%3A00Z&locale=fr-FR&dateStyle=full&timeStyle=short&timezone=Europe%2FParis"
```

#### `GET /v1/relative` — Humanised relative time

**Parameters:**
- `from` (query, required, string) — The event time (ISO/unix) Example: `2026-06-02T10:00:00Z`
- `to` (query, optional, string) — Reference time (default now) Example: `2026-06-02T13:00:00Z`
- `locale` (query, optional, string) — BCP 47 locale Example: `de`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/datelocale-api/v1/relative?from=2026-06-02T10%3A00%3A00Z&to=2026-06-02T13%3A00%3A00Z&locale=de"
```

### Meta

#### `GET /v1/meta` — Styles & locales

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/datelocale-api/v1/meta"
```


---
Marketplace page: https://www.oanor.com/api/datelocale-api
OpenAPI spec: https://www.oanor.com/api/datelocale-api/openapi.json