Announcing a New API!

The Blue Alliance has long been committed to providing open data for the FRC community. Our current API (v2) launched in 2013 and has been a wild success – it has handled over 80 million requests in a single year! However, as TBA grows, we need to scale and iterate the API, as well.

As of June 1, 2017, APIv2 will be officially deprecated and superseded by a new version of The Blue Alliance API. In addition, APIv2 will no longer be accessible starting January 1, 2018.

What’s New in APIv3

Version 3 of The Blue Alliance API has some new and exciting features.

More ways to query. You can now request “simple models” or “keys only” from many endpoints. This is a way to make smaller queries and to fetch only the data your application needs. A “simple” model contains only the minimum required fields to display it.

Better data formats. Some endpoints have new formats that are more structured yet still flexible enough to handle year-to-year variance. For example, the rankings endpoint now contains metadata saying how to display each field.

More complete data. The Blue Alliance does a lot of work computing things about FRC Events. Now, all of this data is exposed in the API so you don’t have to duplicate that work! APIv3 contains:

  • Team@Event statuses, so you know exactly how a team is doing at an event. This contains pre-rendered status strings, as well as all the information required to build your own.
  • Event Insights that contain statistics on when various objectives are completed at each events. This is the same information you see on the web under the Insights tab
  • Match predictions so you can access how TBA thinks a match will pan out. We make no guarantees on the accuracy of our predictions, so take them with a grain of salt and remember they’re just for fun. Warning: this endpoint is still under development, so the format may change unexpectedly before the 2018 season.
  • Predicted match times, so you know when a match will actually start, based on the event’s current timeliness. For more information on how these work, see this tech talk blog post.
  • Winning alliance of a match, because tiebreakers are hard

Getting Started

You must submit an API key with each request you make (except for when you’re logged in to TBA and making requests via your web browser, for debugging convenience). API keys can be generated on your Account Dashboard. Pass the API key in the header or URL Parameter ‘X-TBA-Auth-Key’. Once you have your API key, you can start making requests. Check out the documentation and have at it! If you run into any trouble, let us know on GitHub and we’ll work to fix it.

Finally, I’d like to give a huge thanks to everybody on the TBA team who contributed and helped make APIv3 a reality, especially Eugene Fang and Brian Rozmierski. If you’d like to help improve our APIs yourself, let us know, we’re always looking for new contributors!

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s