/boxrec

retrieve information from BoxRec and return it in JSON format

Primary LanguageTypeScriptMIT LicenseMIT

BoxRec

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.

⚠️ Notice before using this package ⚠️

BoxRec has put in some work that will throw captchas if making too many quick requests and IP block you if you trip their firewall. For the sole purpose of blocking packages like this, which is understandable. But at the cost of making it a worse UX for actual people. If you use this project you put yourself at risk of being IP banned by BoxRec for some time, not by user but by IP. This is automatic from their firewall and not something they do manually. There are ways to get by this but nothing to discuss about at this time. Use this package for learning purposes at this time.

Installation

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

npm install boxrec --save

or

yarn add boxrec

Quick Start

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

or

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.

example:

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)

login

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
}

getPersonById

Get profile by BoxRec ID

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

Output:

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

getPeopleByName

Search people on BoxRec by name

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

Output:

// 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

getPeopleByLocation

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

getEventsByLocation

Search events by location

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

getSchedule

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

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

getVenueById

Returns venue information and events that occurred there

await boxrec.getVenueById(cookieJar, 38555);

search

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.

Output:

    {
        "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"
        }
    }
});

getChampions

Returns a list of champions

Output:

const champions = await boxrec.getChampions(cookieJar);
champions.getByWeightClass().heavyweight.IBF;

getEventById

Returns event information

await boxrec.getEventById(cookieJar, 751017);

Output:

{"date": "2017-09-16",
 "commission": "Nevada Athletic Commission",
 "matchmaker":
   [ {"id": 422440,"name": "Alex Camponovo" },
     {"id": 500179,"name": "Roberto Diaz" },
     {"id": 495527,"name": "Tom Loeffler" } ],
 "location":
   {"location": {"town": "Las Vegas","id": 20388,"region": "Nevada","country": "USA" },
    "venue": {"id": 246559,"name": "T-Mobile Arena" } },
 "promoter":
   [ {"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" } ],
 "television":
   [ "USA HBO PPV",
     "Latin America", 
     "Canal Space",
     "Panama RPC Channel 4",
     "Australia Main Event",
     "Mexico Televisa" ],
 "bouts":
   [ {"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],
...

getDate

Returns events listed for that date

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

getBoutById

Returns detailed information on a single bout

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

getRatings

Get ratings

Following BoxRec's form format

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

Output:

    {
       "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
    };

getTitleById

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");

getTitles

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

getBoxerPDF

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"

getBoxerPrint

Return/save the print version of a BoxRec boxer profile

Follows the exact same format as getBoxerPDF method

await boxrec.getBoxerPrint(cookieJar, 555);

watch

Add the boxer to the user's watch list

await boxrec.watch(cookieJar, 555);

unwatch

Remove the boxer from the user's watch list

await boxrec.unwatch(cookieJar, 555);

getWatched

Return an array of boxers that the user is watching

await boxrec.getWatched(cookieJar);

Roadmap

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

Questions

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.

examples:

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

Note

Not affiliated with the website BoxRec