# NFL API
> Live NFL (American football) data as an API — clean JSON, no key. Get the game scoreboard with live scores, clock and status; open any game for its box-score leaders, line scores and result; browse the full conference and division standings (wins, losses, ties, win percentage, streak); list all 32 teams and open a team for its record, standing, venue and colours; pull a player's profile (position, jersey, height, weight, college, team); search players by name; and read the latest NFL news. Live data sourced continuously from ESPN. The most-watched US sport, with a huge fantasy and betting market — ideal for fantasy-football tools, score apps, dashboards, Discord bots and media sites. 8 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/nfl-api/..."
```

## Pricing
- **Free** (Free) — 3,000 calls/Mo, 5 req/s
- **Starter** ($9/Mo) — 55,000 calls/Mo, 15 req/s
- **Pro** ($39/Mo) — 300,000 calls/Mo, 30 req/s
- **Mega** ($129/Mo) — 1,500,000 calls/Mo, 80 req/s

## Endpoints

### Games

#### `GET /v1/game` — A single game's detail

**Parameters:**
- `id` (query, required, string) — Game id Example: `401872656`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/nfl-api/v1/game?id=401872656"
```

**Response:**
```json
{
    "data": {
        "game": {
            "id": "401872656",
            "name": "New England Patriots at Seattle Seahawks",
            "teams": [
                {
                    "id": "26",
                    "team": "Seattle Seahawks",
                    "winner": false,
                    "home_away": "home",
                    "linescores": [],
                    "abbreviation": "SEA"
                },
                {
                    "id": "17",
                    "team": "New England Patriots",
                    "winner": false,
                    "home_away": "away",
                    "linescores": [],
                    "abbreviation": "NE"
                }
            ],
            "venue": "Lumen Field",
            "status": "Scheduled",
            "leaders": [
                [],
                []
            ],
            "completed": false
        }
    },
    "meta": {
        "timestamp": "2026-06-07T16:46:36.008Z",
        "request_id": "e9477365-f46d-4c35-80c3-254da857470e"
    },
    "status": "ok",
    "message": "Game retrieved successfully",
    "success": true
}
```

#### `GET /v1/scoreboard` — Games & scores

**Parameters:**
- `dates` (query, optional, string) — Date range YYYYMMDD-YYYYMMDD
- `week` (query, optional, string) — Week number
- `seasontype` (query, optional, string) — 1=pre, 2=regular, 3=post

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

**Response:**
```json
{
    "data": {
        "week": 1,
        "count": 16,
        "games": [
            {
                "id": "401872656",
                "away": {
                    "id": "17",
                    "logo": "https://a.espncdn.com/i/teamlogos/nfl/500/scoreboard/ne.png",
                    "team": "New England Patriots",
                    "score": "0",
                    "winner": false,
                    "home_away": "away",
                    "abbreviation": "NE"
                },
                "date": "2026-09-10T00:20Z",
                "home": {
                    "id": "26",
                    "logo": "https://a.espncdn.com/i/teamlogos/nfl/500/scoreboard/sea.png",
                    "team": "Seattle Seahawks",
                    "score": "0",
                    "winner": false,
                    "home_away": "home",
                    "abbreviation": "SEA"
                },
                "name": "New England Patriots at Seattle Seahawks",
                "week": 1,
                "clock": "0:00",
                "venue": "Lumen Field",
                "period": 0,
                "status": "Scheduled",
                "broadcast": "NBC",
                "completed": false,
                "short_name": "NE @ SEA",
                "season_type": 2
            },
            {
                "id": "401872657",
                "away": {
                    "id": "25",
                    "logo": "https://a.espncdn.com/i/teamlogos/nfl/500/scoreboard/
…(truncated, see openapi.json for full schema)
```

### Standings

#### `GET /v1/standings` — Conference & division standings

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

