Timeform APItimeform.com ↗
Access Timeform horse racing fixtures, today's runners with jockey/trainer data, and Timeform ratings via the free daily race pass — 3 endpoints.
What is the Timeform API?
The Timeform API provides 3 endpoints covering horse racing fixtures, runner listings, and expert ratings data from timeform.com. The get_fixtures endpoint returns race schedules for today or tomorrow across all courses grouped by region, including going conditions and race status. The get_free_race_pass endpoint exposes actual Timeform numerical ratings alongside performance flags for top-rated horses in the featured daily race.
curl -X GET 'https://api.parse.bot/scraper/938f4b8f-8433-4631-8b8d-d2589e206bdc/get_fixtures?day=today' \ -H 'X-API-Key: $PARSE_API_KEY'
Typed, relational, agent-ready
A generated client with real types, enums, and the links between objects — the structure a flat JSON response can't carry. Autocompletes in your editor and reads cleanly to coding agents.
- Fully typed · autocompletes
- Objects link to objects
- Typed errors & pagination
Typed Python client. Set up the SDK in your uv project, then pull this API’s typed client:
uv add parse-sdk uv run parse init uv run parse add --marketplace timeform-com-api
uv run parse add --marketplace pulls a pinned snapshot of this canonical API — it won’t change underneath you. To customize it, subscribe and swap to your own copy.
"""Walkthrough: Timeform horse racing SDK — fixtures, runners, and the free race pass."""
from parse_apis.timeform_com_api import Timeform, Day, InputFormatInvalid
client = Timeform()
# Fetch today's fixtures and inspect courses and their going conditions.
try:
fixture = client.fixtures.get(day=Day.TODAY)
except InputFormatInvalid as e:
print(f"Invalid input: {e.message}")
raise
print(f"Fixtures for {fixture.day}: {len(fixture.courses)} courses")
for course in fixture.courses[:3]:
print(f" {course.course} — {course.going} ({len(course.races)} races)")
# Browse today's runners starting with letter "B", capped at 5 items.
for runner in client.runners.list(letter="B", limit=5):
print(f"{runner.horse_name} | jockey: {runner.jockey} | trainer: {runner.trainer}")
# Get the free daily race pass with Timeform ratings for top-rated horses.
race_pass = client.race_passes.get()
print(f"\nFree Race Pass: {race_pass.course} at {race_pass.time} on {race_pass.date}")
for horse in race_pass.horses:
print(f" #{horse.cloth_number} {horse.horse_name} — rating {horse.timeform_rating} ({', '.join(horse.flags)})")
print("\nexercised: fixtures.get / runners.list / race_passes.get")
Returns racing fixtures for today or tomorrow, listing all courses with their going conditions and individual races (time, name, number of runners, status). Courses are grouped by region (GB & Ire, USA, etc). Each race includes a status of 'result' (already run) or 'upcoming'. The number in parentheses in race names indicates declared runners; some divided races may show null for num_runners until final declarations.
| Param | Type | Description |
|---|---|---|
| day | string | Which day's fixtures to retrieve. |
{
"type": "object",
"fields": {
"day": "string — the requested day (today or tomorrow)",
"courses": "array of course objects each containing course name, going, and races array",
"regions": "array of region objects with name and region_id"
},
"sample": {
"data": {
"day": "today",
"courses": [
{
"going": "Good (Good to Firm in places)",
"races": [
{
"name": "DOWNLOAD THE RACEDAY READY APP AMATEUR RIDERS' HANDICAP",
"time": "14:15",
"status": "result",
"url_path": "/horse-racing/result/catterick-bridge/2026-08-17/1415/9/1",
"num_runners": 5
}
],
"course": "Catterick Bridge"
}
],
"regions": [
{
"name": "GB & Ire (4)",
"region_id": "0"
}
]
},
"status": "success"
}
}About the Timeform API
Fixtures and Race Schedules
The get_fixtures endpoint accepts a day parameter (today or tomorrow) and returns a structured list of courses grouped into regions (e.g. GB & Ire, USA). Each course object includes going conditions and an array of races with race time, race name, runner count, and a status field that distinguishes between result (already run) and upcoming races. This makes it straightforward to build a live race card view or filter to only forthcoming events.
Today's Runners
The get_todays_runners endpoint returns all runners competing today, sorted alphabetically and filterable by a single uppercase letter parameter (A–Z). Each runner object includes the horse's name and code, cloth number, jockey name and code, and trainer name and code. Where available from betting data, the response also includes race context fields: course_id, race_number, and meeting_date. Note that some runners may have partial data depending on availability at the time of the request.
Free Race Pass and Timeform Ratings
The get_free_race_pass endpoint requires no parameters and returns Timeform's featured race for the day. The response includes the race time, course, and date, plus an array of horses — typically the top 3 rated — each carrying a numeric Timeform rating, jockey, trainer, and any applicable performance flags such as Horse In Focus or Horse For Course Positive Flag. The race_url_path field provides a relative path to the full race card on timeform.com.
The Timeform API is a managed, monitored endpoint for timeform.com — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when timeform.com changes and a check fails, the API is automatically queued for repair and re-verified. It is built to keep working as the site underneath it changes.
This isn't an official timeform.com API — it's an independent, maintained REST wrapper over public data. Where the source has no official API (or only a limited one), Parse gives you a stable contract over a source that never promised one, and keeps it current. Need a new endpoint or field? You can revise it yourself in plain English and the agent rebuilds it against the live site in minutes — contributing the change back to the shared API is free.
Will this API break when the source site changes?+
Is this an official API from the source site?+
Can I fix or extend this API myself if I need a new endpoint or field?+
What happens if I call an endpoint that has an issue?+
- Display a live daily race schedule filtered to upcoming races using the
statusfield fromget_fixtures - Build a jockey or trainer lookup tool by aggregating entries from
get_todays_runnersacross all letters A–Z - Surface Timeform's top-rated horses and their numerical ratings in a race preview widget using
get_free_race_pass - Track going conditions across multiple courses on a given day using the course-level going data from
get_fixtures - Alert users when a horse flagged as 'Horse In Focus' or 'Horse For Course Positive Flag' appears in the daily race pass
- Cross-reference trainer and jockey codes from
get_todays_runnerswith historical data in your own database - Show tomorrow's fixture list with runner counts to help users plan which races to follow in advance
| Tier | Price | Credits/month | Rate limit |
|---|---|---|---|
| Free | $0/mo | 200 | 5 req/min |
| Hobby | $30/mo | 1,000 | 20 req/min |
| Developer | $100/mo | 5,000 | 100 req/min |
| Team | $300/mo | 20,000 | 300 req/min |
| Company | $1,000/mo | 100,000 | 500 req/min |
Each endpoint has a fixed posted price per successful call — most fall between 1 and 10 credits — shown on this API's page before you run it. Exceeding the rate limit returns a 429 response. Authenticate with the X-API-Key header.
Does Timeform offer an official developer API?+
What does the `get_fixtures` endpoint return for race status, and how do regions work?+
status field set to either result (the race has been run) or upcoming. Courses are organized under regions objects, each with a name and region_id, covering groups like GB & Ire and USA. This lets you segment fixtures by geography or filter to only races still to run.Does `get_todays_runners` return full race card details such as odds, form figures, or horse weights?+
course_id, race_number, meeting_date) where available. Odds, form figures, weights, and draw data are not part of the response. You can fork this API on Parse and revise it to add an endpoint targeting that additional data.How many horses does `get_free_race_pass` return, and does it cover every race on the day?+
Are historical fixtures or past race results available through this API?+
get_fixtures, today's runners via get_todays_runners, and today's featured race via get_free_race_pass. Historical results and archived data are not exposed. You can fork this API on Parse and revise it to add an endpoint for historical race data.