Automate Outreach Data with The Blue Alliance API

Impact judges reward teams that measure themselves. One verifiable data source is The Blue Alliance (TBA), which exposes every team’s events, awards, and history via a free REST API. This mini-project builds a script that fetches your team’s award and event record automatically — useful for the ‘goals and progress’ and ‘role models’ summaries, and for tracking the teams you mentor.

Step 1 — Get a read key. Log in at thebluealliance.com, open your Account dashboard, and under Read API Keys generate a key. Every request must send it in the header X-TBA-Auth-Key.

Step 2 — Know the endpoint shape. The API v3 base URL is https://www.thebluealliance.com/api/v3. Team keys use the format frcNNNN (e.g. frc5985). Three endpoints you will use constantly:

• /team/{team_key}/awards — every award the team has ever won
• /team/{team_key}/events/{year} — events for a given season
• /team/{team_key}/years_participated — list of seasons the team competed

Step 3 — Write the script.

import requests

TBA_KEY = "YOUR_READ_KEY"          # from Account > Read API Keys
TEAM = "frc5985"                  # your team in frcNNNN form
BASE = "https://www.thebluealliance.com/api/v3"
HEADERS = {"X-TBA-Auth-Key": TBA_KEY}

def get(path):
    r = requests.get(BASE + path, headers=HEADERS, timeout=15)
    r.raise_for_status()
    return r.json()

awards = get(f"/team/{TEAM}/awards")
for a in sorted(awards, key=lambda x: x["year"]):
    print(a["year"], a["name"], "@", a["event_key"])

# Count Impact / Chairman's banners (award renamed in 2022)
impact = [a for a in awards
          if "impact" in a["name"].lower()
          or "chairman" in a["name"].lower()]
print(f"\nImpact/Chairman's awards: {len(impact)}")

raise_for_status() will surface a 401 immediately if your key is wrong — debug that before anything else.

Step 4 — Extend it for mentored teams. Keep a list of the teams you started or mentor and pull their first competition year to prove you launched them:

mentored = ["frc9999", "frc8888"]
for t in mentored:
    yrs = get(f"/team/{t}/years_participated")
    print(t, "rookie year:", min(yrs))

Now a claim like ‘we started this team in 2023’ is backed by years_participated data, not a guess.

Why this matters. Judges can verify everything on TBA. If your submission says you won three District Impact Awards, a script that prints them removes any doubt and any typo. It also forces honesty: the API is the ground truth. The official Definitions even warn that teams ‘do not embellish or exaggerate’ and should ‘estimate on the low end’ — anchoring numeric claims to TBA keeps you defensible in the interview.

Stretch goal: schedule the script (cron or GitHub Actions) to dump a CSV monthly into your Impact Tracker so your award history is always current heading into kickoff in January.

Key takeaways

• TBA API v3 is free, verifiable ground truth: base URL https://www.thebluealliance.com/api/v3, key format frcNNNN, auth via the X-TBA-Auth-Key header.
• The /team/{key}/awards and /team/{key}/years_participated endpoints let you prove award counts and the rookie years of teams you started or mentor.
• Anchor every numeric claim in your submission to a verifiable source so it survives judge scrutiny in the interview.

This lesson was adapted from learnfrc.com.