node-thebluealliance

node-thebluealliance is a node.js wrapper library for The Blue Alliance v2 API. See the v2 API page for more information on what data can be returned.

This app uses The Blue Alliance's post-2013 event codes.

Installation

First install node. Then:

$ npm install thebluealliance

This will download node-thebluealliance to the local node_modules folder, from which it can be imported with require.

node-thebluealliance API docs

Notes on the API

• Arguments

  • frc_id refers to the number assigned to each team by FIRST (i.e. 1540, 254, etc.)
  • event_id refers to The Blue Alliance's post-2013 event codes

• CONSISTENT ACROSS EVERY FUNCTION: In node's style, all callbacks will receive an error object as the first argument. A null error object indicates a successful request. The second argument in the callback will contain unchanged queried data from The Blue Alliance. The Blue Alliance data models are available under the Models sections of the API webpage.

callback(err, data)

err

type: null or Error Object

data

Queried data returned by The Blue Alliance

• CONSISTENT ACROSS EVERY FUNCTION: The year argument is always optional and will always default to the current year. For example, calling

tba.getTeamsAtEvent('arc', callback);

is the same as calling

tba.getTeamsAtEvent('arc', (new Date()).getFullYear(), callback);

year

type: number default: current year

The year for which data will be returned.

• Suggestions for improvement are always welcome at hmzh.khn@gmail.com

Methods Summary

• initTBA
• tba
  • getListOfTeams / getTeamList
  • getTeamById / getTeam
  • getEventsForTeam / getTeamEvent
  • getAwardsForTeamAtEvent / getTeamEventAwards
  • getMatchesForTeamsAtEvent / getTeamEventMatches
  • getYearsParticipatedByTeam / getTeamYearsParticipated
  • getMediaForTeam / getTeamMedia
  • getListOfEvents / getEventList
  • getEventById / getEvent
  • getTeamsAtEvent / getEventTeams
  • getMatchesAtEvent / getEventMatches
  • getStatsAtEvent / getEventStats
  • getRankingsAtEvent / getEventRankings
  • getAwardsAtEvent / getEventAwards
  • getEventHistoryForTeam / getTeamEventHistory
  • getAwardHistoryForTeam / getTeamAwardHistory
  • getRobotHistoryForTeam / getTeamRobotHistory
  • getDistrictHistoryForTeam / getTeamDistrictHistory
  • getSingleMatchFromKey / getSingleMatch

initTBA(identifier, description, version_number)

var initTBA = require('thebluealliance');
var tba = initTBA('node-thebluealliance','Node.js wrapper library for the TBA v2 API','1.1.1');

// or as a shortcut

var tba = require('thebluealliance')('node-thebluealliance','Node.js wrapper library for the TBA v2 API','1.1.1');

The Blue Alliance v2 API requires a custom X-TBA-App-Id header in order to accept requests. Calling initTBA allows node-thebluealliance to retain this header for the duration of the library's use. Calling initTBA returns the tba object, which contains all of the methods required to retrieve data from The Blue Alliance.

identifier

Type: String

Name or organization of the user.

description

Type: String

Description of the application requesting data from The Blue Alliance.

version_number

Type: String or Number

Version number of the application requesting data from The Blue Alliance.

tba.getListOfTeams(page_num, callback(err, list_of_teams))

aliased as tba.getTeamList

Team List Request on TBA API docs Gets all the teams on one page of the team list at TBA

data_type: Array of Teams

tba.getTeamById(frc_id, callback(err, team_info))

aliased as tba.getTeam

Team Request on TBA API docs Gets one team`s background info by its team id

tba.getEventsForTeam(frc_id[, year], callback(err, event_info))

aliased as tba.getTeamEvent

Team Events Request on TBA API docs Gets all the team`s events from a single year

tba.getAwardsForTeamAtEvent(frc_id, event_id[, year], callback(err, awards_list))

aliased as tba.getTeamEventAwards

Team Event Awards Request on TBA API docs Gets all the teams awards for a single year at a single event

tba.getMatchesForTeamsAtEvent(frc_id, event_id, [year], callback(err, matches_list))

aliased as tba.getTeamEventMatches

Team Event Matches Request on TBA API docs Gets all the team`s matches at a single event in a single year

tba.getYearsParticipatedByTeam(frc_id, callback(err, list_of_years))

aliased as tba.getTeamYearsParticipated

Team Years Participated Request on TBA API docs returns array of years that the team has been participated in FIRST

tba.getMediaForTeam(frc_id, [year], callback(err, media_list))

aliased as tba.getTeamMedia

Team Media Request on TBA API docs Gets all the teams media for a single year, as collected on TBA

tba.getEventHistoryForTeam(frc_id, callback(err, event_history))

aliased as tba.getTeamEventHistory

'Team History Events Request' on TBA API docs Gets all historical events for a given team

tba.getAwardHistoryForTeam(frc_id, callback(err, award_history))

aliased as tba.getTeamAwardHistory

'Team History Awards Request' on TBA API docs Gets all historical awards for a given team

tba.getRobotHistoryForTeam(frc_id, callback(err, robot_history))

aliased as tba.getTeamRobotHistory

'Team History Robots Request' on TBA API docs Gets all historical robots for a given team

tba.getDistrictHistoryForTeam(frc_id, callback(err, robot_history))

aliased as tba.getTeamDistrictHistory

'Team History Districts Request' on TBA API docs Gets all historical districts for a given team

tba.getListOfEvents([year], callback(err, list_of_teams))

aliased as tba.getEventList

Team List Request on TBA API docs Gets all the events in FIRST in a single year

tba.getEventById(eventId[, year], callback(err, event_object))

aliased as tba.getEvent

Event Request on TBA API docs Gets event info for a single year

tba.getTeamsAtEvent(eventId[, year], callback(err, teams_list))

aliased as tba.getEventTeams

Event Teams Request on TBA API docs get all of the teams at an event

tba.getMatchesAtEvent(eventId[, year], callback(err, matches_list))

aliased as tba.getEventMatches

Event Matches Request on TBA API docs get all of the matches at an event

tba.getStatsAtEvent(eventId[, year], callback(err, stats_object))

aliased as tba.getEventStats

Event Stats Request on TBA API docs Gets the stats for a single event

tba.getRankingsAtEvent(eventId[, year], callback(err, rankings_list))

aliased as tba.getEventRankings

Event Rankings Request on TBA API docs Gets the rankings for a single event

tba.getAwardsAtEvent(eventId[, year], callback(err, awards_list))

aliased as tba.getEventAwards

Event Awards Request on TBA API docs Gets awards at an event in a single year

tba.getSingleMatchFromKey(match_key, callback(err, match_data))

aliased as tba.getSingleMatch

Single Match Request on TBA API docs Gets information from 1 match at an event using a match key (see Match Model - key on TBA API docs)

Example Code

tba.getTeamsAtEvent('casb', function(err, teamsInfo) {
  // teamsInfo is a list of teams at the Inland Empire Regional for the current year
  //...
});

Support

• bug reports

To-Do List

• more clarity in documentation
• add better example code
• tests w/ Mocha
• ability to pass in more variants of ids/years (i.e. '2014orore' instead of getEvent('orore',2014))

Upcoming functionality improvements

• methods that allow analysis of certain data subsets (maybe a separate library for this)
• data caching for things that are unlikely to change
  • for this one, limitations due to TBA API (can't get data subsets easily)

MIT License

Copyright © 2014 Hamzah Khan <hmzh.khn@gmail.com>

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the 'Software'), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.