{ "openapi": "3.1.0", "info": { "title": "HorseRacingAPI", "version": "1.0.0", "description": "Official horse racing results from the United States, Great Britain, Ireland, France and South Africa since 1 January 2022. Factual data only.", "termsOfService": "https://horseracingapi.org/terms", "contact": { "url": "https://horseracingapi.org/support" } }, "servers": [ { "url": "https://api.horseracingapi.org" } ], "security": [ { "ApiKey": [] }, { "Bearer": [] } ], "tags": [ { "name": "Results", "description": "Days of results, the newest as they are declared, single races and race search." }, { "name": "Meetings", "description": "Every meeting on a day, and one meeting with all its races." }, { "name": "Horses", "description": "Find a horse, its profile and record, and its last ten runs." }, { "name": "Jockeys", "description": "Find a jockey, their record, and their last ten rides." }, { "name": "Trainers and owners", "description": "Trainers and owners, opened from any result they appear in." }, { "name": "Reference", "description": "The five nations, every course, and your own usage." } ], "paths": { "/v1/results/latest": { "get": { "operationId": "latest_results", "summary": "Latest results", "description": "The newest results, as they are declared, each with its full finishing order. Plan: Results plan.", "tags": [ "Results" ], "parameters": [ { "name": "country", "in": "query", "required": false, "description": "Only this nation: USA, GB, IRE, FR or RSA.", "schema": { "type": "string", "enum": [ "USA", "GB", "IRE", "FR", "RSA" ] } }, { "name": "per_page", "in": "query", "required": false, "description": "How many to a page, 1 to 50. Default 25.", "schema": { "type": "integer", "minimum": 1, "maximum": 50 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "race_id": { "type": "string", "description": "Our own id for the race. Stable, safe to store." }, "meeting_id": { "type": "string", "description": "The meeting it was run at." }, "course_id": { "type": "string", "description": "The course." }, "course": { "type": "string", "description": "Where it was run." }, "country": { "type": "string", "description": "USA, GB, IRE, FR or RSA." }, "date": { "type": "string", "description": "The course's own calendar day, YYYY-MM-DD." }, "time": { "type": "string", "description": "The advertised start, course time, HH:MM." }, "off_time": { "type": "string", "description": "When it actually started, course time, HH:MM:SS." }, "name": { "type": "string", "description": "The race title as run." }, "race_type": { "type": "string", "description": "Flat, Hurdle, Chase and so on, where the nation publishes it." }, "class": { "type": "string", "description": "Where the nation publishes one, else null." }, "distance": { "type": "string", "description": "As the course states it." }, "going": { "type": "string", "description": "The ground as declared on the day." }, "surface": { "type": "string", "description": "Turf, Dirt or All Weather." }, "handicap": { "type": "boolean", "description": "Whether it was a handicap." }, "runners": { "type": "integer", "description": "How many started." }, "result_available": { "type": "boolean", "description": "True once the result is declared." }, "winning_time": { "type": "string", "description": "Where the nation publishes one, as M:SS.ss, else null. Never guessed." }, "finishing_order": { "type": "array", "items": {}, "description": "Every runner in order: position, status, distance_beaten, cloth, draw, horse_id, horse, age, weight, jockey_id, jockey, trainer_id, trainer, owner_id, owner." } } } }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "externalDocs": { "url": "https://horseracingapi.org/documentation/results-latest" } } }, "/v1/results/yesterday": { "get": { "operationId": "yesterdays_results", "summary": "Yesterday's results", "description": "Every result from yesterday, at each course's own day, meeting by meeting. Plan: Free key.", "tags": [ "Results" ], "parameters": [ { "name": "country", "in": "query", "required": false, "description": "Only this nation: USA, GB, IRE, FR or RSA.", "schema": { "type": "string", "enum": [ "USA", "GB", "IRE", "FR", "RSA" ] } }, { "name": "per_page", "in": "query", "required": false, "description": "How many to a page, 1 to 25. Default 10.", "schema": { "type": "integer", "minimum": 1, "maximum": 25 } }, { "name": "page", "in": "query", "required": false, "description": "Which page, from 1.", "schema": { "type": "integer", "minimum": 1, "maximum": 100000 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "meeting_id": { "type": "string", "description": "Our own id for the meeting." }, "course_id": { "type": "string", "description": "The course." }, "course": { "type": "string", "description": "The course name." }, "country": { "type": "string", "description": "USA, GB, IRE, FR or RSA." }, "date": { "type": "string", "description": "The course's own calendar day." }, "going": { "type": "string", "description": "The going for the meeting." }, "surface": { "type": "string", "description": "Turf, Dirt or All Weather." }, "races": { "type": "array", "items": {}, "description": "Every race at the meeting in full, with its finishing order." } } } }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "externalDocs": { "url": "https://horseracingapi.org/documentation/results-yesterday" } } }, "/v1/results/{date}": { "get": { "operationId": "results_on_date", "summary": "Results by date", "description": "Every result for any day since 1 January 2022, meeting by meeting. Plan: Results plan.", "tags": [ "Results" ], "parameters": [ { "name": "date", "in": "path", "required": true, "description": "The day, YYYY-MM-DD, from 2022-01-01.", "schema": { "type": "string", "format": "date" } }, { "name": "country", "in": "query", "required": false, "description": "Only this nation: USA, GB, IRE, FR or RSA.", "schema": { "type": "string", "enum": [ "USA", "GB", "IRE", "FR", "RSA" ] } }, { "name": "per_page", "in": "query", "required": false, "description": "How many to a page, 1 to 25. Default 10.", "schema": { "type": "integer", "minimum": 1, "maximum": 25 } }, { "name": "page", "in": "query", "required": false, "description": "Which page, from 1.", "schema": { "type": "integer", "minimum": 1, "maximum": 100000 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "meeting_id": { "type": "string", "description": "Our own id for the meeting." }, "course_id": { "type": "string", "description": "The course." }, "course": { "type": "string", "description": "The course name." }, "country": { "type": "string", "description": "USA, GB, IRE, FR or RSA." }, "date": { "type": "string", "description": "The course's own calendar day." }, "going": { "type": "string", "description": "The going for the meeting." }, "surface": { "type": "string", "description": "Turf, Dirt or All Weather." }, "races": { "type": "array", "items": {}, "description": "Every race at the meeting in full, with its finishing order." } } } }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "externalDocs": { "url": "https://horseracingapi.org/documentation/results-date" } } }, "/v1/races/search": { "get": { "operationId": "search_races", "summary": "Search races", "description": "Races by date, nation, course, race type, going or surface. Plan: Results plan.", "tags": [ "Results" ], "parameters": [ { "name": "date_from", "in": "query", "required": false, "description": "From this day. The archive starts on 2022-01-01.", "schema": { "type": "string", "format": "date" } }, { "name": "date_to", "in": "query", "required": false, "description": "Up to this day. Defaults to today.", "schema": { "type": "string", "format": "date" } }, { "name": "country", "in": "query", "required": false, "description": "Only this nation: USA, GB, IRE, FR or RSA.", "schema": { "type": "string", "enum": [ "USA", "GB", "IRE", "FR", "RSA" ] } }, { "name": "course_id", "in": "query", "required": false, "description": "Only this course.", "schema": { "type": "string" } }, { "name": "race_type", "in": "query", "required": false, "description": "Flat, Hurdle, Chase and so on.", "schema": { "type": "string" } }, { "name": "going", "in": "query", "required": false, "description": "The going, as published.", "schema": { "type": "string" } }, { "name": "surface", "in": "query", "required": false, "description": "Turf, Dirt or All Weather.", "schema": { "type": "string", "enum": [ "Turf", "Dirt", "All Weather" ] } }, { "name": "handicap", "in": "query", "required": false, "description": "true for handicaps only, false for none.", "schema": { "type": "boolean" } }, { "name": "per_page", "in": "query", "required": false, "description": "How many to a page, 1 to 100. Default 25.", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "description": "meta.next_cursor from the previous answer, as it came.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "race_id": { "type": "string", "description": "Our own id for the race. Stable, safe to store." }, "meeting_id": { "type": "string", "description": "The meeting it was run at." }, "course_id": { "type": "string", "description": "The course." }, "course": { "type": "string", "description": "Where it was run." }, "country": { "type": "string", "description": "USA, GB, IRE, FR or RSA." }, "date": { "type": "string", "description": "The course's own calendar day, YYYY-MM-DD." }, "time": { "type": "string", "description": "The advertised start, course time, HH:MM." }, "off_time": { "type": "string", "description": "When it actually started, course time, HH:MM:SS." }, "name": { "type": "string", "description": "The race title as run." }, "race_type": { "type": "string", "description": "Flat, Hurdle, Chase and so on, where the nation publishes it." }, "class": { "type": "string", "description": "Where the nation publishes one, else null." }, "distance": { "type": "string", "description": "As the course states it." }, "going": { "type": "string", "description": "The ground as declared on the day." }, "surface": { "type": "string", "description": "Turf, Dirt or All Weather." }, "handicap": { "type": "boolean", "description": "Whether it was a handicap." }, "runners": { "type": "integer", "description": "How many started." }, "result_available": { "type": "boolean", "description": "True once the result is declared." } } } }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "externalDocs": { "url": "https://horseracingapi.org/documentation/races-search" } } }, "/v1/races/{race_id}": { "get": { "operationId": "get_race", "summary": "Race detail", "description": "One race in full: the conditions, the time and every runner in finishing order. Plan: Results plan.", "tags": [ "Results" ], "parameters": [ { "name": "race_id", "in": "path", "required": true, "description": "The race, as returned by any results or search call.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "race_id": { "type": "string", "description": "Our own id for the race. Stable, safe to store." }, "meeting_id": { "type": "string", "description": "The meeting it was run at." }, "course_id": { "type": "string", "description": "The course." }, "course": { "type": "string", "description": "Where it was run." }, "country": { "type": "string", "description": "USA, GB, IRE, FR or RSA." }, "date": { "type": "string", "description": "The course's own calendar day, YYYY-MM-DD." }, "time": { "type": "string", "description": "The advertised start, course time, HH:MM." }, "off_time": { "type": "string", "description": "When it actually started, course time, HH:MM:SS." }, "name": { "type": "string", "description": "The race title as run." }, "race_type": { "type": "string", "description": "Flat, Hurdle, Chase and so on, where the nation publishes it." }, "class": { "type": "string", "description": "Where the nation publishes one, else null." }, "distance": { "type": "string", "description": "As the course states it." }, "going": { "type": "string", "description": "The ground as declared on the day." }, "surface": { "type": "string", "description": "Turf, Dirt or All Weather." }, "handicap": { "type": "boolean", "description": "Whether it was a handicap." }, "runners": { "type": "integer", "description": "How many started." }, "result_available": { "type": "boolean", "description": "True once the result is declared." }, "winning_time": { "type": "string", "description": "Where the nation publishes one, as M:SS.ss, else null. Never guessed." }, "finishing_order": { "type": "array", "items": {}, "description": "Every runner in order: position, status, distance_beaten, cloth, draw, horse_id, horse, age, weight, jockey_id, jockey, trainer_id, trainer, owner_id, owner." } } }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "externalDocs": { "url": "https://horseracingapi.org/documentation/races-race_id" } } }, "/v1/meetings/{date}": { "get": { "operationId": "meetings_date", "summary": "Meetings by date", "description": "Every meeting on a day, with its going and how many races it held. Plan: Results plan.", "tags": [ "Meetings" ], "parameters": [ { "name": "date", "in": "path", "required": true, "description": "The day, YYYY-MM-DD, from 2022-01-01 to today.", "schema": { "type": "string", "format": "date" } }, { "name": "country", "in": "query", "required": false, "description": "Only this nation: USA, GB, IRE, FR or RSA.", "schema": { "type": "string", "enum": [ "USA", "GB", "IRE", "FR", "RSA" ] } }, { "name": "per_page", "in": "query", "required": false, "description": "How many to a page, 1 to 100. Default 50.", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "page", "in": "query", "required": false, "description": "Which page, from 1.", "schema": { "type": "integer", "minimum": 1, "maximum": 100000 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "meeting_id": { "type": "string", "description": "Our own id for the meeting." }, "course_id": { "type": "string", "description": "The course." }, "course": { "type": "string", "description": "The course name." }, "country": { "type": "string", "description": "USA, GB, IRE, FR or RSA." }, "date": { "type": "string", "description": "The course's own calendar day." }, "going": { "type": "string", "description": "The going for the meeting." }, "surface": { "type": "string", "description": "Turf, Dirt or All Weather." }, "races": { "type": "integer", "description": "How many races it held." } } } }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "externalDocs": { "url": "https://horseracingapi.org/documentation/meetings-date" } } }, "/v1/meetings/{meeting_id}": { "get": { "operationId": "get_meeting", "summary": "Meeting", "description": "A meeting and every race run at it. Plan: Results plan.", "tags": [ "Meetings" ], "parameters": [ { "name": "meeting_id", "in": "path", "required": true, "description": "The meeting.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "meeting_id": { "type": "string", "description": "Our own id for the meeting." }, "course_id": { "type": "string", "description": "The course." }, "course": { "type": "string", "description": "The course name." }, "country": { "type": "string", "description": "USA, GB, IRE, FR or RSA." }, "date": { "type": "string", "description": "The course's own calendar day." }, "going": { "type": "string", "description": "The going for the meeting." }, "surface": { "type": "string", "description": "Turf, Dirt or All Weather." }, "races": { "type": "array", "items": {}, "description": "Every race, with its conditions. Open a race for its finishing order." } } }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "externalDocs": { "url": "https://horseracingapi.org/documentation/meetings-meeting_id" } } }, "/v1/horses/search": { "get": { "operationId": "find_horse", "summary": "Search horses", "description": "Find a horse by name. Plan: Results plan.", "tags": [ "Horses" ], "parameters": [ { "name": "q", "in": "query", "required": true, "description": "Part of the name, two letters or more.", "schema": { "type": "string" } }, { "name": "per_page", "in": "query", "required": false, "description": "How many to a page, 1 to 100. Default 25.", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "description": "meta.next_cursor from the previous answer, as it came.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "horse_id": { "type": "string", "description": "Our own id for the horse." }, "name": { "type": "string", "description": "The name it races under." }, "sex": { "type": "string", "description": "As published." }, "last_run": { "type": "string", "description": "The day it last ran." } } } }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "externalDocs": { "url": "https://horseracingapi.org/documentation/horses-search" } } }, "/v1/horses/{horse_id}": { "get": { "operationId": "get_horse", "summary": "Horse profile", "description": "A horse's profile, its current trainer and owner, and its record since 2022. Plan: Results plan.", "tags": [ "Horses" ], "parameters": [ { "name": "horse_id", "in": "path", "required": true, "description": "The horse.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "horse_id": { "type": "string", "description": "Our own id for the horse." }, "name": { "type": "string", "description": "The name it races under." }, "sex": { "type": "string", "description": "As published." }, "colour": { "type": "string", "description": "As published, where it is." }, "trainer_id": { "type": "string", "description": "The trainer at its latest run." }, "trainer": { "type": "string", "description": "The trainer name." }, "owner_id": { "type": "string", "description": "The owner at its latest run." }, "owner": { "type": "string", "description": "The owners named in full, exactly as they race." }, "record": { "type": "object", "description": "Since the archive starts, in our five nations: runs, wins, seconds, thirds, placed, win_pct, since, last_run." } } }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "externalDocs": { "url": "https://horseracingapi.org/documentation/horses-horse_id" } } }, "/v1/horses/{horse_id}/form": { "get": { "operationId": "horse_form", "summary": "Last ten runs", "description": "The last ten runs, newest first. Plan: Results plan.", "tags": [ "Horses" ], "parameters": [ { "name": "horse_id", "in": "path", "required": true, "description": "The horse.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string", "description": "The day of the run." }, "race_id": { "type": "string", "description": "The race, for the full result." }, "course_id": { "type": "string", "description": "The course." }, "course": { "type": "string", "description": "The course name." }, "country": { "type": "string", "description": "USA, GB, IRE, FR or RSA." }, "race_type": { "type": "string", "description": "Flat, Hurdle, Chase and so on." }, "class": { "type": "string", "description": "Where published, else null." }, "distance": { "type": "string", "description": "As the course states it." }, "going": { "type": "string", "description": "The ground on the day." }, "surface": { "type": "string", "description": "Turf, Dirt or All Weather." }, "runners": { "type": "integer", "description": "How many started." }, "position": { "type": "integer", "description": "Where it finished, or null." }, "status": { "type": "string", "description": "finished, or how the run ended: pulled_up, fell and so on." }, "distance_beaten": { "type": "string", "description": "How far behind the winner, where published." }, "weight": { "type": "string", "description": "The weight carried." }, "jockey_id": { "type": "string", "description": "Who rode it." }, "jockey": { "type": "string", "description": "The jockey name." }, "trainer_id": { "type": "string", "description": "Who trained it then." }, "trainer": { "type": "string", "description": "The trainer name." } } } }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "externalDocs": { "url": "https://horseracingapi.org/documentation/horses-horse_id-form" } } }, "/v1/jockeys/search": { "get": { "operationId": "find_jockey", "summary": "Search jockeys", "description": "Find a jockey by name. Plan: Results plan.", "tags": [ "Jockeys" ], "parameters": [ { "name": "q", "in": "query", "required": true, "description": "Part of the name, two letters or more.", "schema": { "type": "string" } }, { "name": "per_page", "in": "query", "required": false, "description": "How many to a page, 1 to 100. Default 25.", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "description": "meta.next_cursor from the previous answer, as it came.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "jockey_id": { "type": "string", "description": "Our own id for the jockey." }, "name": { "type": "string", "description": "The name they ride under." } } } }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "externalDocs": { "url": "https://horseracingapi.org/documentation/jockeys-search" } } }, "/v1/jockeys/{jockey_id}": { "get": { "operationId": "get_jockey", "summary": "Jockey profile", "description": "A jockey's profile and record since 2022. Plan: Results plan.", "tags": [ "Jockeys" ], "parameters": [ { "name": "jockey_id", "in": "path", "required": true, "description": "The jockey.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "jockey_id": { "type": "string", "description": "Our own id for the jockey." }, "name": { "type": "string", "description": "The name they ride under." }, "record": { "type": "object", "description": "Since the archive starts, in our five nations: runs, wins, seconds, thirds, placed, win_pct, since, last_run." } } }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "externalDocs": { "url": "https://horseracingapi.org/documentation/jockeys-jockey_id" } } }, "/v1/jockeys/{jockey_id}/rides": { "get": { "operationId": "jockey_rides", "summary": "Last ten rides", "description": "The last ten rides, newest first. Plan: Results plan.", "tags": [ "Jockeys" ], "parameters": [ { "name": "jockey_id", "in": "path", "required": true, "description": "The jockey.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string", "description": "The day of the run." }, "race_id": { "type": "string", "description": "The race, for the full result." }, "course_id": { "type": "string", "description": "The course." }, "course": { "type": "string", "description": "The course name." }, "country": { "type": "string", "description": "USA, GB, IRE, FR or RSA." }, "race_type": { "type": "string", "description": "Flat, Hurdle, Chase and so on." }, "class": { "type": "string", "description": "Where published, else null." }, "distance": { "type": "string", "description": "As the course states it." }, "going": { "type": "string", "description": "The ground on the day." }, "surface": { "type": "string", "description": "Turf, Dirt or All Weather." }, "runners": { "type": "integer", "description": "How many started." }, "position": { "type": "integer", "description": "Where it finished, or null." }, "status": { "type": "string", "description": "finished, or how the run ended: pulled_up, fell and so on." }, "distance_beaten": { "type": "string", "description": "How far behind the winner, where published." }, "weight": { "type": "string", "description": "The weight carried." }, "horse_id": { "type": "string", "description": "The horse ridden." }, "horse": { "type": "string", "description": "The horse name." }, "trainer_id": { "type": "string", "description": "Its trainer." }, "trainer": { "type": "string", "description": "The trainer name." } } } }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "externalDocs": { "url": "https://horseracingapi.org/documentation/jockeys-jockey_id-rides" } } }, "/v1/trainers/{trainer_id}": { "get": { "operationId": "get_trainer", "summary": "Trainer profile", "description": "A trainer's profile and record since 2022. Plan: Results plan.", "tags": [ "Trainers and owners" ], "parameters": [ { "name": "trainer_id", "in": "path", "required": true, "description": "The trainer, from any result.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "trainer_id": { "type": "string", "description": "Our own id for the trainer." }, "name": { "type": "string", "description": "The name they train under." }, "record": { "type": "object", "description": "Since the archive starts, in our five nations: runs, wins, seconds, thirds, placed, win_pct, since, last_run." } } }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "externalDocs": { "url": "https://horseracingapi.org/documentation/trainers-trainer_id" } } }, "/v1/owners/{owner_id}": { "get": { "operationId": "get_owner", "summary": "Owner profile", "description": "An owner's record since 2022. Plan: Results plan.", "tags": [ "Trainers and owners" ], "parameters": [ { "name": "owner_id", "in": "path", "required": true, "description": "The owner, from any result.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "owner_id": { "type": "string", "description": "Our own id for the owner." }, "name": { "type": "string", "description": "The owners named in full, exactly as they race." }, "record": { "type": "object", "description": "Since the archive starts, in our five nations: runs, wins, seconds, thirds, placed, win_pct, since, last_run." } } }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "externalDocs": { "url": "https://horseracingapi.org/documentation/owners-owner_id" } } }, "/v1/countries": { "get": { "operationId": "countries", "summary": "Nations", "description": "The five nations and what each one publishes. Plan: Free key.", "tags": [ "Reference" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "country": { "type": "string", "description": "USA, GB, IRE, FR or RSA." }, "name": { "type": "string", "description": "The nation." }, "note": { "type": "string", "description": "Anything worth knowing, else null." }, "from": { "type": "string", "description": "The first day served: 2022-01-01." }, "publishes": { "type": "object", "description": "finishing_order, class and winning_time: true where the nation publishes them." } } } }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "externalDocs": { "url": "https://horseracingapi.org/documentation/countries" } } }, "/v1/courses": { "get": { "operationId": "list_courses", "summary": "Courses", "description": "Every course in the five nations, with its latest meeting. Plan: Free key.", "tags": [ "Reference" ], "parameters": [ { "name": "country", "in": "query", "required": false, "description": "Only this nation: USA, GB, IRE, FR or RSA.", "schema": { "type": "string", "enum": [ "USA", "GB", "IRE", "FR", "RSA" ] } }, { "name": "page", "in": "query", "required": false, "description": "Which page, from 1.", "schema": { "type": "integer", "minimum": 1, "maximum": 100000 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "course_id": { "type": "string", "description": "Our own id for the course." }, "name": { "type": "string", "description": "The course." }, "country": { "type": "string", "description": "USA, GB, IRE, FR or RSA." }, "last_meeting": { "type": "string", "description": "The day it last raced." } } } }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "externalDocs": { "url": "https://horseracingapi.org/documentation/courses" } } }, "/v1/courses/{course_id}": { "get": { "operationId": "courses_course_id", "summary": "Course", "description": "One course: its surfaces, race types and distances. Plan: Results plan.", "tags": [ "Reference" ], "parameters": [ { "name": "course_id", "in": "path", "required": true, "description": "The course.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "course_id": { "type": "string", "description": "Our own id for the course." }, "name": { "type": "string", "description": "The course." }, "country": { "type": "string", "description": "USA, GB, IRE, FR or RSA." }, "surfaces": { "type": "array", "items": {}, "description": "Turf, Dirt or All Weather, as raced on since 2022." }, "race_types": { "type": "array", "items": {}, "description": "The race types run there since 2022, where published." }, "distances": { "type": "array", "items": {}, "description": "The distances it races over, most used first." }, "last_meeting": { "type": "string", "description": "The day it last raced." } } }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "externalDocs": { "url": "https://horseracingapi.org/documentation/courses-course_id" } } }, "/v1/usage": { "get": { "operationId": "my_usage", "summary": "Your usage", "description": "Your calls today and this month, and your limits. Never counted against them. Plan: Free key.", "tags": [ "Reference" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "plan": { "type": "string", "description": "free or results." }, "plan_name": { "type": "string", "description": "Free key or Results plan." }, "window": { "type": "string", "description": "What your plan reaches." }, "calls_today": { "type": "integer", "description": "Calls since 00:00 UTC." }, "calls_month": { "type": "integer", "description": "Calls since the 1st, UTC." }, "per_minute": { "type": "integer", "description": "Calls allowed in any minute." }, "per_day": { "type": "integer", "description": "Calls allowed a day, or null." }, "per_month": { "type": "integer", "description": "Calls allowed a month, or null." }, "resets": { "type": "object", "description": "day and month: when each count starts again, UTC." } } }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "externalDocs": { "url": "https://horseracingapi.org/documentation/usage" } } } }, "components": { "securitySchemes": { "ApiKey": { "type": "apiKey", "in": "header", "name": "X-API-Key" }, "Bearer": { "type": "http", "scheme": "bearer" } }, "schemas": { "Meta": { "type": "object", "properties": { "request_id": { "type": "string" }, "plan": { "type": "string" }, "window": { "type": "string" }, "data_as_of": { "type": "string", "format": "date-time" }, "count": { "type": "integer" }, "next_cursor": { "type": [ "string", "null" ] }, "next_page": { "type": [ "integer", "null" ] } } }, "Error": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "plan": { "type": "string" }, "docs": { "type": "string" } } } } } }, "responses": { "Error": { "description": "An error. See https://horseracingapi.org/documentation/errors", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }