ESPN API endpoint
Returns poll rankings (e.g. AP Top 25) for a college league. Rankings are only published for college leagues: the `sport` enum accepts `football` and `basketball`, and the `league` enum accepts `college-football`, `mens-college-basketball`, and `womens-college-basketball`.
/espn/rankingsQuery parameters:
sport: required enum. Allowed values: football, basketball.league: required enum. Allowed values: college-football, mens-college-basketball, womens-college-basketball.Notable response behavior:
nfl, nba) return an invalid-parameter error — rankings are not published for them.sport/league values return an invalid-parameter error before upstream IO.| Field | Filled in, of 5 checked | Values in the sample |
|---|---|---|
| name | 5 | “AP Top 25” and 4 other values |
| short_name | 5 | “AP Poll” and 4 other values |
| ranks | 5 | median 25 entries |
| Parameter | Type | Required | Default | Description | Example |
|---|---|---|---|---|---|
| sport | string | Yes | Sport key Allowed values: football, basketball. | football | |
| league | string | Yes | College league key Allowed values: college-football, mens-college-basketball, womens-college-basketball. | college-football | |
| x-api-key (header) | string | Yes | API key required |
curl -X GET "https://api.crawlora.net/api/v1/espn/rankings?sport=football&league=college-football" \ -H "x-api-key: $CRAWLORA_API_KEY"
{
"code": 200,
"msg": "OK",
"data": {
"sport": "football",
"league": "college-football",
"season": {
"year": 2024
},
"source_url": "https://site.api.espn.com/apis/site/v2/sports/football/college-football/rankings",
"fetched_at": "2026-07-06T00:00:00Z",
"polls": [
{
"name": "AP Top 25",
"short_name": "AP Poll",
"ranks": [
{
"current": 1,
"previous": 1,
"points": 1650,
"trend": "-",
"record": "16-0",
"team": {
"id": "194",
"abbreviation": "OSU",
"name": "Buckeyes"
}
}
]
}
]
}
}Request schema
No body schema
Response schema
#/definitions/espn.rankingsResponseDoc
| Field | Type | Required | Enum | Bounds | Example | Description |
|---|---|---|---|---|---|---|
| code | integer | No | 200 | |||
| data | espn.RankingsResponse | No | ||||
| data.fetched_at | string | No | Time the data was fetched, in UTC (RFC 3339). | |||
| data.league | string | No | League key that was requested, for example `college-football`. | |||
| data.polls | array | No | Ranking polls published for the league, one entry per poll. | |||
| data.polls[].name | string | No | Full poll name, for example `AP Top 25`. | |||
| data.polls[].ranks | array | No | Ranked teams in the poll, one entry per rank. | |||
| data.polls[].ranks[].current | integer | No | Team's rank in this poll. | |||
| data.polls[].ranks[].points | number | No | Total poll points the team received. Omitted when ESPN gives none. | |||
| data.polls[].ranks[].previous | integer | No | Team's rank in the previous poll. Omitted when ESPN gives none. | |||
| data.polls[].ranks[].record | string | No | Team's win-loss record, for example `16-0`. | |||
| data.polls[].ranks[].team | object | No | Team holding this rank. | |||
| data.polls[].ranks[].team.abbreviation | string | No | KC | Short team code, for example `KC`. | ||
| data.polls[].ranks[].team.alternate_color | string | No | Team's secondary colour code, as ESPN gives it. | |||
| data.polls[].ranks[].team.color | string | No | Team's primary colour code, as ESPN gives it. | |||
| data.polls[].ranks[].team.display_name | string | No | Kansas City Chiefs | Full team name, for example `Kansas City Chiefs`. | ||
| data.polls[].ranks[].team.id | string | No | 12 | ESPN team id, for example `12`. Use it as the `team` parameter of the team and roster endpoints. | ||
| data.polls[].ranks[].team.location | string | No | Kansas City | Team's city or region, for example `Kansas City`. | ||
| data.polls[].ranks[].team.logo | string | No | URL of the team logo image. | |||
| data.polls[].ranks[].team.name | string | No | Chiefs | Team nickname without the location, for example `Chiefs`. | ||
| data.polls[].ranks[].team.short_display_name | string | No | Chiefs | Shortened team name, for example `Chiefs`. | ||
| data.polls[].ranks[].team.uid | string | No | ESPN's unique identifier string for the team. | |||
| data.polls[].ranks[].trend | string | No | Change in rank since the previous poll, as ESPN shows it. | |||
| data.polls[].short_name | string | No | Short poll name as ESPN shows it. | |||
| data.season | object | No | Season the rankings belong to. | |||
| data.season.name | string | No | Season type name as ESPN shows it. | |||
| data.season.type | integer | No | 2 | Season type code: 1 preseason, 2 regular season, 3 postseason, 4 offseason. | ||
| data.season.year | integer | No | 2024 | Season year, for example `2024`. | ||
| data.source_url | string | No | URL the data was read from. | |||
| data.sport | string | No | Sport key that was requested, for example `football`. | |||
| msg | string | No | OK |
| Status | Description | Schema |
|---|---|---|
| 400 | Bad Request | #/definitions/app.Response |
| 404 | Not Found | #/definitions/app.Response |
| 429 | Too Many Requests | #/definitions/app.Response |
| 503 | Service Unavailable | #/definitions/app.Response |
Use environment variables for secrets and keep Crawlora API keys server-side.
curl -X GET "https://api.crawlora.net/api/v1/espn/rankings?sport=football&league=college-football" \
-H "x-api-key: $CRAWLORA_API_KEY"