Building a course picker
Fetch once, cache indefinitely. Sorting by races puts the tracks a user actually wants at the top without you hardcoding a list.
Documentation / Reference & coverage
Courses
GET
/v1/courses
Every course, with first and last meeting and how many races we hold.
Available on
Free key
24h – 7d
Live
today + 3 days
Archive
back to 2017
Complete
2017 → upcoming
Complete + Analyst
2017 → upcoming
Send your key in the X-API-Key header, or as
?key= if your tool cannot set one. A date outside your plan's window returns
403 outside_window naming the window, never an empty array.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| region | query | string | no | Restrict to one jurisdiction, e.g. GB. Values come from /v1/countries. |
| country | query | string | no | Restrict to one source country code, which is finer than region: Scot and Wale both roll up to GB. |
Request
curl https://api.apihorseracing.com/v1/courses \ -H "X-API-Key: $AHR_KEY"
$ch = curl_init('https://api.apihorseracing.com/v1/courses'); curl_setopt_array($ch, [ CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => ['X-API-Key: ' . getenv('AHR_KEY')], ]); $data = json_decode(curl_exec($ch), true)['data'];
const res = await fetch( 'https://api.apihorseracing.com/v1/courses', { headers: { 'X-API-Key': process.env.AHR_KEY } } ); const { meta, data } = await res.json();
import os, requests r = requests.get( "https://api.apihorseracing.com/v1/courses", headers={"X-API-Key": os.environ["AHR_KEY"]}, ).json()
curl https://api.apihorseracing.com/v1/courses?key=$AHR_KEY
$url = 'https://api.apihorseracing.com/v1/courses' . '?key=$AHR_KEY'; $data = json_decode(file_get_contents($url), true)['data'];
const res = await fetch( 'https://api.apihorseracing.com/v1/courses?key=$AHR_KEY' ); const { meta, data } = await res.json();
import os, requests r = requests.get( "https://api.apihorseracing.com/v1/courses?key=$AHR_KEY", ).json()
Response
200 OK
application/json
harvested 8 days ago
{ "meta": { "request_id": "27eb8b250d0a531e", "data_as_of": "2026-09-12T05:10:27+00:00", "plan": "analyst", "window": "2017 → upcoming", "count": 339 }, "data": [ { "course_id": "cr_2F843RM", "name": "Gulfstream", "shortcode": null, "country": "USA", "region": "USA", "races": 19223, "meetings": 1891, "first_meeting": "2017-01-01", "last_meeting": "2026-09-06" }, { "course_id": "cr_27P04G6", "name": "Charles Town", "shortcode": null, "country": "USA", "region": "USA", "races": 11668, "meetings": 1429, "first_meeting": "2017-01-12", "last_meeting": "2026-08-30" }, "… 337 more" ] }
A real response from /v1/courses?limit=3,
captured by calling the live API rather than written by hand.
Response fields
Each field is described once and rendered on every endpoint that returns it, so the wording cannot drift between pages.
| Field | Type | What it is |
|---|---|---|
| course_id | string | Opaque course identifier. |
| name | string | Race title as published, sponsor and all. |
| country | string | Country code as the source publishes it. |
| region | string | Jurisdiction, normalised. Welsh and Scottish racing is GB. |
Errors this endpoint returns
| Code | Status | When |
|---|---|---|
| unauthorized | 401 | No key, or one we do not recognise. Check the header name and that the key has not been rotated from your account page. |
| invalid_param | 422 | A date that is not YYYY-MM-DD, a by= dimension we do not have, or a cursor that did not come from us. The message names the parameter. |
| rate_limited | 429 | Past your per-minute rate. Retry-After is set, and X-RateLimit-Remaining tells you where you stand on every successful response too. |
| server_error | 500 | Ours, not yours. Every response carries a request_id; quote it and we can find the exact request. |
Run it live
A real request from your browser straight to
api.apihorseracing.com with
your own key. Nothing is proxied and nothing is logged by this page.
Remembered in this browser so you do not paste it on every page. Forget it
What this is for
Every course in the archive, ordered by how many of its races we hold, with the span of dates covered. Courses are the one entity you will almost certainly cache, because there are a few hundred of them and they do not change.
Common uses
Finding what is worth analysing
A course with two hundred races will not support a draw bias study. The races count tells you before you run the query.