API Documentation

Overview

The FIRST Alliance API was designed out of the realization that no official FIRST Robotics Competition APIs existed and that teams worldwide were implementing their own solutions for obtaining official FRC event data. We also realized that there were existing web applications and services that provided a similar feature set as The FIRST Alliance, however, these existing solutions were flawed.

Designed with our “API first” thinking, The FIRST Alliance API was built to provide the quickest and easiest way to access official FRC match results, team, and event information. Simply put, our user friendly and stable API is designed to empower creative individuals to build amazing things.

So good luck as you learn, create, and hack. We’re just glad we can help!

Getting Started

Requesting

There are two main api pages that can be requested. The first is api.json.php which returns all data back as JSON formatted responses, and the second is api.xml.php which returns all data back as XML formatted responses. Examples requests/responses can be found below. All function/parameters can be supplied as POST, GET or a combination of the both for ease of programming. All requests to the api must have an action supplied. This action describes what the request is looking for. A list of actions and associated parameters can be found below

Response

The server encapsulates all data within a simple shell. This shell has 2 values to it result and data. If the query was successful, result will be true and data will be filled with the response data. If the query was unsuccessful however, result will be false, and data will be a simple explanation of why it failed.

Examples

All examples will use GET parameters for ease of display, but all parameters (including action) can be supplied via POST.

List Teams Example: http://www.thefirstalliance.org/api/api.json.php?action=list-teams
Would return something along the lines of this:
{"result":true,"data":[.....teams go here.....]}

Event Details Example: http://www.thefirstalliance.org/api/api.json.php?action=event-details
Would return something along the lines of this:
{"result":true,"data":[.....teams go here.....]}

Incorrect Action Example: http://www.thefirstalliance.org/api/api.json.php?action=space
Would fail because there is no action called “space” so it would return
{"result":false,"data":"Invalid Action: space"}

No Action Example: http://www.thefirstalliance.org/api/api.json.php
Would fail because there is no action specified, so it would return
{"result":false,"data":"No Action Specified"}

Data Objects

All responses return either a whole or partial data object. The data objects consist solely of a Key-Value pair as described below Some api functions only return partial versions of the following data objects.
  • Team
    • id - Unique Identifier for team
    • number - Team Number
    • name - Team Name
    • daat - Extra Team Properties
  • Match
    • id - Unique Identifier for that match
    • year - The year this match took place on
    • event_id - The event id that this match happened in
    • match_number - The number of the match
    • (red_1_id -> blue_3_id) - These 6 fields contain the id’s of the teams playing
    • (red_1_num -> blue_3_num) - These 6 fields contain the numbers of the teams playing
    • red_score - Red Team Score
    • blue_score - Blue Team Score
    • timestamp - Timestamp of when this match data was collected last
    • match_type - Either 1 for Qualifications match or 2 for Eliminations
    • description - Describes Elimination match or null if Qualification match
  • Event
    • id - Unique Identifier for that event
    • name - Name of the event
    • api_name - Shorthand name used for queries
    • start_date - Start day of the event
    • end_date - End day of the event
    • rank_date - Last update time of rankings
    • rankings - JSON encoded rankings, more on this field later

API Requests

Select an API request for more details
Action:
list-events
Description:
Returns list of events worldwide
Parameters:
void
Returns:
List of partial event data objects (id, name, api_name fields only)