Public API (v2)

Overview

This documentation is for The Blue Alliance's public web API for programmatically accessing data.

The API and code are open source. If you find a bug, want a new feature, or are interested in helping us improve it, visit us on GitHub and file an issue or send a pull request. If you have any questions about this API or would like to stay up-to-date on its development, you can join our developer's mailing list.

X-TBA-App-Id Header or URL Parameter

So we can know how the API is being used to prioritize future development, we require clients to identify themselves. All API requests must include a unique, descriptive X-TBA-App-Id header or URL parameter to identify the application.

The X-TBA-App-Id needs to follow this format: <team/person id>:<app description>:<version> and not use any colons except for the two already present.

Valid examples:

  • frc281:scouting-system:v01
  • woodie_flowers:match_scraper:5

Last-Modified and If-Modified-Since Headers

All API responses have a Last-Modified header, which indicates the date and time at which the data at a particular endpoint was last updated. When making repeated calls to a particular endpoint, you should set the If-Modified-Since header in your request to the value of Last-Modified from the previous call to that endpoint. On the first call, If-Modified-Since does not need to be set.

Consumers of the TBA API are highly encouraged to make use of these headers. If the server determines that no data has been updated, it returns a 304 Not Modified response with an empty body, saving both the server and the consumer time and bandwidth.

Cache-Control Header

If your application makes many queries to the TBA API and you are capable of caching the results locally, the Cache-Control header will provide guidance on how long the API response can remain valid in a local cache. In particular, the max-age value in the Cache-Control header contains the number of seconds the API result should be considered valid for. See also Google's Cache-Control reference.

API Endpoint

Requests made to the API should be made using SSL to www.thebluealliance.com.

Checking the Datafeed Status

At times, it may be useful to know the status of the datafeeds from which the API is updated. This may be done by sending an API request to https://www.thebluealliance.com/api/v2/status. If a specific event is no longer updating, it is included inside the array down_events; if the entire FMSAPI is down, is_datafeed_down is set to true.

Webhooks

The TBA API also includes support for webhooks. We can push notifications for things you've subscribed to your sever. This can save both your client and our server time and processing power, as it can reduce the need to poll the API. See this page for more documentation on webhooks.


Models

Team Model

Related: Team Request

Response Data
Key Description Examples
website Official website associated with the team http://www.entech281.com
name Official long form name registered with FIRST Michelin/Caterpillar/Greenville Technical College/Greenville...
locality City of team derived from parsing the address registered with FIRST Greenville
region State of team derived from parsing the address registered with FIRST SC
country_name Country of team derived from parsing the address registered with FIRST USA
location Long form address that includes city, state, and country provided by FIRST Greenville, SC, USA
team_number Official team number issued by FIRST 281
key TBA team key with the format frcyyyy frc281
nickname Team nickname provided by FIRST EnTech GreenVillians
rookie_year Team's rookie year 1999
motto Team's Motto Infiltrating Young Minds One Robot at a Time

Event Model

Related: Event Request

Response Data
Key Description Examples
key TBA event key with the format yyyy[EVENT_CODE], where yyyy is the year, and EVENT_CODE is the event code of the event. 2010sc
name Official name of event on record either provided by FIRST or organizers of offseason event. Palmetto Regional
short_name name but doesn't include event specifiers, such as 'Regional' or 'District'. May be null. Palmetto
event_code Event short code. SC
event_type_string A human readable string that defines the event type. 'Regional', 'District', 'District Championships'…see more
event_type An integer that represents the event type as a constant. List of constants to event type
event_district_string A human readable string that defines the event's district. 'Michigan', 'Mid Atlantic', null (if regional)…see more
event_district An integer that represents the event district as a constant. List of constants to event district
year Year the event data is for. 2010
week Week of the event relative to the first official season event. Only valid for Regionals, Districts, and District Championships. Null otherwise. 2
location Long form address that includes city, and state provided by FIRST Clemson, SC
venue_address Address of the event's venue, if available. Line breaks included. Long Beach Arena\n300 East Ocean Blvd\nLong Beach, CA 90802\nUSA
timezone Timezone name, as found in the tz database America/New_York
website The event's website, if any. http://www.firstsv.org
official Whether this event used the official FMS. true
teams List of team models that attended the event
matches List of match models for the event.
awards List of award models for the event.
webcast If the event has webcast data associated with it, this contains JSON data of the streams
alliances If we have alliance selection data for this event, this contains a JSON array of the alliances. The captain is the first team, followed by their picks, in order.
district_points If this event is part of a district, this contains the number and breakdown of points that each team attending earned.

