# Soccer API
> Live soccer (football) data for the world's top leagues as an API — clean JSON, no key. Get the full league table for any competition (rank, played, wins, draws, losses, goals for/against, goal difference and points), list every team and open a team for its record, form and standing, pull matches and results for any date, and open a match for its full detail — line-ups, formations and scorers. Read league news too. Covers the Premier League, La Liga, Serie A, Bundesliga, Ligue 1, Eredivisie, Primeira Liga, the Champions League and more — pass the league id (see /v1/leagues). Live data sourced continuously from ESPN. The world's most popular sport with an enormous betting and fantasy market — ideal for score apps, league-table widgets, betting tools, dashboards and Discord bots. 7 data endpoints. Authenticated with an x-oanor-key; fair-use rate limits per plan.

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

## Pricing
- **Free** (Free) — 3,000 calls/Mo, 5 req/s
- **Starter** ($10/Mo) — 58,000 calls/Mo, 15 req/s
- **Pro** ($39/Mo) — 320,000 calls/Mo, 30 req/s
- **Mega** ($135/Mo) — 1,500,000 calls/Mo, 80 req/s

## Endpoints

### Reference

#### `GET /v1/leagues` — Supported leagues

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

**Response:**
```json
{
    "data": {
        "count": 15,
        "leagues": [
            {
                "id": "eng.1",
                "name": "English Premier League"
            },
            {
                "id": "esp.1",
                "name": "Spanish La Liga"
            },
            {
                "id": "ita.1",
                "name": "Italian Serie A"
            },
            {
                "id": "ger.1",
                "name": "German Bundesliga"
            },
            {
                "id": "fra.1",
                "name": "French Ligue 1"
            },
            {
                "id": "ned.1",
                "name": "Dutch Eredivisie"
            },
            {
                "id": "por.1",
                "name": "Portuguese Primeira Liga"
            },
            {
                "id": "eng.2",
                "name": "English Championship"
            },
            {
                "id": "usa.1",
                "name": "Major League Soccer"
            },
            {
                "id": "mex.1",
                "name": "Mexican Liga MX"
            },
            {
                "id": "bra.1",
                "name": "Brazilian Serie A"
            },
            {
                "id": "uefa.champions",
                "name": "UEFA Champions League"
            },
            {
                "id": "uefa.europa",
                "name": "UEFA Europa League"
            },
            {
                "id": "eng.fa",
                "
…(truncated, see openapi.json for full schema)
```

### Standings

#### `GET /v1/standings` — League table

