ftc-events-api

name: ftc-events-api description: >- Integrate with the official FIRST Tech Challenge Events API in FTC Metrics. Use when fetching events, teams, matches, scores, rankings, or troubleshooting FTC API authentication and responses. license: MIT compatibility: [Claude Code] metadata: author: ftcmetrics version: "1.0.0" category: api

FTC Events API Integration

The FTC Events API provides official data for FIRST Tech Challenge competitions. FTC Metrics uses this to fetch events, teams, match schedules, scores, and rankings.

Quick Start

Prerequisites

1. Register for API credentials at https://ftc-events.firstinspires.org/services/API
2. Add credentials to .env:

   FTC_API_USERNAME=your_username
   FTC_API_TOKEN=your_token
   

Basic Usage

import { getFTCApi } from "@ftcmetrics/api/lib/ftc-api";

const api = getFTCApi();

// Get all events for current season
const { events } = await api.getEvents();

// Get teams at an event
const { teams } = await api.getEventTeams("USNCCRR");

// Get match scores
const { matchScores } = await api.getScores("USNCCRR", "qual");

API Reference

Tournament Levels

• "qual" - Qualification matches (default)
• "playoff" - Elimination matches

Response Types

FTCEvent

interface FTCEvent {
  eventCode: string;
  name: string;
  venue: string;
  city: string;
  stateProv: string;
  country: string;
  dateStart: string;
  dateEnd: string;
  type: string;
  timezone: string;
}

FTCMatchScore

interface FTCMatchScore {
  matchLevel: string;
  matchNumber: number;
  alliances: {
    alliance: "Red" | "Blue";
    totalPoints: number;
    autoPoints: number;
    dcPoints: number;
    endgamePoints: number;
    penaltyPointsCommitted: number;
    team1: number;
    team2: number;
  }[];
}

Authentication

The API uses HTTP Basic Auth with base64-encoded credentials:

private getAuthHeader(): string {
  const credentials = Buffer.from(`${username}:${token}`).toString("base64");
  return `Basic ${credentials}`;
}

Common Patterns

Fetch Event with All Data

async function getFullEventData(eventCode: string) {
  const api = getFTCApi();

  const [eventData, teams, schedule, scores, rankings] = await Promise.all([
    api.getEvent(eventCode),
    api.getEventTeams(eventCode),
    api.getSchedule(eventCode, "qual"),
    api.getScores(eventCode, "qual"),
    api.getRankings(eventCode),
  ]);

  return { eventData, teams, schedule, scores, rankings };
}

Handle Missing Scores

// Matches may not have scores yet (scheduled but not played)
const { matchScores } = await api.getScores(eventCode, "qual");

const completedMatches = matchScores.filter(
  (match) => match.alliances[0].totalPoints > 0
);

Anti-Patterns

• ❌ Hardcoding credentials in source code
• ❌ Not handling API errors (always check response.ok)
• ❌ Fetching all events when you only need one (use eventCode filter)
• ❌ Ignoring rate limits (add delays between bulk requests)

Common Errors

"FTC API credentials not configured"

Ensure FTC_API_USERNAME and FTC_API_TOKEN are set in your .env file.

401 Unauthorized

Credentials are invalid. Verify at https://ftc-events.firstinspires.org/services/API

404 Not Found

Event code doesn't exist or season is wrong. Current season is 2025 (DECODE).

Current Season

The API client is configured for the 2025 DECODE season:

const CURRENT_SEASON = 2025;

References

• FTC Events API Documentation
• Register for API Access
• API Implementation