--- name: horseracingapi-uk description: British and Northern Irish horse racing data from horseracingapi.co.uk (courses, racecards, results, prices, race reports, trainers, jockeys, owners, statistics since 2017). Use when an agent needs UK racing facts or builds on them; not for tips or other countries. --- # Horse Racing API UK Factual horse racing data for Great Britain and Northern Ireland since 1 January 2017, as JSON over HTTPS: every course, card, runner and result, starting prices and the market, written race reports, and the trainers, jockeys and owners behind every horse. Operated by DeveloperData.net. ## When to use it, and when not Use it for UK racing facts: what runs today, who won, at what price, how a horse or yard has been running, a course's details, a race's written account. Do not use it for racing outside Great Britain and Northern Ireland (the Republic of Ireland included), for tips or predictions (there are none), for sectional times or in-running comments, or for anything before 2017. ## Getting access - A free key: sign in with Google at https://horseracingapi.co.uk/free-key. It reads yesterday only, 50 calls a month, with prices as null. - Paid plans (Live, Archive, Complete) read further; the same key follows the plan. See https://horseracingapi.co.uk/pricing. - Send the key in a header: `X-API-Key: ` or `Authorization: Bearer `. A key in the address is refused. Base URL: `https://api.horseracingapi.co.uk/v1` ## The calls that answer common questions Today's cards (Live and above): ``` curl https://api.horseracingapi.co.uk/v1/racecards/today -H "X-API-Key: $HRUK_KEY" ``` ```json {"data": [{"meeting_id": "mt_...", "course": "...", "going": "Good to Soft", "races": [{"race_id": "rc_...", "race_time": "13:20"}]}], "meta": {"plan": "live", "window": "today and the next 3 days", "count": 5}} ``` Yesterday's results (every plan): ``` curl https://api.horseracingapi.co.uk/v1/results/yesterday -H "X-API-Key: $HRUK_KEY" ``` One race in full, with the field and the market: ``` curl https://api.horseracingapi.co.uk/v1/races/rc_xxxxxxxx -H "X-API-Key: $HRUK_KEY" ``` From a name to an id: ``` curl "https://api.horseracingapi.co.uk/v1/search?q=star&type=horse" -H "X-API-Key: $HRUK_KEY" ``` A horse's UK form, newest first: ``` curl https://api.horseracingapi.co.uk/v1/horses/hs_xxxxxxxx/form -H "X-API-Key: $HRUK_KEY" ``` Every endpoint has a page with its parameters and a sample at https://horseracingapi.co.uk/documentation, and the whole API is in one file at https://horseracingapi.co.uk/documentation/manual.md. ## Limits - Free key: reads yesterday only, 60 calls a minute, 50 a month. - Live (GBP 35 a month): reads today and the next 3 days, 180 calls a minute, 250,000 a month. - Archive (GBP 60 a month): reads January 2017 to yesterday, 90 calls a minute, 150,000 a month. - Complete (GBP 89 a month): reads January 2017 to the next 3 days, 180 calls a minute, 400,000 a month. - Dates are the course's own racing day, YYYY-MM-DD. Race times are the racecourse clock; every other time is UTC. - Race reports start in 2020. Reports and statistics are on Complete. - Lists come a page at a time: pass `meta.next_cursor` back as `cursor` while `meta.has_more` is true. ## Errors Errors are `{"error": {"code", "message", "request_id", "docs"}}`. Branch on `code`: - 400 `bad_request`: a value is the wrong shape. - 401 `unauthorized`: no key, or not one of ours. - 403 `upgrade_required`: the plan does not reach this endpoint; the answer names the plans that do. - 403 `outside_plan_window`: the day is outside the plan's window; the answer gives the window. - 404 `not_found`: no such id, or not UK racing. - 422 `unknown_parameter`: a parameter the endpoint does not take; the answer lists the allowed ones. - 429 `rate_limited` (wait for `Retry-After`) or `quota_exceeded` (the month is used up). A 403 is never temporary; do not retry it. An empty list is a 200 with `meta.count` 0. ## MCP server Address: `https://horseracingapi.co.uk/mcp`. Each tool calls the API with the caller's own key. - `list_courses`: Every British and Northern Irish course, with where it is and which way round it runs. (`GET /v1/courses`) - `course_details`: One course in full: what is raced there and over which distances. (`GET /v1/courses/{course_id}`) - `todays_racecards`: Today's UK cards, every meeting and race in the order they are due off. (`GET /v1/racecards/today`) - `racecards_for_date`: The full UK card for one day, with results where the races are settled. (`GET /v1/racecards/{date}`) - `results_for_date`: Every settled UK race on a day: finishing order, starting prices and the rest. (`GET /v1/results/{date}`) - `race_details`: One race: its conditions, the market and every runner. (`GET /v1/races/{race_id}`) - `race_market`: A race's market: the book, every price and what moved. (`GET /v1/races/{race_id}/market`) - `search_races`: Find UK races by date, course, type, going, class and field size. (`GET /v1/races/search`) - `search_racing`: Look up a horse, trainer, jockey or course by name and get its id. (`GET /v1/search`) - `horse_form`: A horse's UK runs, newest first. (`GET /v1/horses/{horse_id}/form`) - `trainer_stats`: A trainer's strike rate, A/E and level stakes, split any way. (`GET /v1/trainers/{trainer_id}/stats`) - `jockey_stats`: A jockey's strike rate, A/E and level stakes, split any way. (`GET /v1/jockeys/{jockey_id}/stats`) - `race_report`: The written account of one race, with a line for every runner. (`GET /v1/reports/{race_id}`) - `days_upsets`: The day's UK shocks, each scored 0 to 100 with the reasons. (`GET /v1/upsets`) ## A typical workflow 1. Check the key with `GET /v1/usage`: its plan and the days it reads. 2. Turn names into ids with `GET /v1/search`. 3. Get the day's racing with `GET /v1/racecards/today` or `GET /v1/results/{date}`. 4. Go deeper on one race with `GET /v1/races/{race_id}`, its `/market` or its `/result`. 5. For people, use the trainer, jockey and owner endpoints; for figures by course or going, the `/stats` endpoints on Complete. 6. Quote facts as given. Never present them as tips or predictions.