**Parameters:**
- `league` (query, optional, string) — League id (e.g. eng.1, esp.1, ita.1, ger.1) — see /v1/leagues Example: `eng.1`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/soccer-api/v1/standings?league=eng.1"
```

**Response:**
```json
{
    "data": {
        "count": 20,
        "table": [
            {
                "id": "359",
                "logo": "https://a.espncdn.com/i/teamlogos/soccer/500/359.png",
                "rank": 1,
                "team": "Arsenal",
                "wins": 26,
                "draws": 7,
                "losses": 5,
                "played": 38,
                "points": 85,
                "goals_for": 71,
                "goals_against": 27,
                "goal_difference": 44
            },
            {
                "id": "382",
                "logo": "https://a.espncdn.com/i/teamlogos/soccer/500/382.png",
                "rank": 2,
                "team": "Manchester City",
                "wins": 23,
                "draws": 9,
                "losses": 6,
                "played": 38,
                "points": 78,
                "goals_for": 77,
                "goals_against": 35,
                "goal_difference": 42
            },
            {
                "id": "360",
                "logo": "https://a.espncdn.com/i/teamlogos/soccer/500/360.png",
                "rank": 3,
                "team": "Manchester United",
                "wins": 20,
                "draws": 11,
                "losses": 7,
                "played": 38,
                "points": 71,
                "goals_for": 69,
                "goals_against": 50,
                "goal_difference": 19
            },
            {
                "id": "362",
                "logo":
…(truncated, see openapi.json for full schema)
```

### Matches

#### `GET /v1/match` — Match detail (line-ups, scorers)

**Parameters:**
- `league` (query, optional, string) — League id (e.g. eng.1, esp.1, ita.1, ger.1) — see /v1/leagues Example: `eng.1`
- `id` (query, required, string) — Match id Example: `740966`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/soccer-api/v1/match?league=eng.1&id=740966"
```

**Response:**
```json
{
    "data": {
        "match": {
            "id": "740966",
            "name": "Brighton & Hove Albion vs Manchester United",
            "goals": [],
            "teams": [
                {
                    "id": "331",
                    "team": "Brighton & Hove Albion",
                    "score": "0",
                    "winner": false,
                    "home_away": "home"
                },
                {
                    "id": "360",
                    "team": "Manchester United",
                    "score": "3",
                    "winner": true,
                    "home_away": "away"
                }
            ],
            "venue": "American Express Stadium",
            "status": "Full Time",
            "lineups": [
                {
                    "team": "Brighton & Hove Albion",
                    "starters": [
                        "Bart Verbruggen",
                        "Lewis Dunk",
                        "Jan Paul van Hecke",
                        "Ferdi Kadioglu",
                        "Mats Wieffer",
                        "Jack Hinshelwood",
                        "James Milner",
                        "Pascal Gross",
                        "Danny Welbeck",
                        "Maxim De Cuyper",
                        "Diego Gómez"
                    ],
                    "formation": "4-2-3-1"
                },
                {
                    "team": "Manchester United",
                    "
…(truncated, see openapi.json for full schema)
```

#### `GET /v1/matches` — Matches & results

**Parameters:**
- `league` (query, optional, string) — League id (e.g. eng.1, esp.1, ita.1, ger.1) — see /v1/leagues Example: `eng.1`
- `dates` (query, optional, string) — Date range YYYYMMDD-YYYYMMDD

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/soccer-api/v1/matches?league=eng.1"
```

**Response:**
```json
{
    "data": {
        "count": 10,
        "league": "eng.1",
        "matches": [
            {
                "id": "740966",
                "away": {
                    "id": "360",
                    "form": "WWDWW",
                    "logo": "https://a.espncdn.com/i/teamlogos/soccer/500/360.png",
                    "team": "Manchester United",
                    "score": "3",
                    "winner": true,
                    "home_away": "away",
                    "abbreviation": "MAN"
                },
                "date": "2026-05-24T15:00Z",
                "home": {
                    "id": "331",
                    "form": "LLWLW",
                    "logo": "https://a.espncdn.com/i/teamlogos/soccer/500/331.png",
                    "team": "Brighton & Hove Albion",
                    "score": "0",
                    "winner": false,
                    "home_away": "home",
                    "abbreviation": "BHA"
                },
                "name": "Manchester United at Brighton & Hove Albion",
                "clock": "90'+6'",
                "venue": "American Express Stadium",
                "status": "Full Time",
                "completed": true
            },
            {
                "id": "740967",
                "away": {
                    "id": "380",
                    "form": "DDLDL",
                    "logo": "https://a.espncdn.com/i/teamlogos/soccer/500/380.png",
                    "team": "Wolverhampton 
…(truncated, see openapi.json for full schema)
```

### Teams

#### `GET /v1/team` — Team detail

**Parameters:**
- `league` (query, optional, string) — League id (e.g. eng.1, esp.1, ita.1, ger.1) — see /v1/leagues Example: `eng.1`
- `id` (query, required, string) — Team id Example: `359`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/soccer-api/v1/team?league=eng.1&id=359"
```

**Response:**
```json
{
    "data": {
        "team": {
            "id": "359",
            "logo": "https://a.espncdn.com/i/teamlogos/soccer/500/359.png",
            "name": "Arsenal",
            "color": "e20520",
            "record": "26-7-5",
            "location": "Arsenal",
            "nickname": "Arsenal",
            "standing": "1st in English Premier League",
            "abbreviation": "ARS",
            "alternate_color": "003399"
        },
        "league": "eng.1"
    },
    "meta": {
        "timestamp": "2026-06-07T16:46:32.876Z",
        "request_id": "cc410124-8598-4ca9-830a-759304b0e5c4"
    },
    "status": "ok",
    "message": "Team retrieved successfully",
    "success": true
}
```

#### `GET /v1/teams` — Teams in a league

**Parameters:**
- `league` (query, optional, string) — League id (e.g. eng.1, esp.1, ita.1, ger.1) — see /v1/leagues Example: `eng.1`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/soccer-api/v1/teams?league=eng.1"
```

**Response:**
```json
{
    "data": {
        "count": 20,
        "teams": [
            {
                "id": "349",
                "logo": "https://a.espncdn.com/i/teamlogos/soccer/500/349.png",
                "name": "AFC Bournemouth",
                "color": "f42727",
                "location": "AFC Bournemouth",
                "nickname": "AFC Bournemouth",
                "abbreviation": "BOU",
                "alternate_color": "0000CC"
            },
            {
                "id": "359",
                "logo": "https://a.espncdn.com/i/teamlogos/soccer/500/359.png",
                "name": "Arsenal",
                "color": "e20520",
                "location": "Arsenal",
                "nickname": "Arsenal",
                "abbreviation": "ARS",
                "alternate_color": "003399"
            },
            {
                "id": "362",
                "logo": "https://a.espncdn.com/i/teamlogos/soccer/500/362.png",
                "name": "Aston Villa",
                "color": "660e36",
                "location": "Aston Villa",
                "nickname": "Aston Villa",
                "abbreviation": "AVL",
                "alternate_color": "333333"
            },
            {
                "id": "337",
                "logo": "https://a.espncdn.com/i/teamlogos/soccer/500/337.png",
                "name": "Brentford",
                "color": "f42727",
                "location": "Brentford",
                "nickname": "Brentford",
                "abbrevi
…(truncated, see openapi.json for full schema)
```

### News

#### `GET /v1/news` — League news

**Parameters:**
- `league` (query, optional, string) — League id (e.g. eng.1, esp.1, ita.1, ger.1) — see /v1/leagues Example: `eng.1`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/soccer-api/v1/news?league=eng.1"
```

**Response:**
```json
{
    "data": {
        "count": 6,
        "league": "eng.1",
        "articles": [
            {
                "link": "https://www.espn.com/soccer/story/_/id/48990165/transfer-rumors-news-arsenal-psg-fight-nottingham-forest-morgan-gibbs-white",
                "image": "https://a.espncdn.com/photo/2026/0419/r1645969_1296x729_16-9.jpg",
                "headline": "Transfer rumors, news: Arsenal, PSG to fight for Gibbs-White",
                "published": "2026-06-07T14:05:25Z",
                "description": "Arsenal could face strong competition from Paris Saint-Germain for the signature of Nottingham Forest midfielder Morgan Gibbs-White. Transfer Talk has the latest."
            },
            {
                "link": "https://www.espn.com/soccer/story/_/id/48944912/premier-league-efl-summer-transfer-window-2026-dates-does-open-deadline-day",
                "image": "https://a.espncdn.com/photo/2024/0913/r1385766_1296x729_16-9.jpg",
                "headline": "Premier League, EFL summer transfer window 2026 dates: When does it open, when is Deadline Day?",
                "published": "2026-06-07T12:00:31Z",
                "description": "Everything that Premier League and EFL supporters need to know about the 2026 summer transfer window, and key dates around it."
            },
            {
                "link": "https://www.espn.com/soccer/story/_/id/48709856/world-cup-2026-which-players-your-premier-league-team-going",
                "image": "https://a.esp
…(truncated, see openapi.json for full schema)
```

### Meta

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

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

**Response:**
```json
{
    "data": {
        "service": "soccer-api",
        "endpoints": {
            "GET /v1/meta": "This document.",
            "GET /v1/news": "League news (league=).",
            "GET /v1/team": "Team detail (league=, id=).",
            "GET /v1/match": "Full match detail by id (league=, id=).",
            "GET /v1/teams": "Teams in a league (league=).",
            "GET /v1/leagues": "Supported leagues and their ids.",
            "GET /v1/matches": "Matches & results (league=, dates=YYYYMMDD-YYYYMMDD).",
            "GET /v1/standings": "League table (league=)."
        },
        "description": "Soccer (football) data for the world's top leagues: league tables/standings, teams, team detail (record, form), matches & results by date, full match detail (lineups, scorers) and news — Premier League, La Liga, Serie A, Bundesliga, Ligue 1, Champions League and more. Real live data, no key."
    },
    "meta": {
        "timestamp": "2026-06-07T16:46:33.176Z",
        "request_id": "85d030a3-23b3-400d-8adb-901fdd37c6ee"
    },
    "status": "ok",
    "message": "Meta",
    "success": true
}
```


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