HKJC APIhkjc.com ↗
Search Hong Kong Jockey Club horses by name and retrieve full race-by-race form records including official ratings and finishing positions via the HKJC API.
What is the HKJC API?
The HKJC API exposes two endpoints that cover Hong Kong Jockey Club horse registration and race history data. Use search_horses to find any registered horse by full or partial name — getting back the horse's ID, current status, and pagination metadata — then pass that ID to get_horse_rating_history to retrieve a complete local form record with up to dozens of race entries, each carrying the official pre-race rating, finishing position, racecourse, and season.
curl -X GET 'https://api.parse.bot/scraper/01e469d9-7b80-4554-bafc-77b2fd8ef8bf/search_horses?query=GOLDEN' \ -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 hkjc-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: HKJC Horse Rating History — search, drill-down, point lookup."""
from parse_apis.hkjc_com_api import HKJC, HorseNotFound
client = HKJC()
# Search for horses whose name contains "GOLDEN", cap total results.
for summary in client.horse_summaries.search(query="GOLDEN", limit=5):
print(summary.name, summary.status)
# Drill into the first match to get full race history.
hit = client.horse_summaries.search(query="GOLDEN", limit=1).first()
if hit is not None:
horse = hit.details()
print(horse.name, f"rating={horse.current_rating}", f"races={horse.race_count}")
for race in (horse.races or [])[:3]:
print(f" {race.race_date} pos={race.finish_position} rating={race.rating} {race.racecourse} {race.distance_m}m")
# Point lookup by name — shows typed-error handling for an unknown horse.
try:
detail = client.horses.get_by_name(horse_name="GOLDEN SIXTY")
print(detail.name, detail.total_stakes, f"last_rating={detail.last_rating}")
except HorseNotFound:
print("horse not found")
print("exercised: horse_summaries.search / details / horses.get_by_name")
Searches HKJC's horse register by (partial) name and returns matching horses with their horse_id, name and registration status (Active, Retired or Deregistered). One request per call. If the query exactly matches a registered horse name the site resolves directly to that horse and a single result is returned with exact_match=true; otherwise results are paged 50 per page by the site, controlled by the `page` input (omitted = page 1), with total_records, total_pages and has_more describing the continuation. A query with no matches returns an empty horses list with total_records 0.
| Param | Type | Description |
|---|---|---|
| page | integer | 1-based results page (50 horses per page). Ignored when the query is an exact name match. |
| queryrequired | string | Horse name or name fragment, case-insensitive (e.g. GOLDEN). An exact full name resolves straight to that horse. |
{
"type": "object",
"fields": {
"page": "integer current page",
"query": "the search string echoed back",
"horses": "array of {horse_id (e.g. HK_2024_K347, input to get_horse_rating_history), name, status (Active|Retired|Deregistered)}",
"has_more": "boolean; true when a later page exists",
"exact_match": "boolean; true when the site resolved the query straight to one horse",
"total_pages": "integer number of pages (0 when nothing matched)",
"total_records": "integer total horses matching the query on the site"
},
"sample": {
"data": {
"page": 1,
"query": "GOLDEN",
"horses": [
{
"name": "ARMOR GOLDEN EAGLE",
"status": "Active",
"horse_id": "HK_2024_K566"
},
{
"name": "GOLDEN BRILLIANT",
"status": "Active",
"horse_id": "HK_2024_K347"
},
{
"name": "GOLDEN ACE",
"status": "Retired",
"horse_id": "HK_2014_T321"
}
],
"has_more": true,
"exact_match": false,
"total_pages": 4,
"total_records": 172
},
"status": "success"
}
}About the HKJC API
Horse Search
The search_horses endpoint accepts a query string (full or partial horse name, case-insensitive) and returns an array of matching horses. Each entry includes a horse_id (format: HK_<year>_<brand>, e.g. HK_2024_K347), the registered name, and a status field that is one of Active, Retired, or Deregistered. Results are paginated at 50 per page; the page parameter selects which page to retrieve, and has_more, total_pages, and total_records tell you whether further pages exist. When the query exactly matches a registered horse name, exact_match is returned as true and the result resolves directly to that single horse.
Race Rating History
get_horse_rating_history returns a horse's full profile and its complete Hong Kong race record. Supply either horse_id (as returned by search_horses) or horse_name (exact registered name). The profile fields include name, sire, dam, owner, trainer, colour_sex, and status. The races array is sorted newest-first; each entry contains race_date (ISO 8601), racecourse (ST for Sha Tin or HV for Happy Valley), race_number, season, race_index, the placing text as the site records it, and crucially the rating integer — the official HKJC rating the horse carried into that race. Where the site's rating text is non-numeric, the raw value is preserved in rating_raw. The race_count field gives the total number of entries returned.
Coverage and Scope
All data covers Hong Kong racing only — races run at Sha Tin (ST) and Happy Valley (HV) under HKJC jurisdiction. The API reflects the HKJC horse register, so horses that have never raced locally will not appear. Status values (Active, Retired, Deregistered) correspond to the horse's current standing in the HKJC register at the time of the request.
The HKJC API is a managed, monitored endpoint for hkjc.com — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when hkjc.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 hkjc.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?+
- Track official HKJC rating progression for a horse across its entire local career using the
ratingfield in each race entry. - Build a horse form guide app that resolves partial name searches via
search_horsesand displays finishing positions fromget_horse_rating_history. - Filter horses by
status(Active/Retired/Deregistered) to maintain an up-to-date roster of currently racing horses. - Analyse racecourse-specific performance by filtering the
racesarray on theracecoursefield (ST vs HV). - Identify pedigree relationships by comparing
sireanddamfields across multiple horses returned from name-fragment searches. - Aggregate race counts and rating trends per season using the
seasonandratingfields across a horse's form record. - Cross-reference trainer records by grouping
trainervalues returned across multipleget_horse_rating_historycalls.
| 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 HKJC offer an official developer API?+
What does `get_horse_rating_history` return for the `rating` field, and what happens when the value isn't a number?+
rating field is an integer representing the official HKJC rating the horse carried into each race. When the site's rating text cannot be parsed as a number — for example, when a horse ran without an official rating — the raw text is preserved in rating_raw and rating will not be a clean integer. Always check rating_raw when building any logic that depends on rating values.Does the API cover overseas races a HKJC-registered horse may have run in?+
get_horse_rating_history returns only races run in Hong Kong under HKJC jurisdiction (Sha Tin and Happy Valley). Overseas starts do not appear in the races array. You can fork this API on Parse and revise it to add an endpoint that covers international form if the underlying source exposes that data.Does `search_horses` return draw, weight carried, or jockey data alongside each result?+
search_horses returns only horse_id, name, and status per horse — it is a lookup tool, not a form data endpoint. Draw, weight, and jockey information are not currently returned by either endpoint. You can fork this API on Parse and revise it to add those fields to the race record entries in get_horse_rating_history.How does pagination work in `search_horses`, and when is the `page` parameter ignored?+
page parameter (1-based) to navigate pages; use has_more and total_pages to determine whether more results exist. The page parameter is ignored when the query is an exact match for a registered horse name — in that case exact_match is true and only that one horse is returned regardless of the page value.