The Blue Alliance cares about making our data publicly accessible via our various APIs. We want to help inspire people to build their own projects and get started with data analysis and software development. This page explains the APIs we provide and how to get started using them.
Here are some areas where you can ask the TBA developer community for assistance if you run into trouble.
Before you get started using The Blue Alliance APIs, you need to be familiar with a few elements of web technology. The Blue Alliance APIs work by having your computer send a web request to our servers asking for some piece of data, and our servers send the data back to your computer. You can ask for information about teams or matches, or even send us information, like letting us know there's a robot photo we should add to our data set.
First, you need some way of sending HTTPS Requests to The Blue Alliance's servers. This will be your primary means of communication with TBA. For testing purposes, your web browser may suffice. For more advanced applications, you may want to use an external library. jQuery (Javascript), Requests (Python), and OkHttp (Java) are all examples of HTTPS Libraries.
You will also need to be familiar with JSON, a machine-readable format for sending and receiving data. Most of the TBA APIs use JSON-formatted data, so you should find out how to parse JSON text in the language of your choice.
Once you've figured out how to make HTTPS requests, you will need to figure out how to manipulate request and response headers. These will be used to pass authentication keys to TBA and understand the cache life of returned data.
Most people want to pull event listings, team information, match results, or statistics from The Blue Alliance to use in their own application. The read API is the way to do this. This API exposes almost all of the data you see on TBA to your application in a machine-readable format called JSON.
To get started using APIv3, you first need to generate an access token on your Account Dashboard in the Read API Keys section. This key needs to be passed along with each request you make in the header (or URL parameter) X-TBA-Auth-Key. If you are logged in to your TBA account, you can access the API without a key by simply navigating to an API URL in your web browser. All requests should be made to the base URL https://www.thebluealliance.com/api/v3.
To see complete details of data accessible via APIv3, please see the APIv3 full documentation.
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.
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.
The Blue Alliance automatically builds and publishes client libraries to make it easier for you to get started using APIv3. The libraries are automatically generated by Swagger Codegen and are not provided with any guarantee of support from The Blue Alliance and are not guaranteed to be complete implementations of the API. They are merely provided as a convenience to developers looking to get started and can be found on the TBA-API GitHub
The Blue Alliance also provides continued access to our version 2 read API. The v2 API is deprecated and will be shut down on January 1, 2018.
All API users are strongly encouraged to use the v3 API which provides more information than is available in our v2 API.
Legacy documentation on v2 is still available.
The TBA API also includes support for webhooks, or HTTP callbacks. When an item of interest changes, TBA can send a HTTP request to your server, allowing your application to react instantly to the change. 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.
Write API (v1)
The Blue Alliance provides a Write API, called the Trusted API, which allows users to import data to The Blue Alliance for archival. For example, many offseason events use the Trusted API to provide real-time match results to their audience. To get started, you need to request access tokens for your desired event. These need to be used when constructing each request.
To see the complete specification of the trusted API, refer to the full documentation.
If you're looking to run SQL queries over the TBA database, you can use this BigQuery dataset. This contains a full replica of the TBA database, so the possibilities are endless!
If these APIs are too complex for your application, The Blue Alliance also provides periodic data archives in comma separated value (CSV) format. The data provided here is less detailed, but is simpler to use in Excel spreadsheets, for example.
You can find these data archives on the-blue-alliance/the-blue-alliance-data GitHub.
We’re excited to see you building things on top of The Blue Alliance’s APIs! We love seeing the creativity and utility in these projects. We have a few developer guidelines to help guide your work.
