# Stadiums API
> Stadiums and sports venues around the world as an API — 7,000+ stadiums from Wikidata with their seating capacity, country and city, geographic coordinates and year opened. Search and filter by name, country, minimum capacity and opening year (the results come back largest-first, so it doubles as a "biggest stadiums in the world" ranking), or find every stadium near any coordinate by great-circle distance. Ideal for sports, travel, ticketing, maps, trivia and matchday apps. Open data from Wikidata.

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

## Pricing
- **Free** (Free) — 3,900 calls/Mo, 2 req/s
- **Starter** ($5/Mo) — 52,000 calls/Mo, 8 req/s
- **Pro** ($13/Mo) — 250,000 calls/Mo, 20 req/s
- **Mega** ($36/Mo) — 1,230,000 calls/Mo, 50 req/s

## Endpoints

### Stadiums

#### `GET /v1/nearby` — Stadiums near a coordinate

**Parameters:**
- `lat` (query, optional, string) — Latitude (-90..90) Example: `51.55`
- `lon` (query, optional, string) — Longitude (-180..180) Example: `7.45`
- `radius_km` (query, optional, string) — Search radius in km (0.5-2000, default 25)
- `min_capacity` (query, optional, string) — Minimum seating capacity
- `limit` (query, optional, string) — Max results (1-100, default 20)

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/stadiums-api/v1/nearby?lat=51.55&lon=7.45"
```

**Response:**
```json
{
    "data": {
        "count": 2,
        "total": 2,
        "center": {
            "lat": 51.55,
            "lon": 7.45
        },
        "results": [
            {
                "name": "Wullen Stadium",
                "country": "Germany",
                "capacity": 12000,
                "latitude": 51.446092,
                "longitude": 7.360267,
                "distance_km": 13.12,
                "opened_year": 1926
            },
            {
                "name": "Ischelandstadion",
                "country": "Germany",
                "capacity": 32000,
                "latitude": 51.372239,
                "longitude": 7.478072,
                "distance_km": 19.86,
                "opened_year": 1926
            }
        ],
        "radius_km": 25
    },
    "meta": {
        "timestamp": "2026-05-31T08:35:48.281Z",
        "request_id": "2974e583-6cff-4a42-822b-704695bd98e0"
    },
    "status": "ok",
    "message": "Nearby stadiums retrieved",
    "success": true
}
```

#### `GET /v1/search` — Search & filter stadiums (largest first)

**Parameters:**
- `q` (query, optional, string) — Search by stadium name
- `country` (query, optional, string) — Country, e.g. Germany, Brazil Example: `Germany`
- `min_capacity` (query, optional, string) — Minimum seating capacity
- `year_from` (query, optional, string) — Opened in or after this year
- `limit` (query, optional, string) — Results per page (1-100, default 20) Example: `20`
- `offset` (query, optional, string) — Pagination offset Example: `0`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/stadiums-api/v1/search?country=Germany&limit=20&offset=0"
```

**Response:**
```json
{
    "data": {
        "count": 20,
        "limit": 20,
        "total": 104,
        "offset": 0,
        "filters": {
            "q": null,
            "country": "Germany",
            "year_from": null,
            "min_capacity": null
        },
        "results": [
            {
                "name": "Deutsches Stadion",
                "country": "Germany",
                "capacity": 400000,
                "latitude": 49.422197,
                "longitude": 11.114142,
                "opened_year": null
            },
            {
                "name": "Allianz Arena",
                "country": "Germany",
                "capacity": 75024,
                "latitude": 48.218775,
                "longitude": 11.624753,
                "opened_year": null
            },
            {
                "name": "Munich Olympic Stadium",
                "country": "Germany",
                "capacity": 63118,
                "latitude": 48.173056,
                "longitude": 11.546667,
                "opened_year": null
            },
            {
                "name": "Arena AufSchalke",
                "country": "Germany",
                "capacity": 62271,
                "latitude": 51.554503,
                "longitude": 7.067589,
                "opened_year": 2001
            },
            {
                "name": "MHPArena",
                "country": "Germany",
                "capacity": 60058,
                "latitude": 48.792222,
               
…(truncated, see openapi.json for full schema)
```

### Meta

#### `GET /v1/meta` — Totals, top countries & largest

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

**Response:**
```json
{
    "data": {
        "note": "Stadiums & sports venues worldwide. /v1/search defaults to largest-capacity first; filter by name, country, min_capacity and year_from. /v1/nearby finds venues near a coordinate.",
        "total": 7241,
        "fields": [
            "name",
            "country",
            "capacity",
            "latitude",
            "longitude",
            "opened_year"
        ],
        "source": "Wikidata (stadiums & sports venues)",
        "largest": [
            {
                "name": "Deutsches Stadion",
                "country": "Germany",
                "capacity": 400000
            },
            {
                "name": "Narendra Modi Stadium",
                "country": "India",
                "capacity": 132000
            },
            {
                "name": "Estádio da Luz (1954)",
                "country": "Portugal",
                "capacity": 120000
            },
            {
                "name": "Hassan II Stadium",
                "country": "Morocco",
                "capacity": 115000
            },
            {
                "name": "Michigan Stadium",
                "country": "United States",
                "capacity": 107601
            }
        ],
        "countries": 212,
        "top_countries": [
            {
                "count": 1117,
                "country": "United States"
            },
            {
                "count": 424,
                "country": "Lithuania"
            },

…(truncated, see openapi.json for full schema)
```


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