🔭

Trackside API

Developer Documentation
🔭 Latest Race
Base URL
https://api.zkrace.ggroogle.au
Authentication
None required - Public API
Rate Limit
100 requests / minute
Response Format
CSV (text/csv)
🏁

Race Types

Champion Races
Goal: Finish fastest. Winner has the lowest time.
Filter: race=champion or race=best_time
Donkey Races
Goal: Finish slowest. Winner has the highest time.
Filter: race=donkey or race=worst_time
🛤️

Track Configuration

Surface
0 Dirt
1 Turf
2 Synthetic
Length
Values 2-15
Track distance in furlongs
Equipment
0 No horseshoes
1 With horseshoes
⚡

API Endpoints

GET /ancestry/v1 Ancestry Export (Legacy) ▶

Export all horse ancestry data. Same as /v5/csv/horse/ancestry.

Parameters
Name Type Required Description
limit int optional Max results
Example Request
/ancestry/v1
Returns
CSV with all horses and their lineage.
GET /csv/horse/averages/v2 Horse Averages v2 ▶

Get horse averages with global comparison.

Parameters
Name Type Required Description
horse int required Horse ID
race str optional Race type: champion or donkey
Example Request
/csv/horse/averages/v2?horse=3277
Returns
CSV with horse and global averages per track.
GET /csv/horse/tracks/v1 Horse Track Stats (Unified) ▶

Get horse track stats supporting both race types via query parameter.

Parameters
Name Type Required Description
horse int required Horse ID
race str optional Race type: champion or donkey
Example Request
/csv/horse/tracks/v1?horse=3277&race=donkey
Returns
CSV with track performance stats.
GET /csv/surface/champion/v1 Champion Surface Speeds ▶

Get global surface speed statistics for champion (fastest) races.

Parameters
Name Type Required Description
surface int optional Surface ID filter
length int optional Track length filter
equipment int optional Equipment filter
Example Request
/csv/surface/champion/v1
Returns
CSV with global speed stats and record holders per track.
GET /csv/surface/donkey/v1 Donkey Surface Speeds ▶

Get global surface speed statistics for donkey (slowest) races.

Parameters
Name Type Required Description
surface int optional Surface ID filter
length int optional Track length filter
equipment int optional Equipment filter
Example Request
/csv/surface/donkey/v1
Returns
CSV with global speed stats and record holders per track.
GET /health Health Check ▶

Health check endpoint for monitoring API status. Returns system health including: - API status and uptime - Database connectivity - Environment mode (PROD/DEV) - Recent race count for data freshness Returns: JSONResponse with health status and metrics

Example Request
/health
Returns
CSV file
GET /horse/results/v1 Horse Race Results (Legacy) ▶

Get individual race results for a specific horse.

Parameters
Name Type Required Description
horse int required Horse ID
surface int optional Surface ID (0=dirt, 1=turf, 2=synthetic)
length int optional Track length (2-15)
equipment int optional Equipment (0=none, 1=equipped)
race str optional Race type: champion or donkey
start int optional Start timestamp (ms)
end int optional End timestamp (ms)
limit int optional Max results
Example Request
/horse/results/v1?horse=3277
Returns
CSV with race details, placement, times, prizes, and profit.
GET /horse/tracks/champion/v1 Champion Track Stats ▶

Get champion race track stats for a horse.

Parameters
Name Type Required Description
horse int required Horse ID
Example Request
/horse/tracks/champion/v1?horse=3277
Returns
CSV with champion race performance per track.
GET /horse/tracks/donkey/v1 Donkey Track Stats ▶

Get donkey race track stats for a horse.

Parameters
Name Type Required Description
horse int required Horse ID
Example Request
/horse/tracks/donkey/v1?horse=3277
Returns
CSV with donkey race performance per track.
GET /horse/v1 Single Horse (Legacy) ▶

Get detailed information for a single horse.

Parameters
Name Type Required Description
horse int required Horse ID
Example Request
/horse/v1?horse=3277
Returns
CSV with complete horse details.
GET /json/race/results Get Json Race Results ▶

