ftc8569/ftc-events-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

| Method | Description | |--------|-------------| | getEvents() | List all events for current season | | getEvent(code) | Get specific event details | | getEventTeams(code) | Get teams registered at event | | getTeam(number) | Get team info by number | | getSchedule(code, level) | Get match schedule | | getMatches(code, level) | Get match results | | getScores(code, level) | Get detailed match scores | | getRankings(code) | Get team rankings at event | | getTeamEvents(number) | Get events a team is registered for |

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