Match Model

Related: Event Matches Request

Response Data
Key Description Examples
key TBA event key with the format yyyy[EVENT_CODE]_[COMP_LEVEL]m[MATCH_NUMBER], where yyyy is the year, and EVENT_CODE is the event code of the event, COMP_LEVEL is (qm, ef, qf, sf, f), and MATCH_NUMBER is the match number in the competition level. A set number may append the competition level if more than one match in required per set . 2010sc_qm10, 2011nc_qf1m2
comp_level The competition level the match was played at. qm, ef, qf, sf, f
set_number The set number in a series of matches where more than one match is required in the match series. 2010sc_qf1m2, would be match 2 in quarter finals 1.
match_number The match number of the match in the competition level. 2010sc_qm20
alliances A list of alliances, the teams on the alliances, and their score.
score_breakdown Score breakdown for auto, teleop, etc. points. Varies from year to year. May be null.
event_key Event key of the event the match was played at. 2011sc
videos JSON array of videos associated with this match and corresponding information "videos": [{"key": "xswGjxzNEoY", "type": "youtube"}, {"key": "http://videos.thebluealliance.net/2010cmp/2010cmp_f1m1.mp4", "type": "tba"}]
time_string Time string for this match, as published on the official schedule. Of course, this may or may not be accurate, as events often run ahead or behind schedule 11:15 AM
time UNIX timestamp of match time, as taken from the published schedule 1394904600

Award Model

Related: Event Awards Request

Response Data
Key Description Examples
name The name of the award from TIMS. May vary for the same award type. Engineering Inspiration
award_type An integer that represents the award type as a constant. List of constants to award type
event_key The event_key of the event the award was won at. 2011sc
recipient_list A list of recipients of the award at the event. Either team_number or awardee for individual awards. {"team_number": 281, "awardee": null}
year The year this award was won. 2010

Media Model

Related: Team Media Request

Response Data
Key Description Examples
type The string type of the media element, as determined here. cdphotothread
foreign_key The key used to indentify this media element on the remote site (e.g YouTube video key) aFZy8iibMD0
details If the media requires it, a json dict of additional information {"image_partial": "fe3/fe38d320428adf4f51ac969efb3db32c_l.jpg"}
preferred Whether the media is considered to be of high quality. true

Robot Model

Related: Team History Robots Request

Response Data
Key Description Examples
key A key identifying the robot object. Formed like <team_key>_<year> frc1124_2015
team_key The associated Team key frc1124
year The year this Robot model refers to 2015
name The robot name in this year Orion

Team Requests

Team List Request

Related: Team Model

Request format: https://www.thebluealliance.com/api/v2/teams/<page_num>

Key Description Examples
page_num A page of teams, zero-indexed. Each page consists of teams whose numbers start at start = 500 * page_num and end at end = start + 499, inclusive. 0, 5, 7

Example GET Request:

https://www.thebluealliance.com
            

Team Request

Related: Team Model

Request format: https://www.thebluealliance.com/api/v2/team/<team key>

Key Description Examples
team key A team key name where the format is frcyyyy where yyyy is the a valid, official team number issued by FIRST frc1, frc281, frc1114

Example GET Request:

https://www.thebluealliance.com
            

Team Events Request

Related: Event Model

Request format: https://www.thebluealliance.com/api/v2/team/<team key>(/<year>)/events

