# College Football API
> Live college football (NCAA) data as an API — clean JSON, no key. Get the game scoreboard with live scores, clock and status (filter by week or conference); open any game for its leaders and result; browse the AP Top 25, Coaches Poll and College Football Playoff rankings with each team's record and rank movement; list every team and open a team for its record, conference standing and colours; pull a player's profile (position, class, height, weight, hometown); search players by name; and read the latest news. Live data sourced continuously from ESPN. A massive US betting and fantasy market, especially around bowl season and the Playoff — ideal for score apps, rankings widgets, betting tools, dashboards and Discord bots. 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/cfb-api/..."
```

## Pricing
- **Free** (Free) — 3,000 calls/Mo, 5 req/s
- **Starter** ($8/Mo) — 52,000 calls/Mo, 15 req/s
- **Pro** ($33/Mo) — 290,000 calls/Mo, 30 req/s
- **Mega** ($115/Mo) — 1,350,000 calls/Mo, 80 req/s

## Endpoints

### Games

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

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

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

**Response:**
```json
{
    "data": {
        "game": {
            "id": "401628455",
            "name": "Akron Zips at Ohio State Buckeyes",
            "teams": [
                {
                    "id": "194",
                    "team": "Ohio State Buckeyes",
                    "score": "52",
                    "record": "1-0",
                    "winner": true,
                    "home_away": "home",
                    "linescores": [
                        "7",
                        "10",
                        "21",
                        "14"
                    ],
                    "abbreviation": "OSU"
                },
                {
                    "id": "2006",
                    "team": "Akron Zips",
                    "score": "6",
                    "record": "0-1",
                    "winner": false,
                    "home_away": "away",
                    "linescores": [
                        "3",
                        "0",
                        "3",
                        "0"
                    ],
                    "abbreviation": "AKR"
                }
            ],
            "venue": "Ohio Stadium",
            "status": "Final",
            "leaders": [
                {
                    "value": "17/28, 228 YDS, 3 TD",
                    "athlete": "Will Howard"
                },
                {
                    "value": "9/13, 68 YDS",
                    "athlete": "Tahj Bullock"
                }
            ],
    
…(truncated, see openapi.json for full schema)
```

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

**Parameters:**
- `week` (query, optional, string) — Week number
- `groups` (query, optional, string) — Conference group id
- `dates` (query, optional, string) — Date range YYYYMMDD-YYYYMMDD

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

**Response:**
```json
{
    "data": {
        "week": 1,
        "count": 99,
        "games": [
            {
                "id": "401856766",
                "away": {
                    "id": "153",
                    "logo": "https://a.espncdn.com/i/teamlogos/ncaa/500/153.png",
                    "team": "North Carolina Tar Heels",
                    "score": "0",
                    "winner": false,
                    "home_away": "away",
                    "abbreviation": "UNC"
                },
                "date": "2026-08-29T16:00Z",
                "home": {
                    "id": "2628",
                    "logo": "https://a.espncdn.com/i/teamlogos/ncaa/500/2628.png",
                    "team": "TCU Horned Frogs",
                    "score": "0",
                    "winner": false,
                    "home_away": "home",
                    "abbreviation": "TCU"
                },
                "name": "North Carolina Tar Heels at TCU Horned Frogs",
                "week": 1,
                "clock": "0:00",
                "venue": "Aviva Stadium",
                "period": 0,
                "status": "Scheduled",
                "broadcast": "ESPN",
                "completed": false,
                "short_name": "UNC VS TCU",
                "season_type": 2
            },
            {
                "id": "401864494",
                "away": {
                    "id": "23",
                    "logo": "https://a.espncdn.com/i/teamlogos/ncaa/500/23.png",
  
…(truncated, see openapi.json for full schema)
```

### Rankings

#### `GET /v1/rankings` — AP, Coaches & CFP rankings

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

**Response:**
```json
{
    "data": {
        "count": 5,
        "polls": [
            {
                "poll": "AP Top 25",
                "type": "ap",
                "ranks": [
                    {
                        "id": "84",
                        "rank": 1,
                        "team": "Indiana",
                        "trend": "-",
                        "points": 1650,
                        "record": "16-0",
                        "previous": 1,
                        "first_place_votes": 66
                    },
                    {
                        "id": "2390",
                        "rank": 2,
                        "team": "Miami",
                        "trend": "+8",
                        "points": 1584,
                        "record": "13-3",
                        "previous": 10,
                        "first_place_votes": 0
                    },
                    {
                        "id": "145",
                        "rank": 3,
                        "team": "Ole Miss",
                        "trend": "+3",
                        "points": 1492,
                        "record": "13-2",
                        "previous": 6,
                        "first_place_votes": 0
                    },
                    {
                        "id": "2483",
                        "rank": 4,
                        "team": "Oregon",
                        "trend": "+1",
                        "points": 1429,
                    
…(truncated, see openapi.json for full schema)
```

### Teams

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

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

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

**Response:**
```json
{
    "data": {
        "team": {
            "id": "333",
            "logo": "https://a.espncdn.com/i/teamlogos/ncaa/500/333.png",
            "name": "Alabama Crimson Tide",
            "color": "9e1b32",
            "location": "Alabama",
            "nickname": "Crimson Tide",
            "standing": "1st in SEC",
            "abbreviation": "ALA",
            "alternate_color": "ffffff"
        }
    },
    "meta": {
        "timestamp": "2026-06-07T16:46:21.066Z",
        "request_id": "fad5e09b-7ce7-492a-832b-e8288b2d787b"
    },
    "status": "ok",
    "message": "Team retrieved successfully",
    "success": true
}
```

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

**Parameters:**
- `limit` (query, optional, string) — Max teams (default 400) Example: `400`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/cfb-api/v1/teams?limit=400"
```

**Response:**
```json
{
    "data": {
        "count": 400,
        "teams": [
            {
                "id": "2000",
                "logo": "https://a.espncdn.com/i/teamlogos/ncaa/500/2000.png",
                "name": "Abilene Christian Wildcats",
                "color": "592d82",
                "location": "Abilene Christian",
                "nickname": "Wildcats",
                "abbreviation": "ACU",
                "alternate_color": "b1b3b3"
            },
            {
                "id": "2001",
                "logo": "https://a.espncdn.com/i/teamlogos/ncaa/500/2001.png",
                "name": "Adams State Grizzlies",
                "color": "000000",
                "location": "Adams State",
                "nickname": "Grizzlies",
                "abbreviation": "ADSU"
            },
            {
                "id": "2003",
                "logo": "https://a.espncdn.com/i/teamlogos/ncaa/500/2003.png",
                "name": "Adrian Bulldogs",
                "color": "000000",
                "location": "Adrian",
                "nickname": "Bulldogs",
                "abbreviation": "ADR"
            },
            {
                "id": "2005",
                "logo": "https://a.espncdn.com/i/teamlogos/ncaa/500/2005.png",
                "name": "Air Force Falcons",
                "color": "003594",
                "location": "Air Force",
                "nickname": "Falcons",
                "abbreviation": "AF",
                "alternate_color": "ffffff"
  
…(truncated, see openapi.json for full schema)
```

### Players

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

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

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

**Response:**
```json
{
    "data": {
        "player": {
            "id": "4918121",
            "name": "Cole Adams",
            "team": "Alabama Crimson Tide",
            "active": true,
            "height": "5' 10\"",
            "jersey": "7",
            "status": "active",
            "weight": "183 lbs",
            "headshot": "https://a.espncdn.com/i/headshots/college-football/players/full/4918121.png",
            "position": "WR",
            "last_name": "Adams",
            "first_name": "Cole",
            "position_name": "Wide Receiver"
        }
    },
    "meta": {
        "timestamp": "2026-06-07T16:46:21.883Z",
        "request_id": "000b1984-876d-44e3-aebe-518969acafd4"
    },
    "status": "ok",
    "message": "Player retrieved successfully",
    "success": true
}
```

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

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

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

**Response:**
```json
{
    "data": {
        "count": 3,
        "query": "alabama",
        "players": [
            {
                "id": "4da0e853-7aa1-3f47-9032-5b9ebfc267f0",
                "name": "Charles B. Foster "
            },
            {
                "id": "60f897eb-7d35-3495-8900-e8aff3fae771",
                "name": "Mark Kolker"
            },
            {
                "id": "9f19453a-bc97-3838-86f9-619b12a0dbb3",
                "name": "Matt George"
            }
        ]
    },
    "meta": {
        "timestamp": "2026-06-07T16:46:22.075Z",
        "request_id": "94a07118-49f6-4422-8cef-c5269855a199"
    },
    "status": "ok",
    "message": "Players retrieved successfully",
    "success": true
}
```

### News

#### `GET /v1/news` — College football news

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

**Response:**
```json
{
    "data": {
        "count": 6,
        "articles": [
            {
                "link": "https://www.espn.com/video/clip/_/id/48983491/appropriate-try-work-issues",
                "type": "Media",
                "image": "https://a.espncdn.com/media/motion/2026/0606/ss_20260606_101734867_3555506/ss_20260606_101734867_3555506.jpg",
                "headline": "SEC's Sankey on college sports bill: 'It's appropriate to try to work through these issues'",
                "published": "2026-06-06T14:38:35Z",
                "description": "SEC's Sankey on college sports bill: 'It's appropriate to try to work through these issues'"
            },
            {
                "link": "https://www.espn.com/college-football/story/_/id/48980735/reports-ncaa-rejects-texas-tech-appeal-reinstate-sorsby",
                "type": "HeadlineNews",
                "image": "https://a.espncdn.com/photo/2026/0604/r1668188_600x400_3-2.jpg",
                "headline": "Reports: NCAA rejects Texas Tech's appeal to reinstate Sorsby",
                "published": "2026-06-06T13:07:49Z",
                "description": "The NCAA has denied Texas Tech's appeal to reinstate quarterback Brendan Sorsby's eligibility, according to multiple reports."
            },
            {
                "link": "https://www.espn.com/college-football/story/_/id/48978537/four-star-qb-colton-nussmeier-commits-georgia-bulldogs-football-2027-class",
                "type": "HeadlineNews",
                "imag
…(truncated, see openapi.json for full schema)
```

### Meta

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

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

**Response:**
```json
{
    "data": {
        "service": "cfb-api",
        "endpoints": {
            "GET /v1/game": "A single game's detail by id.",
            "GET /v1/meta": "This document.",
            "GET /v1/news": "College football news.",
            "GET /v1/team": "Team detail by id.",
            "GET /v1/teams": "All teams (limit=).",
            "GET /v1/player": "Player profile by id.",
            "GET /v1/search": "Search players by name.",
            "GET /v1/rankings": "AP, Coaches & CFP rankings.",
            "GET /v1/scoreboard": "Games & scores (week=, groups=, dates=)."
        },
        "description": "College Football (NCAA) data: game scoreboard and results, single-game detail with leaders, the AP / Coaches / CFP rankings, all teams, team detail, player profiles, player search and news. Real live data, no key."
    },
    "meta": {
        "timestamp": "2026-06-07T16:46:22.346Z",
        "request_id": "71a21474-c980-44e3-a1b6-63eae9906c92"
    },
    "status": "ok",
    "message": "Meta",
    "success": true
}
```


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