motogp-api
Version:
A TypeScript API wrapper for MotoGP data
385 lines (384 loc) • 16 kB
TypeScript
import type { ClientOptions, Season, Category } from '../types/common.js';
import type { LiveTimingResponse, Event, Session, ClassificationResponse, EntryResponse, GridPosition, StandingsResponse, StandingsFilesResponse, BMWAwardResponse } from '../types/results.js';
import type { BroadcastEvent, BroadcastRider, RiderStatistics, SeasonStatistics, BroadcastTeam } from '../types/broadcast.js';
/**
* MotoGP API Client
*
* A TypeScript client for the official MotoGP API, providing access to both Results API and Broadcast API endpoints.
* Uses undici for high-performance HTTP requests with full TypeScript support.
*
* @example
* ```typescript
* const client = new MotoGPClient();
* const riders = await client.getRiders();
* const seasons = await client.getSeasons();
* ```
*/
export declare class MotoGPClient {
private readonly baseURL;
private readonly timeout;
private readonly userAgent;
/**
* Creates a new MotoGP API client instance
*
* @param options - Configuration options for the client
* @param options.baseURL - Base URL for the API (default: https://api.motogp.pulselive.com/motogp/v1/)
* @param options.timeout - Request timeout in milliseconds (default: 10000)
* @param options.userAgent - Custom User-Agent string (default: Chrome browser)
*
* @example
* ```typescript
* const client = new MotoGPClient({
* timeout: 15000,
* userAgent: 'MyApp/1.0.0'
* });
* ```
*/
constructor(options?: ClientOptions);
/**
* Makes an HTTP GET request to the API
*
* @template T - The expected response type
* @param endpoint - The API endpoint path (relative to baseURL)
* @param searchParams - Optional query parameters to append to the URL
* @returns Promise that resolves to the API response data
* @throws {APIError} When the request fails or returns non-200 status
*
* @private
*/
private makeRequest;
/**
* Retrieves live timing data during active sessions
*
* @returns Promise that resolves to live timing data including session info and rider positions
* @throws {APIError} When no live session is active or request fails
*
* @example
* ```typescript
* const liveTiming = await client.getLiveTiming();
* console.log('Current session:', liveTiming.head.session_name);
* Object.values(liveTiming.rider).forEach(rider => {
* console.log(`${rider.pos}. ${rider.rider_name} ${rider.rider_surname} - ${rider.lap_time}`);
* });
* ```
*/
getLiveTiming(): Promise<LiveTimingResponse>;
/**
* Retrieves all available MotoGP seasons
*
* @returns Promise that resolves to an array of season objects
* @throws {APIError} When the request fails
*
* @example
* ```typescript
* const seasons = await client.getSeasons();
* const currentSeason = seasons.find(s => s.current);
* console.log('Current season:', currentSeason?.year);
* ```
*/
getSeasons(): Promise<Season[]>;
/**
* Retrieves all categories for a specific season
*
* @param seasonYear - The season year e.g. "SeasonUUID"
* @returns Promise that resolves to an array of category objects (MotoGP, Moto2, Moto3, MotoE)
* @throws {APIError} When the season year is invalid or request fails
*
* @example
* ```typescript
* const categories = await client.getCategories("SeasonUUID");
* const motoGP = categories.find(c => c.name === 'MotoGP');
* console.log('MotoGP category ID:', motoGP?.id);
* ```
*/
getCategories(seasonUuid: string): Promise<Category[]>;
/**
* Retrieves events for a specific season
*
* @param seasonUuid - The unique identifier of the season
* @returns Promise that resolves to an array of event objects
* @throws {APIError} When the season is not found or request fails
*
* @example
* ```typescript
* const events = await client.getEvents('season-uuid-here');
* console.log(`Found ${events.length} events in the season`);
* ```
*/
getEvents(seasonUuid: string): Promise<Event[]>;
/**
* Retrieves a specific event by ID
*
* @param eventId - The unique identifier of the event
* @returns Promise that resolves to the event object
* @throws {APIError} When the event is not found or request fails
*
* @example
* ```typescript
* const event = await client.getEvent('event-id-here');
* console.log('Event:', event.name);
* ```
*/
getEvent(eventId: string): Promise<Event>;
/**
* Retrieves sessions for a specific event and category
*
* @param eventUuid - The unique identifier of the event
* @param categoryUuid - The unique identifier of the category (e.g., MotoGP, Moto2, Moto3)
* @returns Promise that resolves to an array of session objects
* @throws {APIError} When the event/category is not found or request fails
*
* @example
* ```typescript
* const sessions = await client.getSessions('event-uuid', 'motogp-category-uuid');
* const raceSession = sessions.find(s => s.type.toLowerCase().includes('race'));
* ```
*/
getSessions(eventUuid: string, categoryUuid: string): Promise<Session[]>;
/**
* Retrieves a specific session by ID
*
* @param sessionId - The unique identifier of the session
* @returns Promise that resolves to the session object
* @throws {APIError} When the session is not found or request fails
*
* @example
* ```typescript
* const session = await client.getSession('session-id-here');
* console.log('Session:', session.type, session.status);
* ```
*/
getSession(sessionId: string): Promise<Session>;
/**
* Retrieves the classification (results) for a specific session
*
* @param sessionId - The unique identifier of the session
* @param seasonYear - Optional season year for disambiguation (e.g., "UUID")
* @param isTest - Optional flag indicating if this is a test session
* @returns Promise that resolves to the classification data
* @throws {APIError} When the session is not found or request fails
*
* @example
* ```typescript
* const classification = await client.getClassification('session-id', 'SeasonUUID');
* classification.classification.forEach((entry, index) => {
* console.log(`${index + 1}. ${entry.rider.name} ${entry.rider.surname} - ${entry.points} points`);
* });
* ```
*/
getClassification(sessionId: string, seasonYear?: string, isTest?: boolean): Promise<ClassificationResponse>;
/**
* Retrieves the entry list (participating riders) for an event
*
* @param eventId - The unique identifier of the event
* @param categoryUuid - The unique identifier of the category
* @returns Promise that resolves to the entry list with rider data and PDF file link
* @throws {APIError} When the event/category is not found or request fails
*
* @example
* ```typescript
* const entryList = await client.getEntryList('event-id', 'category-uuid');
* console.log(`${entryList.entry.length} riders participating`);
* console.log('Official entry list PDF:', entryList.file);
* ```
*/
getEntryList(eventId: string, categoryUuid: string): Promise<EntryResponse>;
/**
* Retrieves grid positions for a specific event and category
*
* @param eventId - The unique identifier of the event
* @param categoryId - The unique identifier of the category
* @returns Promise that resolves to an array of grid position objects
* @throws {APIError} When the event/category is not found or request fails
*
* @example
* ```typescript
* const gridPositions = await client.getGridPositions('event-id', 'category-id');
* gridPositions.forEach(pos => {
* console.log(`Position ${pos.position}: ${pos.rider.name} ${pos.rider.surname} - ${pos.qualifying_time}`);
* });
* ```
*/
getGridPositions(eventId: string, categoryId: string): Promise<GridPosition[]>;
/**
* Retrieves rider standings for a specific season and category
*
* @param seasonUuid - The unique identifier of the season
* @param categoryUuid - The unique identifier of the category
* @returns Promise that resolves to the standings data with points and file links
* @throws {APIError} When the season/category is not found or request fails
*
* @example
* ```typescript
* const standings = await client.getStandings('season-uuid', 'motogp-category-uuid');
* standings.classification.forEach((rider, index) => {
* console.log(`${index + 1}. Rider ${rider.id} - ${rider.points} points`);
* });
* ```
*/
getStandings(seasonUuid: string, categoryUuid: string): Promise<StandingsResponse>;
/**
* Retrieves official files related to standings (PDFs, statistics)
*
* @param seasonUuid - The unique identifier of the season
* @param categoryUuid - The unique identifier of the category
* @returns Promise that resolves to file URLs for various standings documents
* @throws {APIError} When the season/category is not found or request fails
*
* @example
* ```typescript
* const files = await client.getStandingsFiles('season-uuid', 'category-uuid');
* console.log('Podiums PDF:', files.riders_results.podiums);
* console.log('Pole positions PDF:', files.riders_results.pole_positions);
* ```
*/
getStandingsFiles(seasonUuid: string, categoryUuid: string): Promise<StandingsFilesResponse>;
/**
* Retrieves qualifying standings (BMW Award) for a season
*
* @param seasonUuid - The unique identifier of the season
* @returns Promise that resolves to BMW Award standings data
* @throws {APIError} When the season is not found or request fails
*
* @example
* ```typescript
* const bmwAward = await client.getBMWAward('season-uuid');
* console.log('BMW Award standings:', bmwAward.classification.length, 'riders');
* ```
*/
getBMWAward(seasonUuid: string): Promise<BMWAwardResponse>;
/**
* Retrieves all categories for a specific season
*
* @param seasonYear - The season year e.g. "SeasonUUID"
* @returns Promise that resolves to an array of category objects (MotoGP, Moto2, Moto3, MotoE)
* @throws {APIError} When the season year is invalid or request fails
*
* @example
* ```typescript
* const categories = await client.getCategories("SeasonUUID");
* const motoGP = categories.find(c => c.name === 'MotoGP');
* console.log('MotoGP category ID:', motoGP?.id);
* ```
*/
getBroadcastCategories(seasonUuid: string): Promise<Category[]>;
/**
* Retrieves broadcast events for a specific season
*
* @param seasonYear - The season year (e.g., "SeasonUUID")
* @returns Promise that resolves to an array of broadcast event objects
* @throws {APIError} When the season year is invalid or request fails
*
* @example
* ```typescript
* const events = await client.getBroadcastEvents("SeasonUUID");
* const upcomingEvents = events.filter(e => new Date(e.date_start) > new Date());
* console.log(`${upcomingEvents.length} upcoming events`);
* ```
*/
getBroadcastEvents(seasonYear: string): Promise<BroadcastEvent[]>;
/**
* Retrieves a specific broadcast event by ID
*
* @param eventId - The unique identifier of the broadcast event
* @returns Promise that resolves to the broadcast event object with full details
* @throws {APIError} When the event is not found or request fails
*
* @example
* ```typescript
* const event = await client.getBroadcastEvent('event-id-here');
* console.log('Event:', event.name);
* console.log('Circuit:', event.circuit.name);
* console.log('Broadcasts:', event.broadcasts.length);
* ```
*/
getBroadcastEvent(eventId: string): Promise<BroadcastEvent>;
/**
* Retrieves all riders from the current season across all categories
*
* @returns Promise that resolves to an array of rider objects with career information
* @throws {APIError} When the request fails
*
* @example
* ```typescript
* const riders = await client.getRiders();
* const motoGPRiders = riders.filter(r => r.current_career_step.category.name === 'MotoGP');
* motoGPRiders.forEach(rider => {
* console.log(`#${rider.current_career_step.number} ${rider.name} ${rider.surname} - ${rider.current_career_step.team.name}`);
* });
* ```
*/
getRiders(): Promise<BroadcastRider[]>;
/**
* Retrieves detailed information for a specific rider
*
* @param riderId - The unique identifier of the rider
* @returns Promise that resolves to the rider object with full career history and details
* @throws {APIError} When the rider is not found or request fails
*
* @example
* ```typescript
* const rider = await client.getRider('rider-uuid-here');
* console.log(`${rider.name} ${rider.surname}`);
* console.log('Country:', rider.country.name);
* console.log('Career steps:', rider.career?.length);
* ```
*/
getRider(riderId: string): Promise<BroadcastRider>;
/**
* Retrieves comprehensive statistics for a rider across their entire career
*
* @param legacyId - The legacy ID of the rider (numeric identifier)
* @returns Promise that resolves to detailed rider statistics including wins, podiums, poles, etc.
* @throws {APIError} When the rider is not found or request fails
*
* @example
* ```typescript
* const stats = await client.getRiderStatistics(7646); // Example: Brad Binder
* console.log(`Total victories: ${stats.grand_prix_victories.total}`);
* console.log(`Total podiums: ${stats.podiums.total}`);
* console.log(`Total pole positions: ${stats.poles.total}`);
* ```
*/
getRiderStatistics(legacyId: number): Promise<RiderStatistics>;
/**
* Retrieves rider statistics summarized by season
*
* @param legacyId - The legacy ID of the rider (numeric identifier)
* @returns Promise that resolves to an array of season statistics
* @throws {APIError} When the rider is not found or request fails
*
* @example
* ```typescript
* const seasonStats = await client.getRiderSeasonStatistics(7646);
* seasonStats.forEach(season => {
* console.log(`${season.season}: ${season.points} points, Position ${season.position}`);
* });
* ```
*/
getRiderSeasonStatistics(legacyId: number): Promise<SeasonStatistics[]>;
/**
* Retrieves teams for a specific category and season
*
* Note: This is the only known way to get riders from all seasons, as the getRiders()
* endpoint only returns riders from the current season.
*
* @param categoryUuid - The unique identifier of the category (use CATEGORY_IDS constants)
* @param seasonYear - The season year (e.g., "SeasonUUID")
* @returns Promise that resolves to an array of team objects with their riders
* @throws {APIError} When the category/season is not found or request fails
*
* @example
* ```typescript
* import { CATEGORY_IDS } from 'motogp-api';
* const teams = await client.getTeams(CATEGORY_IDS.MOTOGP, "SeasonUUID");
* teams.forEach(team => {
* console.log(`${team.name} (${team.constructor.name})`);
* team.riders.forEach(rider => {
* console.log(` - #${rider.current_career_step.number} ${rider.name} ${rider.surname}`);
* });
* });
* ```
*/
getTeams(categoryUuid: string, seasonYear: string): Promise<BroadcastTeam[]>;
}