Key Description Examples
team key A team key name where the format is frcyyyy where yyyy is the a valid, official team number issued by FIRST frc1, frc281, frc1114
year A specific year you would like to grab data for this team. Defaults to current year if not provided. 2008, 2013

Example GET Request:

https://www.thebluealliance.com
            

Team Event Awards Request

Related: Award Model

Request format: https://www.thebluealliance.com/api/v2/team/<team key>/event/<event key>/awards

Key Description Examples
team key A team key name where the format is frcyyyy where yyyy is the a valid, official team number issued by FIRST frc1, frc281, frc1114
event key TBA event key with the format yyyy[EVENT_CODE], where yyyy is the year, and EVENT_CODE is the event code of the event. 2014casj, 2010cmp

Example GET Request:

https://www.thebluealliance.com
            

Team Event Matches Request

Related: Match Model

Request format: https://www.thebluealliance.com/api/v2/team/<team key>/event/<event key>/matches

Key Description Examples
team key A team key name where the format is frcyyyy where yyyy is the a valid, official team number issued by FIRST frc1, frc281, frc1114
event key TBA event key with the format yyyy[EVENT_CODE], where yyyy is the year, and EVENT_CODE is the event code of the event. 2014casj, 2010cmp

Example GET Request:

https://www.thebluealliance.com
            

Team Years Participated Request

Request format: https://www.thebluealliance.com/api/v2/team/<team key>/years_participated

Key Description Examples
team key A team key name where the format is frcyyyy where yyyy is the a valid, official team number issued by FIRST frc1, frc281, frc1114

Example GET Request:

https://www.thebluealliance.com
            

Team Media Request

Related: Media Model

Request format: https://www.thebluealliance.com/api/v2/team/<team key>(/<year>)/media

Key Description Examples
team key A team key name where the format is frcyyyy where yyyy is the a valid, official team number issued by FIRST frc1, frc281, frc1114
year A specific year you would like to grab data for this team. Defaults to current year if not provided. 2008, 2013

Example GET Request:

https://www.thebluealliance.com
            

Team History Events Request

Related: Event Model

Request format: https://www.thebluealliance.com/api/v2/team/<team key>/history/events

Key Description Examples
team key A team key name where the format is frcyyyy where yyyy is the a valid, official team number issued by FIRST frc1, frc281, frc1114

Example GET Request:

https://www.thebluealliance.com
            

Team History Awards Request

Related: Awards Model

Request format: https://www.thebluealliance.com/api/v2/team/<team key>/history/awards

Key Description Examples
team key A team key name where the format is frcyyyy where yyyy is the a valid, official team number issued by FIRST frc1, frc281, frc1114

Example GET Request:

https://www.thebluealliance.com
            

Team History Robots Request

Related: Robot Model

Request format: https://www.thebluealliance.com/api/v2/team/<team key>/history/robots

Key Description Examples
team key A team key name where the format is frcyyyy where yyyy is the a valid, official team number issued by FIRST frc1, frc281, frc1114

Example GET Request:

https://www.thebluealliance.com
            

Team History Districts Request

Request format: https://www.thebluealliance.com/api/v2/team/<team key>/history/districts

Key Description Examples
team key A team key name where the format is frcyyyy where yyyy is the a valid, official team number issued by FIRST frc1, frc281, frc1114

Example GET Request:

https://www.thebluealliance.com
            

Event Requests

Event List Request

Related: Event Model

Request format: https://www.thebluealliance.com/api/v2/events/<year>

Key Description Examples
year A year to specify what year of events you want. Valid years are within 1992, and the current year + 1. Defaults to current year if not specified. 2010

Example GET Request:

https://www.thebluealliance.com
            

Event Request

Related: Event Model

Request format: https://www.thebluealliance.com/api/v2/event/<event key>

Key Description Examples
event key TBA event key with the format yyyy[EVENT_CODE], where yyyy is the year, and EVENT_CODE is the event code of the event. 2010sc

Example GET Request:

https://www.thebluealliance.com
            

Event Teams Request

Related: Team Model

Request format: https://www.thebluealliance.com/api/v2/event/<event key>/teams

