v2 of The Blue Alliance API has been deprecated as of June 1, 2017. This means there will be no further development and no further changes will be made. Please migrate your apps to APIv3. APIv2 will be decommissioned on January 1, 2018.
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.
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.
frc281:scouting-system:v01woodie_flowers:match_scraper:5All 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.
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.
Requests made to the API should be made using SSL to www.thebluealliance.com.
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.
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.
| 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 |
| 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. |
| 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 |
| 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 |
| 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 |
| 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 |
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 |
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 |
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 |
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 |
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 |
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 |
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 |
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 |
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 |
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 |
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 |
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 |
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 |
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 |
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 |
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 |
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 |
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 |
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 |
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 |
Request format:
https://www.thebluealliance.com/api/v2/districts/<year>
| Key | Description | Examples |
|---|---|---|
| Year | The year you want data for | 2014 |
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 |
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 |
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 |
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!
