Skip to content
MMA Calendar
MMA Fight Data API · Code guide

How do I get historical UFC rankings for any date?

Add date=YYYY-MM-DD to the rankings endpoint of the MMA Fight Data API. GET /v1/rankings/ufc?date=2016-11-14 returns the official board that was in force that day, every division with its champion and ranked fighters. The history is point-in-time back to 2013, and snapshot_date tells you which published board answered.

Free plan: 1,000 requests a month, no card. Paid plans from $19/mo.

Get a free API keyRead the docs

Endpoints used

Endpoints used
Method & pathWhat it returnsPlan
GET /v1/rankings/{org}?date=YYYY-MM-DDOfficial ranking boards, point-in-time back to 2013 for the UFC. Champions across every launch org.All plans
GET /v1/rankings/{org}/{division}?date=One division's current board, or the board on any past date.All plans
GET /v1/fighters/{slug}/rankingsEvery official ranking row a fighter ever held, newest first.All plans
GET /v1/championsCurrent champions across every launch org in one call.All plans

The code

curl asks for the bantamweight board on 1 March 2019. The Python block prints it, steps to the neighbouring snapshots and finds one fighter's first ranking; the JavaScript block lists every champion on a single date.

Every block runs as shown with your API key in the UFCAL_API_KEY environment variable. Python uses pip install ufcalendar and JavaScript or TypeScript uses npm install @ufcalendar/sdk; any HTTP client works too.

curl
curl "https://api.ufcalendar.com/v1/rankings/ufc/bantamweight?date=2019-03-01" \
  -H "Authorization: Bearer $UFCAL_API_KEY"
Python
# pip install ufcalendar
from ufcalendar import FightAPI

api = FightAPI()  # reads UFCAL_API_KEY from the environment

board = api.division_rankings("ufc", "bantamweight", date="2019-03-01")
print("in force on 2019-03-01, published", board["snapshot_date"])
for e in board["entries"][:6]:
    print(" C" if e["is_champion"] else f"{e['rank']:>2}", e["name"])

# Step through history with the neighbouring snapshot dates
meta = api.last_meta
print("previous:", meta["previous_snapshot_date"], "| next:", meta["next_snapshot_date"])

# One fighter's ranking history, every snapshot and every board
rows = api.fighter_rankings("merab-dvalishvili")
official = [r for r in rows if r["board"] == "official" and r["division"] == "bantamweight"]
print("first ranked at bantamweight:", min(r["snapshot_date"] for r in official))
JavaScript
// npm install @ufcalendar/sdk
import { FightAPI } from "@ufcalendar/sdk";

const api = new FightAPI(); // reads UFCAL_API_KEY from the environment

// Every UFC champion on one date
const board = await api.rankings("ufc", { date: "2016-11-14" });
console.log("snapshot", board.snapshot_date);
for (const d of board.divisions) {
  const champ = d.entries.find((e) => e.is_champion);
  console.log(d.division.padEnd(22), champ ? champ.name : "(no champion row)");
}

Sample response

A real response from the live API, trimmed for length. … marks removed fields.

GET /v1/rankings/ufc/bantamweight?date=2019-03-01
{
  "data": {
    "org": "ufc",
    "board": "official",
    "snapshot_date": "2019-02-25",
    "division": "bantamweight",
    "entries": [
      {
        "rank": 0,
        "is_champion": true,
        "fighter_id": 1947,
        "fighter_slug": "tj-dillashaw",
        "name": "TJ Dillashaw",
        "nationality": "United States",
        "country_code": "US",
        "movement": 0,
        "is_new": false,
        "fighter": { "id": 1947, "slug": "tj-dillashaw", "name": "TJ Dillashaw" }
      },
      {
        "rank": 1,
        "is_champion": false,
        "fighter_id": 697,
        "fighter_slug": "marlon-moraes",
        "name": "Marlon Moraes",
        "nationality": "Brazil",
        "country_code": "BR",
        "movement": 0,
        "is_new": false,
        "fighter": { "id": 697, "slug": "marlon-moraes", "name": "Marlon Moraes" }
      },
      {
        "rank": 2,
        "is_champion": false,
        "fighter_id": 465,
        "fighter_slug": "cody-garbrandt",
        "name": "Cody Garbrandt",
        "nationality": "United States",
        "country_code": "US",
        "movement": 0,
        "is_new": false,
        "fighter": { "id": 465, "slug": "cody-garbrandt", "name": "Cody Garbrandt" }
      },
      …
    ]
  },
  "meta": { "previous_snapshot_date": "2019-02-19", "next_snapshot_date": "2019-03-05" }
}

Notes and pitfalls

  • A snapshot stays valid until the next one replaces it, so any calendar day works and the board in force is returned. meta.previous_snapshot_date and meta.next_snapshot_date walk the history one board at a time.
  • rank 0 is the champion, and is_champion says so. Pound-for-pound boards have no rank 0, and tied ranks are real.
  • movement is the change against the previous snapshot, positive when the fighter moved up, and is_new marks a fighter new to that board.
  • Ranking boards exist for UFC, PFL, OKTAGON and BKFC; RIZIN publishes none, and the history back to 2013 is the UFC's. A fighter's own ranking rows span more than one board, so filter board to official.

Related pages

UFC rankings historyPricing & plansRead the docs

More code guides

All code guides →

UFCalendar is an independent publication, not affiliated with UFC/Zuffa/TKO, PFL, OKTAGON MMA, BKFC, RIZIN FF or any promotion. Organization names are used to describe the data. Terms of service · Refund Policy

How do I get historical UFC rankings for any date? | UFCalendar