# Elo Rating API
> Compute Elo ratings — the rating system behind chess, esports, games and competitive leaderboards. The expected endpoint takes two players' ratings and returns each side's win probability using the classic logistic formula 1 / (1 + 10^((Rb − Ra) / 400)), names the favourite and reports the rating gap. The match endpoint applies a result — a win, loss or draw for player A — and returns both players' updated ratings, the exact points each one gained or lost, and the expected scores, using a configurable K-factor (32 by default; lower for established players, higher for newcomers, so ratings settle or move quickly as you choose). An upset is rewarded with a bigger swing and a draw shifts points toward the underdog, exactly as Elo intends. Everything is computed locally and deterministically, so it is instant and private — no players or leaderboard are stored. Ideal for games and esports matchmaking, chess and board-game apps, tournament and ladder systems, ranking and reputation features, and A/B-style skill comparisons. Pure local computation — no key, no third-party service, instant. Live, nothing stored. 3 endpoints. This computes ratings from inputs you provide; it does not store a leaderboard or look up a player's rating.

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

## Pricing
- **Free** (Free) — 4,835 calls/Mo, 2 req/s
- **Starter** ($6/Mo) — 14,350 calls/Mo, 8 req/s
- **Pro** ($26/Mo) — 194,500 calls/Mo, 20 req/s
- **Mega** ($64/Mo) — 1,015,000 calls/Mo, 50 req/s

## Endpoints

### Elo

#### `GET /v1/expected` — Win probability

**Parameters:**
- `a` (query, required, string) — Player A's rating Example: `2000`
- `b` (query, required, string) — Player B's rating Example: `1500`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/elo-api/v1/expected?a=2000&b=1500"
```

**Response:**
```json
{
    "data": {
        "a": 2000,
        "b": 1500,
        "favorite": "a",
        "expected_a": 0.9468,
        "expected_b": 0.0532,
        "rating_difference": 500
    },
    "meta": {
        "timestamp": "2026-06-03T17:42:19.585Z",
        "request_id": "78c30b48-d8cd-4469-9f60-2fd454f81f18"
    },
    "status": "ok",
    "message": "Win probability",
    "success": true
}
```

#### `GET /v1/match` — Update ratings

**Parameters:**
- `a` (query, required, string) — Player A's rating Example: `1600`
- `b` (query, required, string) — Player B's rating Example: `1400`
- `result` (query, required, string) — a (A wins), b (B wins), draw — or 1, 0.5, 0 Example: `a`
- `k` (query, optional, string) — K-factor (default 32) Example: `32`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/elo-api/v1/match?a=1600&b=1400&result=a&k=32"
```

**Response:**
```json
{
    "data": {
        "a": 1600,
        "b": 1400,
        "k": 32,
        "new_a": 1608,
        "new_b": 1392,
        "result": "a",
        "change_a": 8,
        "change_b": -8,
        "expected_a": 0.7597,
        "expected_b": 0.2403,
        "new_a_precise": 1607.69,
        "new_b_precise": 1392.31
    },
    "meta": {
        "timestamp": "2026-06-03T17:42:19.686Z",
        "request_id": "cb65e19c-feeb-43cd-b42d-aac4d770fd70"
    },
    "status": "ok",
    "message": "Update ratings",
    "success": true
}
```

### Meta

#### `GET /v1/meta` — Spec

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

**Response:**
```json
{
    "data": {
        "name": "Elo Rating API",
        "notes": "Expected score Ea = 1 / (1 + 10^((Rb − Ra) / 400)); new rating = R + K × (score − expected). A higher K-factor makes ratings move faster (32 is common; 16–24 for established players, 40 for new ones). Ratings are returned rounded to whole numbers, with a precise value alongside. This computes ratings — it does not store players or a leaderboard. Nothing is stored.",
        "version": "v1",
        "endpoints": [
            {
                "path": "/v1/expected",
                "params": {
                    "a": "player A's rating (required)",
                    "b": "player B's rating (required)"
                },
                "returns": "the win probability of each player and the favourite"
            },
            {
                "path": "/v1/match",
                "params": {
                    "a": "player A's rating (required)",
                    "b": "player B's rating (required)",
                    "k": "K-factor (default 32)",
                    "result": "a (A wins), b (B wins), draw — or 1, 0.5, 0 for A"
                },
                "returns": "both updated ratings, the point changes and expected scores"
            },
            {
                "path": "/v1/meta",
                "params": [],
                "returns": "this document"
            }
        ],
        "description": "Compute Elo ratings — the rating system used in chess, esports, games a
…(truncated, see openapi.json for full schema)
```


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