Mini-Project 5: Auto-Pull Match Results from The Blue Alliance API

Manually typing match scores into a graphic is slow and error-prone. The Blue Alliance (TBA) APIv3 lets you pull your results programmatically so a graphics template can populate itself.

Step 1 — Get a read API key. Sign in at thebluealliance.com, open your Account page, scroll to ‘Read API Keys,’ add a description, and click add. This is free. Treat the key like a password (don’t publish it), and send it on every request in the X-TBA-Auth-Key header.

Step 2 — Understand the endpoints. All URIs are relative to the base URL https://www.thebluealliance.com/api/v3. Useful ones:

• /team/frc1234/events/2026 — your events this season.
• /team/frc1234/event/2026casd/matches — your matches at a specific event.
• /team/frc1234/media/2026 — your robot photos, reveal videos, and CAD links on TBA.

Team keys take the form frcNNNN; event keys are the year plus an event code (e.g. 2026casd), which you can read off the event’s TBA page.

Step 3 — A working script. Install the community Python wrapper tbapy (maintained by FRC 1418) or just use requests:

import requests

TBA_KEY = "YOUR_READ_API_KEY"
TEAM = "frc1234"
EVENT = "2026casd"  # event key from TBA
BASE = "https://www.thebluealliance.com/api/v3"
HEADERS = {"X-TBA-Auth-Key": TBA_KEY}

url = f"{BASE}/team/{TEAM}/event/{EVENT}/matches"
matches = requests.get(url, headers=HEADERS).json()

for m in sorted(matches, key=lambda x: x["match_number"]):
    if m["comp_level"] != "qm":
        continue  # qualification matches only
    red = m["alliances"]["red"]
    blue = m["alliances"]["blue"]
    on_red = TEAM in red["team_keys"]
    us, them = (red, blue) if on_red else (blue, red)
    result = "W" if us["score"] > them["score"] else "L"
    print(f"Q{m['match_number']}: {us['score']}-{them['score']} ({result})")

This prints, for example, Q12: 88-74 (W) for every qualification match — ready to drop into a recap graphic.

Step 4 — Feed your graphics. Export the results to a CSV or JSON, then use them as a data source in a Canva bulk-create template or a simple HTML graphic. Now a ‘Day 1 Recap’ image populates from real data in seconds.

Step 5 — Optional: the Trusted (Write) API. For offseason events your team runs, TBA’s Trusted API lets you push match results to TBA so your audience sees scores. You request per-event auth tokens and sign each request — more advanced, but powerful for hosting your own event.

Etiquette: Cache responses. TBA returns Last-Modified and ETag headers; send them back as If-Modified-Since and If-None-Match and the server replies 304 Not Modified with an empty body when nothing changed (track these per-URL). A User-Agent header is also recommended to avoid 403s. Respect their service — TBA is a volunteer-run nonprofit relied on by the whole community.

Key takeaways

• Generate a free TBA Read API key (Account > Read API Keys) and send it in the X-TBA-Auth-Key header on every request.
• Base URL is https://www.thebluealliance.com/api/v3; pull matches with /team/frc1234/event/{eventKey}/matches and read scores from alliances.red/blue.
• Export results to CSV/JSON to auto-populate recap graphics instead of typing scores by hand.
• Cache with ETag/Last-Modified (expect 304 responses) and set a User-Agent — TBA is a volunteer-run nonprofit resource.

This lesson was adapted from learnfrc.com.