MotoGP API (Unofficial) — FastAPI + Swagger on Vercel

An attempt at documenting the "hidden" API of Motogp.com. Not affiliated with MotoGP or Dorna in any capacity.

This repository wraps that API in FastAPI, with automatically generated Swagger UI documentation, deployed on Vercel.

⚠️ Not affiliated with Dorna Sports / MotoGP. For educational purposes. Endpoints were reverse-engineered by third parties; they are not officially documented or guaranteed stable by Dorna.

Why Vercel (and not GitHub Pages)

Vercel actually runs the FastAPI app as a serverless function (Python runtime, zero-config detection: just an app instance in app/main.py). Unlike GitHub Pages — which only serves static files — on Vercel you get:

• /docs — live Swagger UI, with "Try it out" that actually works (requests go to the real backend, on the same domain: no CORS issues).
• /redoc — alternative documentation in ReDoc style.
• /openapi.json — OpenAPI schema generated on the fly.
• All 32 endpoints are actually callable, not just documented.

Endpoint coverage

Every endpoint from the original API reference (README used as the source spec) is implemented and exposed in the Swagger UI — 32 out of 32. Endpoints that operate on the same underlying resource but were listed as separate sections in the source doc (e.g. "Season's Categories" and "Event's Categories") are merged into a single parametric endpoint here, matching how the upstream API actually works.

Every query/path parameter across all 32 endpoints has a real, working example value pre-filled in Swagger UI (real season, event, session, circuit and rider UUIDs), so "Try it out" returns actual data on the first click instead of failing on a placeholder.

Four additional endpoints were listed in the source doc under "Endpoints to investigate further" (undocumented/unconfirmed, discovered by observation rather than verified as stable):

• /content/motogp/playlist/{language}/{id}
• /content/motogp/video/{language}/{id}
• /content/motogp/promo/{language}/?tagNames=premium
• /motogp/v1/video-gateway/live/v2/mgp/prod/on-air

These are not implemented here, since they weren't part of the confirmed/stable endpoint list. Feel free to add them following the same pattern as the existing routers in app/routers/ if you need them.

What's included

• app/main.py — FastAPI instance, metadata, CORS, router inclusion, redirect from / to /docs.
• app/client.py — shared async HTTP client (proxy towards the upstream MotoGP API), with upstream error handling.
• app/config.py — base URL and request timeout.
• app/routers/ — 6 routers, one per section of the original API reference: content.py, broadcasting.py, gateways.py, results_v1.py, results_v2.py, core.py.
• vercel.json — function configuration (max duration).
• .python-version — pins Python 3.12 for the Vercel build.

Deploying to Vercel

Option A — from Git (recommended)

1. Push the project to GitHub (or GitLab/Bitbucket):

   git init
   git add .
   git commit -m "Initial commit: MotoGP API FastAPI"
   git branch -M main
   git remote add origin https://github.com/<your-username>/<your-repo>.git
   git push -u origin main
   

2. Go to vercel.com, Add New → Project, and import the repository.

3. Under "Framework Preset" leave Other (FastAPI isn't in the preset list, but Vercel detects it anyway via app/main.py).

4. Root Directory: leave it empty (the project is already at the root).

5. Click Deploy. After the build, the app will be live at https://<project-name>.vercel.app, with the documentation already available at https://<project-name>.vercel.app/docs.

Every push to main triggers a production deployment; every Pull Request automatically gets its own preview deployment with its own dedicated Swagger UI.

Option B — from the CLI

npm install -g vercel   # requires Node.js
vercel login
vercel                  # preview deployment
vercel --prod           # production deployment

Local development

With the Vercel CLI (simulates the serverless environment):

python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
vercel dev

Or with plain Uvicorn (faster for iterating on the code):

uvicorn app.main:app --reload

The app can also be run directly as a script (python3 app/main.py or, from inside app/, python3 main.py) — a small sys.path fix at the top of app/main.py makes this work without ModuleNotFoundError.

Then open:

• Swagger UI: http://127.0.0.1:8000/docs (or the port shown by vercel dev)
• ReDoc: http://127.0.0.1:8000/redoc
• OpenAPI schema: http://127.0.0.1:8000/openapi.json

Project structure

motogp-api/
├── app/
│   ├── main.py                # FastAPI app, metadata, routers, "/" → "/docs" redirect
│   ├── client.py               # Shared HTTP client (proxy to upstream)
│   ├── config.py                # Base URL and timeout
│   └── routers/
│       ├── content.py           # Content API (/content) — 2 endpoints
│       ├── broadcasting.py      # Broadcasting API (/broadcasting) — 1 endpoint
│       ├── gateways.py          # Gateways API (/motogp/v1/*-gateway) — 2 endpoints
│       ├── results_v1.py        # Results API v1 (/motogp/v1/results) — 14 endpoints
│       ├── results_v2.py        # Results API v2 (/motogp/v2/results) — 4 endpoints
│       └── core.py              # Core API v1 (/motogp/v1/) — 9 endpoints
├── vercel.json                  # Function config (maxDuration)
├── .python-version               # Python 3.12
├── .vercelignore
├── requirements.txt
└── README.md

Notes on timeouts and limits (Vercel free tier)

• vercel.json sets maxDuration: 30 seconds for the function: if the upstream MotoGP API responds slowly, the request may still fail with a timeout — you can increase this value according to your plan's limits.
• Python functions on Vercel run on Fluid compute: the instance may be reused across nearby requests (so the shared HTTP client in app/client.py gets reused), but it can also be recreated from scratch (cold start) if it hasn't received traffic for a while.

Notes on the upstream API

The MotoGP API (https://api.motogp.pulselive.com) is not officially public/documented by Dorna: it has been observed/reverse-engineered, and is also used by several independent third-party tools and libraries. Endpoints, parameters, and response structures may change without notice. This wrapper only acts as a proxy/documentation layer: the responses are whatever the real API returns, with no stability guarantees.

All example values used throughout this project (season, event, session, circuit and rider UUIDs) come from real, previously verified API calls, so that every endpoint in Swagger UI is immediately testable without having to hunt down valid IDs first.