What you need before the first call
RacingAPI.net is a read-only HTTP API for UK and Irish horse racing. Every racing endpoint is a GET under /v1, authenticated with a key that belongs to your account. You can create keys as soon as you sign up, but live racing data only answers once your account has an active subscription, a confirmed trial or an administrator approval. Signing up alone does not start a trial: the seven-day trial begins after the secure on-site checkout.
- Create an account and choose a plan under Dashboard, then Subscriptions. Plan prices, monthly allowances and per-second limits are listed on Pricing.
- Open Dashboard, then API keys, and create a key. The plaintext key is shown once only. Copy it straight into a password manager or your server secret store.
- Set it as an environment variable called
RACINGAPI_KEYon the machine or platform that will call the API. Never paste it into front-end code.
Choose the code tab for your server language; you do not need to run every version. Save Node examples as .mjs files and run them with Node 18 or newer, which includes fetch and supports the top-level await used here. Python examples require Python 3.9 or newer and requests (python -m pip install requests). PHP examples use PHP 8 or newer with cURL enabled. cURL examples run in a terminal. Configure RACINGAPI_KEY privately on your server. When an example uses RACE_ID, HORSE_ID, COURSE_ID or RACE_DATE, set those to discovered IDs and the matching YYYY-MM-DD; they are placeholders, not literal API values.
The shape of a safe integration
The pattern that works for almost every website and app is the same: your visitors talk to your server, your server talks to RacingAPI.net, and your server keeps a short cache so that a thousand visitors do not become a thousand API requests. Your own website or app may display the data; reselling raw API access, sharing keys or redistributing the feed is forbidden on every plan.
- 1Visitor browser. Requests your page or your own JSON route. No RacingAPI.net key is present.
- 2Your server. Checks its own cache first. Only on a miss does it build an outbound request.
- 3RacingAPI.net /v1. Validates the X-API-Key header, applies your plan limits and returns JSON or PNG.
- 4Your cache. Stores the body until a sensible expiry, then serves every following visitor.
Your first request: today's racecards
/v1/racecardsDeveloper, Professional, EnterpriseRaces and declared runners in the combined UK and Ireland daily feed.
Send the key in the X-API-Key header. Authorization: Bearer YOUR_KEY is accepted too. region=uk is the only accepted region and is also the default; it already includes Irish meetings. The examples below ask for ten races and fail loudly on any non-2xx status.
curl --fail-with-body "https://racingapi.net/v1/racecards?region=uk&limit=10" \
-H "X-API-Key: $RACINGAPI_KEY"Reading the response envelope
Core racing JSON responses use meta and data. List endpoints return data as an array; ID endpoints return a single object. There are important exceptions: weather has its own metadata, the tips list has pagination metadata, and the single-tip and explanation endpoints return { data: ... } without meta. Silks return binary PNG instead. Errors return a different shape. Read each lesson's response notes rather than assuming every endpoint has identical metadata.
| Field | Meaning |
|---|---|
| meta.version | Always v1. |
| meta.region | uk, the combined UK and Ireland feed. |
| meta.date | The date you requested, or null for today's default feed. The real meeting date is on each race. |
| meta.retrievedAt | When the gateway retrieved the snapshot. Not a promise about how recently the source changed. |
| meta.cached | true when an existing shared snapshot was reused. It still counts towards your allowance. |
| meta.page, meta.limit, meta.total | Pagination for list endpoints; total is counted before slicing. |
| error, code, requestId | Present on failures. Show error to operators, branch on code, quote requestId to support. |
Core race and runner fields such as IDs, ages, weights and prices arrive as strings. Missing supplied runner strings are normally empty and collections are arrays. That is not a universal type rule: metadata includes numbers and booleans, weather has numeric measurements and nullable values, and tip fields can be null. Render defensively and follow each field's type in the API reference rather than assuming every value is text or zero.
Reference material
Exact schemas: API reference. First call: Quickstart. Copy-ready helpers: Code examples. Plans: Pricing.