# 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"
```

**Response:**
```json
{
    "data": {
        "date": "2026-06-02T13:30:00.000Z",
        "parts": [
            {
                "type": "weekday",
                "value": "mardi"
            },
            {
                "type": "literal",
                "value": " "
            },
            {
                "type": "day",
                "value": "2"
            },
            {
                "type": "literal",
                "value": " "
            },
            {
                "type": "month",
                "value": "juin"
            },
            {
                "type": "literal",
                "value": " "
            },
            {
                "type": "year",
                "value": "2026"
            },
            {
                "type": "literal",
                "value": " à "
            },
            {
                "type": "hour",
                "value": "15"
            },
            {
                "type": "literal",
                "value": ":"
            },
            {
                "type": "minute",
                "value": "30"
            }
        ],
        "locale": "fr-FR",
        "timezone": "Europe/Paris",
        "formatted": "mardi 2 juin 2026 à 15:30"
    },
    "meta": {
        "timestamp": "2026-06-01T23:40:41.488Z",
        "request_id": "abe285cf-37ee-47e6-b1ed-f6d05ea04d6c"
    },
    "status": "ok",
    "message": "Date formatted",
    "success": true
}
```

#### `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"
```

**Response:**
```json
{
    "data": {
        "to": "2026-06-02T13:00:00.000Z",
        "from": "2026-06-02T10:00:00.000Z",
        "unit": "hour",
        "value": -3,
        "locale": "de",
        "is_past": true,
        "relative": "vor 3 Stunden",
        "seconds_diff": -10800
    },
    "meta": {
        "timestamp": "2026-06-01T23:40:41.586Z",
        "request_id": "f75ff6a7-7af4-4dd0-8822-0bf8db31c91a"
    },
    "status": "ok",
    "message": "Relative time computed",
    "success": true
}
```

### Meta

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

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

**Response:**
```json
{
    "data": {
        "note": "Humanise timestamps and format dates for any locale and timezone with full ICU. /v1/relative?from=2026-06-02T10:00:00Z&locale=de turns an instant into a localised relative phrase against now (or a given 'to') — 'vor 3 Stunden', '3 hours ago', 'in 2 days', 'il y a 5 minutes' — automatically choosing the best unit (second to year). /v1/format?date=...&locale=fr-FR&dateStyle=full&timeStyle=short&timezone=Europe/Paris renders a localised date/time string (e.g. 'mardi 2 juin 2026 à 15:30') with a parts breakdown, honouring the locale, named IANA timezone and 12/24-hour preference. Pass dates as ISO 8601 or unix timestamps. Everything is computed locally with no network calls. Ideal for internationalised UIs, 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 key, no cache.",
        "styles": [
            "full",
            "long",
            "medium",
            "short"
        ],
        "endpoints": [
            "/v1/relative",
            "/v1/format",
            "/v1/meta"
        ],
        "example_locales": [
            "en-US",
            "de-DE",
            "fr-FR",
            "es-ES",
            "ja-JP",
            "ar-EG",
            "pt-BR",
            "zh-CN"
        ]
    },
    "meta": {
        "timestamp": "2026-06-01T23:40:41.683Z",
 
…(truncated, see openapi.json for full schema)
```


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