Key Description Examples
event key TBA event key with the format yyyy[EVENT_CODE], where yyyy is the year, and EVENT_CODE is the event code of the event. 2010sc

Example GET Request:

https://www.thebluealliance.com
            

Event Matches Request

Related: Match Model

Request format: https://www.thebluealliance.com/api/v2/event/<event key>/matches

Key Description Examples
event key TBA event key with the format yyyy[EVENT_CODE], where yyyy is the year, and EVENT_CODE is the event code of the event. 2010sc

Example GET Request:

https://www.thebluealliance.com
            

Event Stats Request

Request format: https://www.thebluealliance.com/api/v2/event/<event key>/stats

Key Description Examples
event key TBA event key with the format yyyy[EVENT_CODE], where yyyy is the year, and EVENT_CODE is the event code of the event. 2010sc

Example GET Request:

https://www.thebluealliance.com
            

Event Rankings Request

Request format: https://www.thebluealliance.com/api/v2/event/<event key>/rankings

Key Description Examples
event key TBA event key with the format yyyy[EVENT_CODE], where yyyy is the year, and EVENT_CODE is the event code of the event. 2010sc

Example GET Request:

https://www.thebluealliance.com
            

Event Awards Request

Request format: https://www.thebluealliance.com/api/v2/event/<event key>/awards

Key Description Examples
event key TBA event key with the format yyyy[EVENT_CODE], where yyyy is the year, and EVENT_CODE is the event code of the event. 2010sc

Example GET Request:

https://www.thebluealliance.com
            

Event District Points Request

Request format: https://www.thebluealliance.com/api/v2/event/<event key>/district_points

Key Description Examples
event key TBA event key with the format yyyy[EVENT_CODE], where yyyy is the year, and EVENT_CODE is the event code of the event. 2010sc

Example GET Request:

https://www.thebluealliance.com
            

Match Requests

Single Match Request

Request format: https://www.thebluealliance.com/api/v2/match/<match_key>

Key Description Examples
match_key Key for the match you want to request data for 2014cmp_f1m1

Example GET Request:

https://www.thebluealliance.com
            

District Requests

District List Request

Request format: https://www.thebluealliance.com/api/v2/districts/<year>

Key Description Examples
Year The year you want data for 2014

Example GET Request:

https://www.thebluealliance.com
            

District Events Request

Request format: https://www.thebluealliance.com/api/v2/district/<district short>/<year>/events

Key Description Examples
district short The district abbreviation you want data for, as defined here ne
Year The year you want data for 2014

Example GET Request:

https://www.thebluealliance.com
            

District Rankings Request

Request format: https://www.thebluealliance.com/api/v2/district/<district short>/<year>/rankings

Key Description Examples
district short The district abbreviation you want data for, as defined here ne
Year The year you want data for 2014

Example GET Request:

https://www.thebluealliance.com
            

District Teams Request

Request format: https://www.thebluealliance.com/api/v2/district/<district short>/<year>/teams

Key Description Examples
district short The district abbreviation you want data for, as defined here ne
Year The year you want data for 2014

Example GET Request:

https://www.thebluealliance.com
            

API Libraries

These libraries have been created by our community to help you use our API in your next project.

Note that these libraries are not created by The Blue Alliance. Please contact the respective developers for support.

Language Repository
C# TheBlueAlliance_API
Java tba-apiv2-java
Java TheBlueAlliance
Java java-blue-alliance-api
Java TheBlueAllianceJavaAPI
Java TBA-API
Javascript thebluealliance-javascript
Node.js node-thebluealliance
Node.js tba-api-node
Node.js thebluealliance-nodewrapper
Node.js the-node-alliance
Python The-Blue-Alliance-Python-API
Python tbapy
Python TBApi
Ruby thebluealliance-ruby
Ruby tba.rb
Crystal TheBlueAlliance
Go tbago
Objective-C TBAKit
Objective-C TheBlueAlliance_API
PHP thebluealliance-phpwrapper

Made a library that you want to be included? Let us know!