• Public
  • Public/Protected
  • All



CircleCI Coverage Status dependencies Status devDependencies Status CII Best Practices npm version Codacy Badge DeepScan grade Known Vulnerabilities

This project allows you to query information from BoxRec and return it in JSON format. The purpose of this project is to act as an API for BoxRec.


This project is written in Node. Currently this project supports Node 8-10.

npm install boxrec --save


yarn add boxrec

Quick Start

const boxrec = require("boxrec").Boxrec;


import {Boxrec as boxrec} from "boxrec";

Use credentials to log into BoxRec and then use any of the methods below. Pass the cookie into all methods.


const cookieJar = await boxrec.login(BOXREC_USERNAME, BOXREC_PASSWORD);
await boxrec.getPersonById(cookieJar, 352);

How to contribute

Details on how to help can be found here

Additional Documentation

Latest npm published (master)

Methods (How to use)


logs the user into BoxRec

To use this properly, it requires a login to BoxRec. BoxRec supplies additional information when logged in

try {
    const cookieJar = await boxrec.login(BOXREC_USERNAME, BOXREC_PASSWORD);
    // successfully logged in
} catch (e) {
    // error occurred logging in


Get profile by BoxRec ID

Using the BoxRec global ID, retrieve all information about a person.


const gennadyGolovkin = await boxrec.getPersonById(cookieJar, 356831);
console.log(gennadyGolovkin.name); // Gennady Golovkin
console.log(gennadyGolovkin.division); // middleweight
console.log(gennadyGolovkin.titlesHeld); // currently held titles
console.log(gennadyGolovkin.otherInfo); // other info that couldn't be categorized
console.log(gennadyGolovkin.suspended); // will tell if boxer is currently suspended
console.log(gennadyGolovkin.bouts); // list of bouts
console.log(gennadyGolovkin.bouts[37].opponent.name); // Saul Alvarez

// other profiles
// we optionally specify the `role` as some people have multiple roles
boxrec.getPersonById(cookieJar, 401615, BoxrecRole.judge); // judge CJ Ross


Search people on BoxRec by name

Returns a generator which will makes individual calls, returns differ depending on the profile type


// by default it picks active/inactive boxers
const floyds = await boxrec.getPeopleByName(cookieJar, "Floyd", "Mayweather");
let boxer = await floyds.next();
console.log(boxer.value); // is Floyd Mayweather Sr. object

boxer = await floyds.next();
console.log(boxer.value); // is Floyd Mayweather Jr. object


Search people by location

await boxrec.getPeopleByLocation(cookieJar, {
    country: Country.USA,
    role: BoxrecRole.boxer,
}, 20); // `20` is the search offset.  All endpoints that support `offset` on BoxRec should be supported in this package


Search events by location

await boxrec.getEventsByLocation(cookieJar, {
    country: Country.USA,
    year: 2017,


Returns schedule information by country code, television, and/or division

await boxrec.getSchedule(cookieJar, {
    countryCode: Country.Canada,


Returns venue information and events that occurred there

await boxrec.getVenueById(cookieJar, 38555);

Search boxers by name

Following BoxRec's form format

const searchResults = await boxrec.search(cookieJar, {
    first_name: "Floyd",
    last_name: "Mayweather",
console.log(searchResults[1]); // Floyd Mayweather Jr.


        "id": 352,
        "name": "Floyd Mayweather Jr",
        "alias": "Money / Pretty Boy",
        "record": {
            "draw": 0,
            "loss": 0,
            "win": 50
        "last6": ["win", "win", "win", "win", "win", "win"],
        "division": "welterweight",
        "career": [1996, 2017],
        "residence": {
            "id": 20388,
            "town": "Las Vegas",
            "region": "NV",
            "country": "US"


Returns a list of champions


const champions = await boxrec.getChampions(cookieJar);


Returns event information

await boxrec.getEventById(cookieJar, 751017);


{"date": "2017-09-16",
 "commission": "Nevada Athletic Commission",
   [ {"id": 422440,"name": "Alex Camponovo" },
     {"id": 500179,"name": "Roberto Diaz" },
     {"id": 495527,"name": "Tom Loeffler" } ],
   {"location": {"town": "Las Vegas","id": 20388,"region": "Nevada","country": "USA" },
    "venue": {"id": 246559,"name": "T-Mobile Arena" } },
   [ {"id": 8253,
      "company": "Golden Boy Promotions",
      "name": "Oscar De La Hoya" },
     {"id": 495527,"company": "K2 Promotions","name": "Tom Loeffler" },
     {"id": 413083,"company": "Banner Promotions","name": "Art Pelullo" } ],
   [ "USA HBO PPV",
     "Latin America", 
     "Canal Space",
     "Panama RPC Channel 4",
     "Australia Main Event",
     "Mexico Televisa" ],
   [ {"firstBoxer": [Object],
      "firstBoxerLast6": [Array],
      "firstBoxerRecord": [Object],
      "firstBoxerWeight": 160,
      "secondBoxer": [Object],
      "secondBoxerLast6": [Array],
      "secondBoxerRecord": [Object],
      "secondBoxerWeight": 160,
      "titles": [Array],
      "referee": [Object],
      "judges": [Array],
      "rating": 100,
      "result": [Array],
      "links": [Object],


Returns events listed for that date

await boxrec.getDate(cookieJar, "2018-08-21");


Returns detailed information on a single bout

await boxrec.getBoutById(cookieJar, "726555/2037455");


Get ratings

Following BoxRec's form format

await boxrec.getRatings(cookieJar, {
   "division": "Welterweight",
   "sex": "M",
   "status": "a"


       "id": 629465,
       "name": 'Errol Spence Jr',
       "points": 555,
       "rating": 100,
       "age": 28,
       "record": {
           "draw": 0,
           "loss": 0,
           "win": 23
       "last6": ['win', 'win', 'win', 'win', 'win', 'win'],
       "stance": 'southpaw',
       "residence": {
           "id": 43387,
           "town": 'Desoto',
           "region": 'TX',
           "country": 'US'
       "division": null


Get title information including all bouts that occurred for this title

// WBC Middleweight information
// to get this parameter, the link is on a boxer's profile
await boxrec.getTitleById(cookieJar, "6/Middleweight");


await boxrec.getTitles(cookieJar, {
    bout_title: 322,
    division: WeightDivisionCapitalized.welterweight,


Return/save the PDF version of a BoxRec boxer profile

await boxrec.getBoxerPDF(cookieJar, 555); // returns the PDF information
await boxrec.getBoxerPDF(cookieJar, 555, "./profile"); // saves the PDF to "./profile/555.pdf"
await boxrec.getBoxerPDF(cookieJar, 555, "./profile", "foo.pdf); // saves the PDF to "./profile/foo.pdf"


Return/save the print version of a BoxRec boxer profile

Follows the exact same format as getBoxerPDF method

await boxrec.getBoxerPrint(cookieJar, 555); 


Add the boxer to the user's watch list

await boxrec.watch(cookieJar, 555); 


Remove the boxer from the user's watch list

await boxrec.unwatch(cookieJar, 555);


Return an array of boxers that the user is watching

await boxrec.getWatched(cookieJar); 


Last updated 2019-04-30

  • Added 2019-04-13: Get E2E testing working in CI

  • Added 2019-04-13: Documentation should not be part of commits. Pull requests to only contain source changes

    Completed 2019-04-30 - Documentation pushed to S3

  • Added 2019-04-13: Prepare for Dockerization

  • Added 2019-04-13: All data accessible by Docker package

  • Added 2019-04-13: Changes to boxrec-requests should trigger builds to ensure functionality does not break

  • Added 2019-04-13: Changes to this package should trigger builds in upcoming Docker project

  • Added 2019-04-13: Get to and keep a "A" maintainability in Codacy

    Completed in 2019

  • Added 2019-04-13: Separate typings into typings registry

  • Added 2019-04-13: Reduce package size. Separate typings will greatly help

    Completed 2019-04-30 - 1.30 MB to 48 KB

  • Added 2019-04-13: Make sure all typings work with external projects that use this package

  • Added 2019-04-13: Master branch should be latest version in NPM

    Completed 2019-04-30 - Using Git Flow

Security Requirements


What and where is the BoxRec global ID?

The BoxRec global ID or ID is the unique ID of the person, event, bout, etc. It can be found in the URL bar. For people it can also be found on their page.


(Person) Vasiliy Lomachenko - http://boxrec.com/en/boxer/659771. The BoxRec global ID is 659771.

(Bout) Terence Crawford vs. Amir Khan - http://boxrec.com/en/event/778793/2299385. The BoxRec bout ID is 778793/2299385

(Event) Golden Boy May 4th 2019 Event - http://boxrec.com/en/event/781894. The BoxRec event ID is 781894

Why is there global ID and ID?

I took the safe approach and assumed that there may be some difference between the two. There doesn't seem to be but better safe than sorry.

Is using this software legal?

When this software was initially written, the Terms and Conditions on BoxRec did not include anything about web scraping.

BoxRec had updated their Terms and Conditions sometime in the middle of 2018 to include that you may not use software to extract data from BoxRec.

Web scraping on wikipedia states under legal issues "The legality of web scraping varies across the world. In general, web scraping may be against the terms of use of some websites, but the enforceability of these terms is unclear".

Conclusion: It is unclear. What you do with this package though could very well be illegal.


Not affiliated with the website BoxRec

Generated using TypeDoc