**Response:**
```json
{
    "data": {
        "count": 2,
        "conferences": [
            {
                "divisions": [
                    {
                        "teams": [
                            {
                                "id": "17",
                                "team": "New England Patriots",
                                "ties": "0.0",
                                "wins": "14.0",
                                "losses": "3.0",
                                "streak": "W3",
                                "win_percent": ".824",
                                "abbreviation": "NE"
                            },
                            {
                                "id": "2",
                                "team": "Buffalo Bills",
                                "ties": "0.0",
                                "wins": "12.0",
                                "losses": "5.0",
                                "streak": "W1",
                                "win_percent": ".706",
                                "abbreviation": "BUF"
                            },
                            {
                                "id": "15",
                                "team": "Miami Dolphins",
                                "ties": "0.0",
                                "wins": "7.0",
                                "losses": "10.0",
                                "streak": "L1",
                                "win_percent": ".412",
                           
…(truncated, see openapi.json for full schema)
```

### Teams

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

**Parameters:**
- `id` (query, required, string) — Team id Example: `12`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/nfl-api/v1/team?id=12"
```

**Response:**
```json
{
    "data": {
        "team": {
            "id": "12",
            "logo": "https://a.espncdn.com/i/teamlogos/nfl/500/kc.png",
            "name": "Kansas City Chiefs",
            "color": "e31837",
            "location": "Kansas City",
            "nickname": "Chiefs",
            "standing": "3rd in AFC West",
            "abbreviation": "KC",
            "alternate_color": "ffb612"
        }
    },
    "meta": {
        "timestamp": "2026-06-07T16:46:37.109Z",
        "request_id": "f718eb91-af15-46a3-9998-d2f64e7e184a"
    },
    "status": "ok",
    "message": "Team retrieved successfully",
    "success": true
}
```

#### `GET /v1/teams` — All 32 NFL teams

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

**Response:**
```json
{
    "data": {
        "count": 32,
        "teams": [
            {
                "id": "22",
                "logo": "https://a.espncdn.com/i/teamlogos/nfl/500/ari.png",
                "name": "Arizona Cardinals",
                "color": "a40227",
                "location": "Arizona",
                "nickname": "Cardinals",
                "abbreviation": "ARI",
                "alternate_color": "ffffff"
            },
            {
                "id": "1",
                "logo": "https://a.espncdn.com/i/teamlogos/nfl/500/atl.png",
                "name": "Atlanta Falcons",
                "color": "a71930",
                "location": "Atlanta",
                "nickname": "Falcons",
                "abbreviation": "ATL",
                "alternate_color": "000000"
            },
            {
                "id": "33",
                "logo": "https://a.espncdn.com/i/teamlogos/nfl/500/bal.png",
                "name": "Baltimore Ravens",
                "color": "29126f",
                "location": "Baltimore",
                "nickname": "Ravens",
                "abbreviation": "BAL",
                "alternate_color": "000000"
            },
            {
                "id": "2",
                "logo": "https://a.espncdn.com/i/teamlogos/nfl/500/buf.png",
                "name": "Buffalo Bills",
                "color": "00338d",
                "location": "Buffalo",
                "nickname": "Bills",
                "abbreviation": "BUF",
           
…(truncated, see openapi.json for full schema)
```

### Players

#### `GET /v1/player` — Player profile

**Parameters:**
- `id` (query, required, string) — Player id Example: `3139477`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/nfl-api/v1/player?id=3139477"
```

**Response:**
```json
{
    "data": {
        "player": {
            "id": "3139477",
            "age": 30,
            "name": "Patrick Mahomes",
            "team": "Kansas City Chiefs",
            "active": true,
            "height": "6' 2\"",
            "jersey": "15",
            "status": "active",
            "weight": "225 lbs",
            "college": "Texas Tech",
            "headshot": "https://a.espncdn.com/i/headshots/nfl/players/full/3139477.png",
            "position": "QB",
            "last_name": "Mahomes",
            "experience": "10th Season",
            "first_name": "Patrick",
            "date_of_birth": "17/9/1995",
            "position_name": "Quarterback"
        }
    },
    "meta": {
        "timestamp": "2026-06-07T16:46:37.843Z",
        "request_id": "4309803c-a901-4b21-bf03-73963c2d0744"
    },
    "status": "ok",
    "message": "Player retrieved successfully",
    "success": true
}
```

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

**Parameters:**
- `query` (query, required, string) — Player name Example: `mahomes`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/nfl-api/v1/search?query=mahomes"
```

**Response:**
```json
{
    "data": {
        "count": 2,
        "query": "mahomes",
        "players": [
            {
                "id": "37d87523-280a-9d4a-0adb-22cfc6d3619c",
                "name": "Patrick Mahomes",
                "image": "https://a.espncdn.com/i/headshots/nfl/players/full/3139477.png",
                "subtitle": "Kansas City Chiefs"
            },
            {
                "id": "dcd39c0c-e168-eb07-4751-15e34aa259da",
                "name": "Pat Mahomes",
                "subtitle": "Pittsburgh Pirates"
            }
        ]
    },
    "meta": {
        "timestamp": "2026-06-07T16:46:38.039Z",
        "request_id": "0c604f5e-fde0-4603-8360-13f8b45e3ab8"
    },
    "status": "ok",
    "message": "Players retrieved successfully",
    "success": true
}
```

### News

#### `GET /v1/news` — NFL news

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

**Response:**
```json
{
    "data": {
        "count": 6,
        "articles": [
            {
                "link": "https://www.espn.com/video/clip/_/id/48912944/grainy-security-video-captures-last-moments-reche-caldwell-life",
                "type": "Media",
                "image": "https://a.espncdn.com/media/motion/2026/0529/dm_260529_Watchfolder_reche-caldwell_espn/dm_260529_Watchfolder_reche-caldwell_espn.jpg",
                "headline": "Grainy security video captures the last moments of Reche Caldwell's life",
                "published": "2026-06-07T10:15:52Z",
                "description": "Grainy security video captures the last moments of Reche Caldwell's life"
            },
            {
                "link": "https://www.espn.com/nfl/story/_/id/48966748/new-york-jets-change-44-years-veteran-leadership",
                "type": "Story",
                "image": "https://a.espncdn.com/photo/2026/0604/r1668154_608x342_16-9.jpg",
                "headline": "Can adding 44 years of veteran leadership help Jets turn it around?",
                "published": "2026-06-07T14:21:44Z",
                "description": "As the urgency to win increases, New York hopes its offseason moves will help alleviate growing pressures."
            },
            {
                "link": "https://www.espn.com/nfl/story/_/id/48965433/jaylen-waddle-denver-broncos-debut-otas-offseason-practices",
                "type": "Story",
                "image": "https://a.espncdn.com/photo/2026/0605/r1668565_
…(truncated, see openapi.json for full schema)
```

### Meta

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

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

**Response:**
```json
{
    "data": {
        "service": "nfl-api",
        "endpoints": {
            "GET /v1/game": "A single game's detail by id.",
            "GET /v1/meta": "This document.",
            "GET /v1/news": "NFL news.",
            "GET /v1/team": "Team detail by id.",
            "GET /v1/teams": "All 32 NFL teams.",
            "GET /v1/player": "Player profile by id.",
            "GET /v1/search": "Search players by name.",
            "GET /v1/standings": "Conference & division standings.",
            "GET /v1/scoreboard": "Games & scores (dates=, week=, seasontype=)."
        },
        "description": "NFL (American football) data: game scoreboard and results, single-game detail with box-score leaders, conference/division standings, all teams, team detail, player profiles, player search and NFL news. Real live data, no key."
    },
    "meta": {
        "timestamp": "2026-06-07T16:46:38.265Z",
        "request_id": "6343ad12-bf84-4a87-a7af-229c8fc50a4b"
    },
    "status": "ok",
    "message": "Meta",
    "success": true
}
```


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