API

The site's world title data can be accessed as JSON.

What it covers

The API covers the core data: every world title bout and reign. It doesn't include what only the site uses, such as the references behind the data, the rankings or the articles.

The same data is also on the data page as CSV files. Open Boxing is in early development, so expect some mistakes and missing data; found one? Please raise an issue on GitHub.

Endpoints

Every address starts https://openboxing.org/api.

/bouts/all/index.jsonEvery world title bout
/bouts/scheduled/index.jsonScheduled world title bouts
/{WEIGHT}/bouts/index.jsonA weight class's world title bouts
/{WEIGHT}/{ORG}/bouts/index.jsonWorld title bouts for one weight class and organisation
/reigns/all/index.jsonEvery world title reign
/{WEIGHT}/reigns/index.jsonA weight class's world title reigns
/{WEIGHT}/{ORG}/reigns/index.jsonWorld title reigns for one weight class and organisation
/champions/all/index.jsonEvery world champion
/champions/{ID}/index.jsonA champion's world title reigns and bouts

Parameters

{WEIGHT}

heavyweightbridgerweightcruiserweightlight-heavyweightsuper-middleweightmiddleweightsuper-welterweightwelterweightsuper-lightweightlightweightsuper-featherweightfeatherweightsuper-bantamweightbantamweightsuper-flyweightflyweightlight-flyweightminimumweight

{ORG}

ibu International Boxing Union
nysac New York State Athletic Commission
wba World Boxing Association
wbar World Boxing Association Regular
wbas World Boxing Association Super
wbc World Boxing Council
ibf International Boxing Federation
wbo World Boxing Organization
ring The Ring

{ID}

A champion's ID, as in championId. It is also the number in a champion's page address, e.g. /champions/232/.

Bouts

Each bout endpoint returns an array of bouts, oldest first.

boutId: The bout's ID
date: The date, as YYYY-MM-DD
boxers: boxerA and boxerB: a champion (with championId, name and born) or, for a boxer who never won a world title, just a name
status: FINISHED or SCHEDULED
result: winner (BOXER A, BOXER B, DRAW, NO CONTEST, or null if scheduled), methodOfVictory (e.g. KO, UD) and totalRounds
scheduledRounds: The total rounds the bout was scheduled for
weight: The weight class the bout was fought at, and its limit in pounds
titles: The world titles at stake, each at its weight at the time. A title's weight class can differ from the bout's
location: Where it was held, where known: the venue, locality, country and coordinates

A bout

{
  "boutId": 1247,
  "date": "1974-10-30",
  "boxers": {
    "boxerA": {
      "championId": 298,
      "name": {
        "first": "George",
        "last": "Foreman",
        "short": "Foreman"
      },
      "born": "1949-01-10"
    },
    "boxerB": {
      "championId": 232,
      "name": {
        "first": "Muhammad",
        "last": "Ali",
        "short": "Ali"
      },
      "born": "1942-01-17"
    }
  },
  "status": "FINISHED",
  "result": {
    "winner": "BOXER B",
    "methodOfVictory": "KO",
    "totalRounds": 8
  },
  "scheduledRounds": 15,
  "weight": {
    "class": "Heavyweight",
    "lb": "175+"
  },
  "titles": [
    {
      "weight": {
        "class": "Heavyweight",
        "lb": "175+"
      },
      "org": {
        "name": {
          "full": "World Boxing Association",
          "short": "WBA",
          "abbreviation": "WBA"
        }
      },
      "active": false
    },
    {
      "weight": {
        "class": "Heavyweight",
        "lb": "175+"
      },
      "org": {
        "name": {
          "full": "World Boxing Council",
          "short": "WBC",
          "abbreviation": "WBC"
        }
      },
      "active": true
    },
    {
      "weight": {
        "class": "Heavyweight",
        "lb": "175+"
      },
      "org": {
        "name": {
          "full": "The Ring",
          "short": "The Ring",
          "abbreviation": "RING"
        }
      },
      "active": true
    }
  ],
  "location": {
    "locationId": null,
    "venue": null,
    "locality": null,
    "country": null,
    "latitude": null,
    "longitude": null
  }
}

Reigns

Each reign endpoint returns an array of reigns, ordered by when they began.

reign_id: The reign's ID
period: begins and ends, as YYYY-MM-DD (ends is null if the reign is still going); endReason, why it ended away from the ring (vacated, stripped, retired, died, recess, elevated or discontinued; null where it ended in a bout or the reason isn't known); and current (true if it is still going)
champion: The champion: championId, name and born
title: The world title: its weight class (with the limit during the reign), its organisation and whether it is still contested

A reign

{
  "reign_id": 1670,
  "period": {
    "begins": "1995-04-29",
    "ends": "2005-07-16",
    "endReason": null,
    "current": false
  },
  "champion": {
    "championId": 776,
    "name": {
      "first": "Bernard",
      "last": "Hopkins",
      "short": "Hopkins"
    },
    "born": "1965-01-15"
  },
  "title": {
    "weight": {
      "class": "Middleweight",
      "lb": "160"
    },
    "org": {
      "name": {
        "full": "International Boxing Federation",
        "short": "IBF",
        "abbreviation": "IBF"
      }
    },
    "active": true
  }
}

Champions

/champions/all/index.json returns an array of champions. /champions/{ID}/index.json returns one champion, with arrays of their reigns and world title bouts, shaped as above.

A champion

{
  "champion": {
    "championId": 232,
    "name": {
      "first": "Muhammad",
      "last": "Ali",
      "short": "Ali"
    },
    "born": "1942-01-17"
  },
  "reigns": [
    "…"
  ],
  "bouts": [
    "…"
  ]
}

Examples

In JavaScript, with the comments saying what each returns.

const api = "https://openboxing.org/api";
const get = (path) => fetch(api + path).then((response) => response.json());

// every heavyweight world title reign, oldest first
const reigns = await get("/heavyweight/reigns/index.json");

// the reigns still going: today's heavyweight world champions
const current = reigns.filter((reign) => reign.period.current);

// the WBC heavyweight world title's bouts, oldest first
const wbcBouts = await get("/heavyweight/wbc/bouts/index.json");

// world title bouts that haven't happened yet, soonest first
const scheduled = await get("/bouts/scheduled/index.json");

// one champion: { champion, reigns, bouts }, here Jack Dempsey
const { champion, reigns: dempseyReigns, bouts } = await get("/champions/24/index.json");

// the bouts Dempsey won
const won = bouts.filter((bout) => {
	const side = bout.boxers.boxerA.championId === champion.championId ? "BOXER A" : "BOXER B";
	return bout.result.winner === side;
});