Get individual race results for a horse as JSON with pagination. URL: /json/race/results?horse={id}&limit=20&offset=0 Args: cxn: Database connection (injected) params: Query parameters including: - horse: Horse ID (required) - surface, equipment, length: Optional filters - limit: Results per page (default 20) - offset: Result offset for pagination (default 0) place: Place filter (wins, podiums, or all) Returns: JSON object with total count, pagination info, and results array

Example Request
/json/race/results
Returns
CSV file
GET /surface/topstats/v1 Get Surface Topstats V1 ▶

Get per-horse per-track stats for all horses on a given surface. URL: /surface/topstats/v1?surface={id}&race={best_time|worst_time} Args: background_tasks: FastAPI background tasks for cleanup cxn: Database connection (injected) params: Query parameters including: - surface: Surface ID (required) - equipment: Equipment filter - gen: Generation filter - starts: Minimum starts filter - race: Race type - "best_time" (default) or "worst_time" Returns: FileResponse: CSV with per-horse per-track stats

Example Request
/surface/topstats/v1
Returns
CSV file
GET /surface/tracks/champion/v1 Get Legacy Champion Surface Tracks ▶

Legacy alias for /csv/surface/champion/v1.

Example Request
/surface/tracks/champion/v1
Returns
CSV file
GET /surface/tracks/donkey/v1 Get Legacy Donkey Surface Tracks ▶

Legacy alias for /csv/surface/donkey/v1.

Example Request
/surface/tracks/donkey/v1
Returns
CSV file
GET /trackside/horse/{horse_id} Horse Detail ▶

Horse detail page showing complete profile and statistics. Displays horse info, career stats, financials, reactions, track statistics for both Champion and Donkey races, lineage (parents and children), and external links.

Example Request
/trackside/horse/{horse_id}
Returns
CSV file
GET /trackside/leaderboard Leaderboard ▶

Traditional racecourse-style leaderboard showing track records. Displays fastest times for Champion races and slowest times for Donkey races, organized by surface type with toggles for race type and equipment.

Example Request
/trackside/leaderboard
Returns
CSV file
GET /trackside/stable/{wallet_id} Stable Page ▶

Stable page showing all horses owned by a wallet address. Displays aggregated stable statistics, tier distribution, and individual horse summaries with links to horse detail pages.

Example Request
/trackside/stable/{wallet_id}
Returns
CSV file
GET /v1/csv/stats/averages/{horse_id} Horse Averages ▶

Get average speed statistics for a horse across surfaces and lengths.

Parameters
Name Type Required Description
horse_id int required Horse ID (in URL path)
surface int optional Surface ID filter
length int optional Track length filter
equipment int optional Equipment filter
Example Request
/v1/csv/stats/averages/3277
Returns
CSV with horse averages and global averages for comparison.
GET /v5/csv/horse Horse Details ▶

Get lifetime summary statistics for a single horse.

Parameters
Name Type Required Description
horse int required Horse ID
Example Request
/v5/csv/horse?horse=3277
Returns
CSV with horse info, race stats, reaction times, and financials.
GET /v5/csv/horse/ancestry All Horses Ancestry ▶

Get ancestry data for all horses in the database.

Parameters
Name Type Required Description
limit int optional Max results (default: 50000)
Example Request
/v5/csv/horse/ancestry?limit=1000
Returns
CSV with horse_id, name, generation, tier, gender, breed, starts, parents, wallet.
GET /v5/csv/horse/track/stats Horse Track Stats ▶

Get per-track statistics for a horse in champion or donkey races.

Parameters
Name Type Required Description
horse int required Horse ID
race str optional Race type: champion (default) or donkey
surface int optional Surface ID
length int optional Track length
equipment int optional Equipment flag
Example Request
/v5/csv/horse/track/stats?horse=1443&race=champion
Returns
CSV with per-track performance including times and global averages.
GET /v5/csv/race/results Race Results ▶

Get individual race results for a specific horse.

Parameters
Name Type Required Description
horse int required Horse ID
surface int optional Surface ID (0=dirt, 1=turf, 2=synthetic)
length int optional Track length (2-15)
equipment int optional Equipment (0=none, 1=equipped)
race str optional Race type: champion or donkey
start int optional Start timestamp (ms)
end int optional End timestamp (ms)
limit int optional Max results
Example Request
/v5/csv/race/results?horse=3277&surface=0
Returns
CSV with race details, placement, times, prizes, and profit.