# Olympic Medals API
> The all-time Olympic medal table as an API — cumulative Summer and Winter Olympic results for every National Olympic Committee. For each country: its NOC code and, split into Summer / Winter / Combined, the number of Games attended and the gold, silver, bronze and total medals won. Look a country up by name or NOC code, rank countries by any medal metric (all-time gold, winter gold, totals and more), or search. A stable sports reference for quiz, media, sports and data-viz apps. Distinct from single-Games results.

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

## Pricing
- **Free** (Free) — 400 calls/Mo, 5 req/s
- **Hobby** ($6/Mo) — 12,000 calls/Mo, 12 req/s
- **Pro** ($14/Mo) — 50,000 calls/Mo, 25 req/s
- **Business** ($32/Mo) — 200,000 calls/Mo, 40 req/s

## Endpoints

### Medals

#### `GET /v1/country` — Country medal totals

**Parameters:**
- `name` (query, optional, string) — Country name (preferred) Example: `United States`
- `noc` (query, optional, string) — NOC code, e.g. USA

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/olympicmedals-api/v1/country?name=United+States"
```

**Response:**
```json
{
    "data": {
        "country": {
            "noc": "USA",
            "total": {
                "gold": 1072,
                "games": 48,
                "total": 2681,
                "bronze": 750,
                "silver": 859
            },
            "summer": {
                "gold": 976,
                "games": 26,
                "total": 2399,
                "bronze": 666,
                "silver": 757
            },
            "winter": {
                "gold": 96,
                "games": 22,
                "total": 282,
                "bronze": 84,
                "silver": 102
            },
            "country": "United States"
        }
    },
    "meta": {
        "timestamp": "2026-06-09T03:03:47.898Z",
        "request_id": "320db0ba-72c7-42e0-9420-656cbec50e8c"
    },
    "status": "ok",
    "message": "Country retrieved successfully",
    "success": true
}
```

#### `GET /v1/list` — List all countries

**Parameters:**
- `limit` (query, optional, string) — Max 1-300 Example: `50`
- `offset` (query, optional, string) — Offset Example: `0`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/olympicmedals-api/v1/list?limit=50&offset=0"
```

**Response:**
```json
{
    "data": {
        "count": 50,
        "total": 145,
        "countries": [
            {
                "noc": "AFG",
                "total": {
                    "gold": 0,
                    "games": 13,
                    "total": 2,
                    "bronze": 2,
                    "silver": 0
                },
                "summer": {
                    "gold": 0,
                    "games": 13,
                    "total": 2,
                    "bronze": 2,
                    "silver": 0
                },
                "winter": {
                    "gold": 0,
                    "games": 0,
                    "total": 0,
                    "bronze": 0,
                    "silver": 0
                },
                "country": "Afghanistan"
            },
            {
                "noc": "ALG",
                "total": {
                    "gold": 5,
                    "games": 15,
                    "total": 15,
                    "bronze": 8,
                    "silver": 2
                },
                "summer": {
                    "gold": 5,
                    "games": 12,
                    "total": 15,
                    "bronze": 8,
                    "silver": 2
                },
                "winter": {
                    "gold": 0,
                    "games": 3,
                    "total": 0,
                    "bronze": 0,
                    "silver": 0
                },
                "country": "
…(truncated, see openapi.json for full schema)
```

#### `GET /v1/search` — Search countries

**Parameters:**
- `q` (query, required, string) — Search term Example: `united`
- `limit` (query, optional, string) — Max 1-100 Example: `25`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/olympicmedals-api/v1/search?q=united&limit=25"
```

**Response:**
```json
{
    "data": {
        "count": 3,
        "query": "united",
        "total": 3,
        "countries": [
            {
                "noc": "USA",
                "total": {
                    "gold": 1072,
                    "games": 48,
                    "total": 2681,
                    "bronze": 750,
                    "silver": 859
                },
                "summer": {
                    "gold": 976,
                    "games": 26,
                    "total": 2399,
                    "bronze": 666,
                    "silver": 757
                },
                "winter": {
                    "gold": 96,
                    "games": 22,
                    "total": 282,
                    "bronze": 84,
                    "silver": 102
                },
                "country": "United States"
            },
            {
                "noc": "EUA",
                "total": {
                    "gold": 36,
                    "games": 6,
                    "total": 137,
                    "bronze": 41,
                    "silver": 60
                },
                "summer": {
                    "gold": 28,
                    "games": 3,
                    "total": 118,
                    "bronze": 36,
                    "silver": 54
                },
                "winter": {
                    "gold": 8,
                    "games": 3,
                    "total": 19,
                    "bronze": 5,
                    
…(truncated, see openapi.json for full schema)
```

### Rankings

#### `GET /v1/rank` — Rank countries by a medal metric

**Parameters:**
- `by` (query, optional, string) — gold|silver|bronze|total|summer_gold|summer_total|winter_gold|winter_total|games Example: `gold`
- `order` (query, optional, string) — desc or asc Example: `desc`
- `limit` (query, optional, string) — Max 1-200 Example: `10`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/olympicmedals-api/v1/rank?by=gold&order=desc&limit=10"
```

**Response:**
```json
{
    "data": {
        "count": 10,
        "order": "desc",
        "metric": "gold",
        "ranking": [
            {
                "noc": "USA",
                "total": {
                    "gold": 1072,
                    "games": 48,
                    "total": 2681,
                    "bronze": 750,
                    "silver": 859
                },
                "value": 1072,
                "summer": {
                    "gold": 976,
                    "games": 26,
                    "total": 2399,
                    "bronze": 666,
                    "silver": 757
                },
                "winter": {
                    "gold": 96,
                    "games": 22,
                    "total": 282,
                    "bronze": 84,
                    "silver": 102
                },
                "country": "United States",
                "position": 1
            },
            {
                "noc": "URS",
                "total": {
                    "gold": 473,
                    "games": 18,
                    "total": 1204,
                    "bronze": 355,
                    "silver": 376
                },
                "value": 473,
                "summer": {
                    "gold": 395,
                    "games": 9,
                    "total": 1010,
                    "bronze": 296,
                    "silver": 319
                },
                "winter": {
                    "gold": 78,
             
…(truncated, see openapi.json for full schema)
```

### Meta

#### `GET /v1/meta` — Service metadata

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

**Response:**
```json
{
    "data": {
        "service": "olympicmedals-api",
        "endpoints": {
            "GET /v1/list": "List all countries (limit, offset).",
            "GET /v1/meta": "This document.",
            "GET /v1/rank": "Rank countries by a metric (by=gold|silver|bronze|total|summer_gold|winter_gold|…, order, limit).",
            "GET /v1/search": "Search countries by name or NOC (q=).",
            "GET /v1/country": "Country by name (name=, e.g. United States) or NOC code (noc=, e.g. USA)."
        },
        "total_gold": 5767,
        "description": "All-time Olympic medal table (Summer + Winter) for every National Olympic Committee: Games attended and gold/silver/bronze/total, split Summer/Winter/Combined. Look up by name or NOC code, rank by any medal metric, or search. Distinct from rio2016-api. No key.",
        "total_bronze": 6075,
        "total_silver": 5729,
        "total_countries": 145,
        "rankable_metrics": [
            "gold",
            "silver",
            "bronze",
            "total",
            "games",
            "summer_gold",
            "summer_total",
            "winter_gold",
            "winter_total"
        ]
    },
    "meta": {
        "timestamp": "2026-06-09T03:03:48.245Z",
        "request_id": "807c9997-73c1-4d2e-87bd-76506315494e"
    },
    "status": "ok",
    "message": "Meta",
    "success": true
}
```


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