--- title: "Trainer premiership leaderboards and lookup" method: GET path: "/v1/racing/trainers/stats" tags: ["Racing"] --- # Trainer premiership leaderboards and lookup `GET /v1/racing/trainers/stats` ## Request - Base URL: `https://api.puntersedge.online` - URL: `https://api.puntersedge.online/v1/racing/trainers/stats` - Auth: API key in header `X-API-Key` Cost: 2 credits. Trainer premiership leaderboards — 1st-5th finishes, prize money, strike rate and starts — from Racing Australia's own published tables. WHAT A LEADERBOARD IS. RA publishes each premiership as a TOP-20 table, one per state and scope, and that is exactly what is held: the national table (`state=AUS`) and the eight state tables, each split all/metro/provincial/country/picnic, for the running season and the previous one (RA seasons run 1 Aug - 31 Jul). There is no page two at the source, so a trainer outside every top-20 has no row here — an empty `rows` for a name means "outside the published top 20", never "inactive". For per-horse trainer identity on individual runs, /v1/racing/horses/form carries it with a stable code on every run. LOOKUP SHAPES. With no `name`, the response is one table: `state` (default AUS) x `scope` (default all) for the chosen `season`. With `name`, the search widens to every state and scope for that season by default — a rider prominent only in one state's country scope is found without knowing which — and `state`/`scope`, if given, narrow it back. Name matching is case-insensitive on the whole name or any part of it. JOINS. `ra_code` is the code inside RA's own engagement links, stored with padding stripped — the same identity namespace as `jockey_code` on horse-form runs and `trainer_code` on acceptance rows, so premiership standing joins to per-run data on code, not name spelling. HOW FRESH ANY GIVEN TABLE IS. There are 180 of these tables and Racing Australia will not serve them all in one sitting, so they are refreshed in paced passes overnight Australian time: the national tables (`state=AUS`) daily, and the state tables on a rolling refresh that takes a few nights to come round. Nothing is guessed or interpolated in between — a table is exactly as RA last published it. Read the age off the response rather than assuming it: `period_to` on the running season is the day RA rendered that table, so it dates every row, and `source.scraped_at` gives the newest scrape among the rows returned. A state table added to the store for the first time simply appears; until then its `rows` are empty, the same shape as a name that is outside every top 20. `season=previous` serves the completed season, useful as the longer baseline of the two. It changes only on a late protest, so it is refreshed about weekly. Cached 1 hour. ## Query parameters - `name` string, nullable: Find one trainer by (partial) name across every state and scope. - `state` string, nullable: AUS (national) or a state. Default AUS, unless `name` widens the search. - `scope` string, nullable: all, metro, provincial, country, picnic. Default all, unless `name` widens the search. - `season` string: current or previous RA season (1 Aug - 31 Jul). ## Headers - `X-API-Key` string - `X-RapidAPI-Proxy-Secret` string ## Response `200` Successful Response - PremiershipOut - `role` string, required - `season_start_year` integer, nullable - `state` string, nullable: Echo of the filter; null when a name search crossed all states. - `scope` string, nullable - `name` string, nullable - `rows` PremiershipRow[] - `state` string, required: AUS is the national table — RA's own combined leaderboard, not a sum of the state rows. - `scope` string, required: RA's split: all, metro, provincial, country or picnic. - `rank` integer, required: Position in RA's table, 1-20. - `name` string, required - `ra_code` string, nullable: RA's stable code from the row's engagement link — the same namespace as trainer_code on acceptance data and jockey_code on /v1/racing/horses/form runs, so rows join on identity, not name spelling. - `firsts` number, nullable: Wins. REAL, not int: dead heats appear as halves in some tables (RA prints 23½). - `seconds` number, nullable - `thirds` number, nullable - `fourths` number, nullable - `fifths` number, nullable - `prize_money` number, nullable: Season prize money, AUD. - `strike_rate` number, nullable: RA's own figure, percent. - `starts` integer, nullable - `period_from` string, nullable: Start of the window this row measures (RA seasons run 1 Aug to 31 Jul). - `period_to` string, nullable: End of the measured window. On the running season this is the day RA rendered the table, which makes it the per-row freshness stamp: rows from a table scraped two nights ago carry that day, not today. - `source` PremiershipSource, required - `feed` string - `region` string - `sport` string - `scraped_at` string, nullable: UTC time of the newest row served in this response. For the usual single-table lookup (a `state` + `scope`) every row comes from one scrape, so this IS that table's age. A `name` search spans tables scraped on different nights, so there read it as the freshest of them and use `period_to` for the age of each individual row. - `top_n` integer: RA publishes each premiership as a top-20 table. Absence from `rows` means outside the top 20, never inactivity. ## Other responses - `401`: Missing or invalid API key. Send `X-API-Key`. See https://puntersedge.online/developers/errors - `402`: Monthly credit allowance exhausted for this plan. Upgrade at https://puntersedge.online/api/pricing - `422`: Validation Error - `429`: Rate limit exceeded for this plan. Honour the `Retry-After` header (seconds) before retrying. See https://puntersedge.online/developers/rate-limits - `500`: Unexpected server error. Safe to retry with backoff. --- [API](https://skmtc.dev/puntersedge/apis/puntersedge-odds-api.md) · [All operations](https://skmtc.dev/puntersedge/apis/puntersedge-odds-api/llms.txt) · [OpenAPI document](https://skmtc.dev/puntersedge/apis/puntersedge-odds-api/revisions/f35b6aab1946?raw)