# DateTime API
> A fast, fully-local date and time toolkit (UTC): parse any date string or unix timestamp into ISO, unix and components with the ISO week number, day-of-year and leap-year flag; format dates with custom tokens (YYYY-MM-DD, weekday and month names, and more); add or subtract month-aware durations; compute the difference between two dates in every unit plus a human-readable summary; and convert between unix timestamps and ISO. Every endpoint accepts input via the query string or the request body. Pure server-side compute, no third-party upstream, so responses are instant and always available. Ideal for scheduling, billing periods, reminders, analytics and any date arithmetic. (For the current time in a specific timezone, see the oanor Time API.)

## 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/datetime-api/..."
```

## Pricing
- **Free** (Free) — 18,000 calls/Mo, 5 req/s
- **Basic** ($4/Mo) — 260,000 calls/Mo, 15 req/s
- **Pro** ($13/Mo) — 1,700,000 calls/Mo, 40 req/s
- **Mega** ($35/Mo) — 9,000,000 calls/Mo, 120 req/s

## Endpoints

### DateTime

#### `GET /v1/add` — Add/subtract a duration

**Parameters:**
- `date` (query, required, string) — Date string Example: `2026-05-30T00:00:00Z`
- `years` (query, optional, string) — Years Example: `0`
- `months` (query, optional, string) — Months Example: `0`
- `days` (query, optional, string) — Days Example: `10`
- `hours` (query, optional, string) — Hours Example: `0`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/datetime-api/v1/add?date=2026-05-30T00%3A00%3A00Z&years=0&months=0&days=10&hours=0"
```

**Response:**
```json
{
    "data": {
        "input": "2026-05-30T00:00:00Z",
        "result_iso": "2026-06-09T00:00:00.000Z",
        "result_unix": 1780963200
    },
    "meta": {
        "timestamp": "2026-05-30T09:00:23.150Z",
        "request_id": "0d573f08-6622-4519-b40f-e846ddd34f8b"
    },
    "status": "ok",
    "message": "OK",
    "success": true
}
```

#### `GET /v1/diff` — Difference between two dates

**Parameters:**
- `from` (query, required, string) — Start Example: `2026-01-01T00:00:00Z`
- `to` (query, required, string) — End Example: `2026-05-30T00:00:00Z`
- `unit` (query, optional, string) — Single unit (omit for all) Example: `days`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/datetime-api/v1/diff?from=2026-01-01T00%3A00%3A00Z&to=2026-05-30T00%3A00%3A00Z&unit=days"
```

**Response:**
```json
{
    "data": {
        "to": "2026-05-30T00:00:00.000Z",
        "from": "2026-01-01T00:00:00.000Z",
        "unit": "days",
        "human": "4 months, 27 days",
        "value": 149
    },
    "meta": {
        "timestamp": "2026-05-30T09:00:23.222Z",
        "request_id": "e62ac9eb-557b-4009-ada9-6e7f9c955d9c"
    },
    "status": "ok",
    "message": "OK",
    "success": true
}
```

#### `GET /v1/format` — Format a date

**Parameters:**
- `date` (query, required, string) — Date string or unix timestamp Example: `2026-05-30T08:05:09Z`
- `format` (query, optional, string) — Token format Example: `dddd, DD MMMM YYYY`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/datetime-api/v1/format?date=2026-05-30T08%3A05%3A09Z&format=dddd%2C+DD+MMMM+YYYY"
```

**Response:**
```json
{
    "data": {
        "input": "2026-05-30T08:05:09Z",
        "format": "dddd, DD MMMM YYYY",
        "formatted": "Saturday, 30 May 2026"
    },
    "meta": {
        "timestamp": "2026-05-30T09:00:23.289Z",
        "request_id": "dbcfd791-b964-4c3b-a8bc-e0f4e3a6f5f0"
    },
    "status": "ok",
    "message": "OK",
    "success": true
}
```

#### `GET /v1/parse` — Parse a date

**Parameters:**
- `date` (query, required, string) — Date string or unix timestamp Example: `2026-05-30T12:00:00Z`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/datetime-api/v1/parse?date=2026-05-30T12%3A00%3A00Z"
```

**Response:**
```json
{
    "data": {
        "day": 30,
        "iso": "2026-05-30T12:00:00.000Z",
        "hour": 12,
        "unix": 1780142400,
        "year": 2026,
        "input": "2026-05-30T12:00:00Z",
        "month": 5,
        "minute": 0,
        "second": 0,
        "unix_ms": 1780142400000,
        "weekday": 6,
        "iso_week": 22,
        "month_name": "May",
        "day_of_year": 150,
        "is_leap_year": false,
        "weekday_name": "Saturday"
    },
    "meta": {
        "timestamp": "2026-05-30T09:00:23.359Z",
        "request_id": "0b8a4334-72f3-4900-8607-552185800c0e"
    },
    "status": "ok",
    "message": "OK",
    "success": true
}
```

#### `GET /v1/unix` — Unix <-> ISO conversion

**Parameters:**
- `timestamp` (query, optional, string) — Unix timestamp Example: `1748600000`
- `date` (query, optional, string) — Date string (alternative)

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/datetime-api/v1/unix?timestamp=1748600000"
```

**Response:**
```json
{
    "data": {
        "iso": "2025-05-30T10:13:20.000Z",
        "unix": 1748600000,
        "input": "1748600000",
        "unix_ms": 1748600000000
    },
    "meta": {
        "timestamp": "2026-05-30T09:00:23.432Z",
        "request_id": "ea1498d0-c54a-4fd2-9561-7ac6be8f810c"
    },
    "status": "ok",
    "message": "OK",
    "success": true
}
```


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