bracketclub/bracket-data bracketclub/bracket-data

Get some helpful data for a tournament bracket.

Host: GitHub

License: MIT

Language: JavaScript

Keywords: bracket, ncaa, tweetyourbracket, bracketclub, sport, year, properties, scoring


Get some helpful data for a tournament bracket.


Build Status

What is a bracket?

From wikipedia:

A bracket is a tree diagram that represents the series of games played during a tournament, named as such because it appears to be a large number of interconnected (punctuational) brackets.

But if you're going to use this, you probably already know that :).

What does this module do?

Let's say you like writing code, and you like brackets, and then one day you want to write some code about brackets. Well, you'll probably need some data first. bracket-data aims to have this data for you separated by sport and year, as well as some helpers to make it easier to interact with that data.


This module can be used in Node or the browser. All of the following examples are extracting the same data.

In Node, you can require the module as normally would:

// Node usage
var ncaam2013 = require('bracket-data')({
    year: '2013',
    sport: 'ncaam'

In a browser, the files are provided prebuilt so that you don't include the whole bundle.

// For usage in a browser without bundling data for any other sport/year
var ncaam2013 = require('bracket-data/browser/ncaam-2013');

If you don't care about including all the data for every sport/year, then you can still require it normally:

// Browser usage, although this bundles data for every sport/year
var ncaam2013 = require('bracket-data')({
    year: '2013',
    sport: 'ncaam'

What data does this module give me?

Hopefully enough to display an interactive bracket. There are many other modules for doing things like explicity validating, scoring and updating a bracket.

Here are the specific properties with examples from the ncaam-2013 bracket. Keep in mind, that the data will change based on the number of teams in the bracket, the number of regions and which teams.

  • bracket: an object structured to have each region with the necessary properties. For example:
  "regions": {
    "MW": {
      "name": "Midwest",
      "fullname": "Midwest Region",
      "sameSideAs": "W",
      "teams": [
        "Michigan State",
        "Saint Louis",
        "Oklahoma State",
        "Colorado State",
        "Saint Mary's",
        "New Mexico State",
        "North Carolina A&T"
      "id": "MW"
    /* other regions... */
    "FF": {
      "id": "FF",
      "name": "Final Four"
  • regex: a regular expression that can be used to match a string representation of the bracket. These string representations of brackets make up the foundation of all the bracket modules as it is how the data is stored. Here's what the final bracket looked like as a string.
  • constants: an object with a number of constant values of the bracket. For example:
  "FINAL_ID": "FF",
  "ALL_IDS": [
  "FINAL_NAME": "Final Four",
  • order: an array with the first round team order. This is useful for display purposes as it is ordered how the teams should be paired from top-to-bottom for each region to start the bracket:
[1, 16, 8, 9, 5, 12, 4, 13, 6, 11, 3, 14, 7, 10, 2, 15]
  • scoring: any data from the json files about how to possibly score a bracket. There is no set format for the scoring data, and due to this fact, scoring data will vary quite a bit from sport to sport and year to year. You could even come up with your own scoring system, PR it, and then write your own module to score each bracket. It could be as simple as
  "scoring": {
    // Each correct pick is worth one point
    "simple": 1

or a pretty standard scoring system like:

  "scoring": {
    // Each correct pick is worth as many points as the value at the index of its round
    "standard": [10, 20, 40, 80, 160, 320]

or even as complex as the gooley scoring method which I have modeled here.

  • locks: a date string of when the bracket locks. Locking is when the first game of the bracket has begun and no more picks should be allowed.

Does this have X sport for Y year?

Probably not, but it's only a pull request away! All the data lives in JSON files under the ./data dir. To add a sport/year combination:

  1. Add a directory with the name of the sport (if it doesn't already exist)
  2. Add/edit a defaults.json file inside that sport's directory (if it doesn't already exist)
  3. Add a file YYYY.json inside that sport's directory

Right now the required properties are:

  • regions: an array of objects each with the properties id, name, and fullname. These are order dependent and the regions that play each other to get to the finalRegion should be at indexes 0,1 and 2,3 (in a 4 region bracket).
  • teams: an object where the keys are the ids from regions and the properties are arrays of team names in seed order
  • finalRegion: an object with a name and id property for the final region (could be Final Four, NBA Finals, etc)
  • order: an array of the seeds ordered by who would play each other in the first round

And the following properties are optional:

  • scoring: an object with properties that could be used to score the bracket
  • locks: a date string representing when the bracket "locks" aka when picks should no longer be allowed because the games have started

These properties are merged recursively (using lodash's merge) with the properties from defaults.json being overwritten by the properties from YYYY.json. This allows for things that don't change often (such as the order) to only be written in one place, whereas things such as teams (which change every year) to be located in the appropriate file.

Also see the above section for further explanation about these properites or go look at a complete example: defaults.json, YYYY.json.

Which sports does it have?

Currently it only has a few, but the next priority will be adding the 2014 data very quickly after it is available.

  • NCAA Mens Basketball ncaam: [2012-2016]
  • NCAA Womens Basketball ncaaw: [2016]
  • NHL nhl: [2015, 2016]
  • NBA nba: [2016]

Anything else?

If this is interesting to you, I think you should follow @tweetthebracket on Twitter. There are also a lot of other bracket related modules on our GitHub organization page.




Kind Requirements Latest Stable Latest Release Licenses
alce development ^1.2.0 1.2.0 1.2.0 MIT
browserify development ^14.0.0 14.1.0 14.1.0 MIT
cheerio development ^0.22.0 0.22.0 0.22.0 MIT
git-validate development ^2.1.4 2.2.2 2.2.2 MIT
js-size development ^2.0.0 2.0.0 2.0.0 MIT
lodash development ^4.14.2 4.17.4 4.17.4 MIT
lodash.merge runtime ^4.5.1 4.6.0 4.6.0 MIT
minimist development ^1.2.0 1.2.0 1.2.0 MIT
mkdirp development ^0.5.1 0.5.1 0.5.1 MIT
mocha development ^3.0.2 3.2.0 3.2.0 MIT
request development ^2.74.0 2.81.0 2.81.0 Apache-2.0
scores development ^3.3.0 3.4.1 3.4.1 MIT
standard development ^9.0.0 9.0.2 10.0.0-beta.2 MIT
walkdir development 0.0.11 0.0.11 0.0.11 MIT

Project Statistics

Sourcerank 7
Size 159 KB
Stars 3
Forks 0
Watchers 1
Open issues 1
Dependencies 14
Contributors 2
Tags 61
Last updated
Last pushed

Top Contributors See all

Luke Karrys Greenkeeper

Projects Referencing this Repo

bracket-data 4.5.10
Get some helpful data for a tournament bracket.
npm - JavaScript - MIT - Updated - 3 stars

Tags See all

v4.5.10 March 23, 2017
v4.5.9 March 16, 2017
v4.5.8 March 16, 2017
v4.5.7 March 14, 2017
v4.5.6 March 12, 2017
v4.5.5 March 12, 2017
v4.5.4 March 12, 2017
v4.5.3 March 12, 2017
v4.5.2 February 22, 2017
v4.5.1 February 14, 2017
v4.5.0 January 14, 2017
v4.4.1 January 11, 2017
v4.4.0 November 15, 2016
v4.2.4 August 09, 2016
v4.2.3 April 22, 2016
v4.2.2 April 21, 2016
v4.2.1 April 20, 2016
v4.2.0 April 14, 2016
v4.1.0 April 13, 2016
v4.0.20 March 17, 2016
v4.0.19 March 16, 2016
v4.0.18 March 15, 2016
v4.0.17 March 14, 2016
v4.0.16 March 13, 2016
v4.0.15 March 13, 2016
v4.0.14 March 12, 2016
v4.0.13 March 12, 2016
v4.0.12 March 12, 2016
v4.0.11 March 11, 2016
v4.0.10 March 10, 2016

Something wrong with this page? Make a suggestion

Last synced: 2017-03-23 18:06:01 UTC