---
title: "ESPN poll rankings"
method: GET
path: "/espn/rankings"
tags: ["ESPN"]
---

# ESPN poll rankings

`GET /espn/rankings`

## Request

- Base URL: `https://api.crawlora.net/api/v1`
- URL: `https://api.crawlora.net/api/v1/espn/rankings`
- Auth: API key in header `x-api-key`

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`.

## Query parameters

- `sport` 'football' | 'basketball', required
- `league` 'college-football' | 'mens-college-basketball' | 'womens-college-basketball', required

## Headers

- `x-api-key` string, required

## Response `200`

OK

- EspnRankingsResponseDoc
  - `code` integer
  - `data` EspnRankingsResponse
    - `fetched_at` string: Time the data was fetched, in UTC (RFC 3339).
    - `league` string: League key that was requested, for example `college-football`.
    - `polls` EspnRankingPoll[]: Ranking polls published for the league, one entry per poll.
      - `name` string: Full poll name, for example `AP Top 25`.
      - `ranks` EspnRankEntry[]: Ranked teams in the poll, one entry per rank.
        - `current` integer: Team's rank in this poll.
        - `points` number: Total poll points the team received. Omitted when ESPN gives none.
        - `previous` integer: Team's rank in the previous poll. Omitted when ESPN gives none.
        - `record` string: Team's win-loss record, for example `16-0`.
        - `team` EspnTeamRef
          - `abbreviation` string: Short team code, for example `KC`.
          - `alternate_color` string: Team's secondary colour code, as ESPN gives it.
          - `color` string: Team's primary colour code, as ESPN gives it.
          - `display_name` string: Full team name, for example `Kansas City Chiefs`.
          - `id` string: ESPN team id, for example `12`. Use it as the `team` parameter of the team and roster endpoints.
          - `location` string: Team's city or region, for example `Kansas City`.
          - `logo` string: URL of the team logo image.
          - `name` string: Team nickname without the location, for example `Chiefs`.
          - `short_display_name` string: Shortened team name, for example `Chiefs`.
          - `uid` string: ESPN's unique identifier string for the team.
        - `trend` string: Change in rank since the previous poll, as ESPN shows it.
      - `short_name` string: Short poll name as ESPN shows it.
    - `season` EspnSeason
      - `name` string: Season type name as ESPN shows it.
      - `type` integer: Season type code: 1 preseason, 2 regular season, 3 postseason, 4 offseason.
      - `year` integer: Season year, for example `2024`.
    - `source_url` string: URL the data was read from.
    - `sport` string: Sport key that was requested, for example `football`.
  - `msg` string

## Other responses

- `400`: Bad Request
- `404`: Not Found
- `429`: Too Many Requests
- `503`: Service Unavailable

---

[API](https://skmtc.dev/crawlora/apis/crawlora-api.md) · [All operations](https://skmtc.dev/crawlora/apis/crawlora-api/llms.txt) · [OpenAPI document](https://skmtc.dev/crawlora/apis/crawlora-api/revisions/afac9b012a27?raw)