MotoGP API Documentation

GET /api/v1/health

Check the health status of the API and database connectivity.

{
  "status": "healthy",
  "timestamp": "2026-01-21T15:30:00.000Z",
  "checks": {
    "database": true,
    "last_fetch": {
      "type": "calendar",
      "status": "success",
      "at": "2026-01-21T14:30:00.000Z"
    }
  }
}

GET /api/v1/races

Retrieve all races for a specific season with their sessions.

Query Parameters

Name	Type	Default	Description
season	integer	current year	The championship season
category	string	MotoGP	Filter sessions by category (MotoGP, Moto2, Moto3, or "all")

Cache: 6 hours (dynamic)

{
  "data": [
    {
      "id": 1,
      "name": "Grand Prix of Qatar",
      "circuit": "Lusail Circuit",
      "country": "Qatar",
      "country_code": "QA",
      "start_date": "2026-03-08",
      "end_date": "2026-03-10",
      "round_number": 1,
      "season": 2026,
      "status": "scheduled",
      "is_upcoming": true,
      "is_in_progress": false,
      "sessions": [...]
    }
  ],
  "meta": {
    "season": 2026,
    "category": "MotoGP",
    "total": 20,
    "cached_at": "2026-01-21T15:30:00.000Z"
  }
}

GET /api/v1/races/next

Retrieve the next upcoming race with its sessions.

Query Parameters

Name	Type	Default	Description
category	string	MotoGP	Filter sessions by category (MotoGP, Moto2, Moto3, or "all")

Cache: 1-24 hours (dynamic based on race proximity)

{
  "data": {
    "id": 1,
    "name": "Grand Prix of Qatar",
    "circuit": "Lusail Circuit",
    "country": "Qatar",
    "start_date": "2026-03-08",
    "end_date": "2026-03-10",
    "sessions": [...]
  },
  "meta": {
    "category": "MotoGP",
    "cached_at": "2026-01-21T15:30:00.000Z"
  }
}

GET /api/v1/standings/riders

Retrieve the rider championship standings for a specific category and season.

Query Parameters

Name	Type	Default	Description
season	integer	current year	The championship season
category	string	MotoGP	Motorcycle category (MotoGP, Moto2, Moto3)
limit	integer	20	Maximum riders to return (max: 50)

Cache: 2-12 hours (dynamic)

{
  "data": [
    {
      "position": 1,
      "rider": {
        "name": "Marc Marquez",
        "number": 93,
        "nationality": "Spain",
        "nationality_code": "ESP"
      },
      "team": "Gresini Racing",
      "constructor": "Ducati",
      "points": 250,
      "wins": 8,
      "podiums": 12,
      "sprint_wins": 6,
      "sprint_podiums": 10
    }
  ],
  "meta": {
    "season": 2026,
    "category": "MotoGP",
    "total": 20
  }
}

GET /api/v1/meta

Retrieve API metadata, available data, and freshness information.

Cache: 1 hour

{
  "data": {
    "api_version": "v1",
    "current_season": 2026,
    "available_seasons": [2023, 2024, 2025, 2026],
    "available_categories": ["MotoGP", "Moto2", "Moto3"],
    "data_freshness": {
      "calendar": {
        "updated_at": "2026-01-21T14:30:00.000Z",
        "records": 20
      }
    },
    "stats": {
      "total_races": 20,
      "completed_races": 0,
      "total_riders": 24
    }
  }
}

All API responses follow a consistent structure:

// Success Response
{
  "data": { ... },
  "meta": { ... }
}

// Error Response
{
  "data": null,
  "message": "Error description"
}

The API implements intelligent caching with dynamic TTLs based on racing calendar proximity:

Context	Description	Cache Duration
Off-season	No races scheduled	12-24 hours
Normal	7+ days to next race	6-8 hours
Race week	1-7 days to next race	2-4 hours
Race day	Race happening today	1-2 hours

MotoGP API

Endpoints

Response Structure

Caching Strategy