ufcalendar — Python client for the UFCalendar Fight API

The UFCalendar Fight API is a REST API for MMA data: UFC, PFL, OKTAGON, BKFC and RIZIN events, full fight cards, results within minutes, per-fight and round-by-round statistics, complete fighter careers, the only UFC rankings API with point-in-time history back to 2013, and the only one serving judges' scorecards — every official, every round: UFC back to 1995, PFL to 2018, OKTAGON to 2025 and RIZIN from March 2026. This package is a thin requests wrapper over it — one method per endpoint, cursor pagination handled for you.

pip install ufcalendar

Get a key (free 1-day trial, 100 requests, no card) at https://www.ufcalendar.com/account/api?trial=1. Paid plans from $19/month for 30,000 requests (Pro $49 for 200,000, Business $149 for 1,000,000), hard caps, no overage.

Quickstart

from ufcalendar import FightAPI

api = FightAPI("ufcalendar_...")            # or export UFCAL_API_KEY=...

# Upcoming UFC schedule, soonest first
for ev in api.events(org="ufc", limit=5):
    print(ev["starts_at"], ev["title"], "PPV" if ev["is_ppv"] else "")

# Full card + results of the newest completed UFC event
latest = next(api.events(org="ufc", status="completed", limit=1))
card = api.event(latest["slug"])
for f in card["fights"]:
    r = f.get("result")
    if r:
        print(f["fighter_a"]["name"], "vs", f["fighter_b"]["name"], "->", r["method"], f"R{r['round']} {r['time']}")

# Round-by-round statistics for one bout
rounds = api.fight_rounds(card["fights"][0]["id"])

# UFC rankings on any date since February 2013 (rank 0 = champion)
board = api.rankings("ufc", date="2016-11-14")
lw = next(d for d in board["divisions"] if d["division"] == "lightweight")
print(board["snapshot_date"], [e["name"] for e in lw["entries"][:5]])

# A fighter's complete multi-promotion career
history = api.fighter_history("islam-makhachev")

What's covered

Full reference: https://api.ufcalendar.com/docs · OpenAPI 3.1: https://api.ufcalendar.com/openapi.json · Also on npm (TypeScript client), RapidAPI Hub and Postman

Live stream (UFC fight nights, Pro plans and up)

The UFC live API: a WebSocket that pushes the fight-night document the moment it changes — card order and statuses, the bout in progress (round, running clock, unofficial in-fight stats, per-round splits, a timestamped action timeline) and the last result. It is the streaming half of event_live(), and it is the UFC live stats API you want instead of polling.

The socket ships as an optional extra so a REST-only install stays requests-thin:

pip install 'ufcalendar[live]'

from ufcalendar import FightAPI

api = FightAPI()  # UFCAL_API_KEY

for frame in api.live_stream("ufc-331", until_final=True):
    # frame["type"]: "snapshot" | "update" | "fight.final" | "event.completed"
    state = frame["data"]
    if not state:
        continue                      # nothing streaming yet
    cur = state["current"] or {}
    print(frame["type"], "R", cur.get("round"), cur.get("clock_sec"))

until_final=True stops after the first fight.final frame; the default runs until the socket ends. A dropped connection is re-subscribed once automatically.

Runnable ticker: examples/live_ticker.py — ~40 lines that print R2 3:41 · Oliveira 41 vs Makhachev 37 sig. strikes as the round unfolds.

Webhooks instead of polling (Pro and up)

ep = api.create_webhook_endpoint("https://example.com/hooks/ufcal", ["fight.result", "card.changed"])
print(ep["secret"])   # shown once; verify X-UFCalendar-Signature with it

Errors and rate limits

Every error raises FightAPIError with .status, .code, .message, .request_id. After each call api.last_rate_limit holds the X-RateLimit-* headers.

Notes

• No betting odds are served, by design.
• Fighter images are Wikimedia Commons / Creative Commons files: display the license and artist fields as a credit.
• Not affiliated with UFC, Zuffa, TKO or any promotion. Terms: https://www.ufcalendar.com/developers/terms

MIT licensed.