WorldAthletics.org APIWorldAthletics.org ↗
Search athletes, retrieve competition results by year, and access full major championship career histories from World Athletics via a clean REST API.
curl -X GET 'https://api.parse.bot/scraper/c818b331-d34b-4d51-b08b-f72111010743/search_athletes' \ -H 'X-API-Key: $PARSE_API_KEY'
Search for athletes by name. Returns matching athletes with basic profile information including ID, name, disciplines, country, and URL slug. Results include fuzzy matches.
| Param | Type | Description |
|---|---|---|
| queryrequired | string | Athlete name or partial name to search for (e.g. 'Bolt', 'Hassan'). |
| gender | string | Filter by gender. The GraphQL API accepts GenderType enum values. |
| country_code | string | Filter by 3-letter country code (e.g. 'JAM', 'USA', 'GBR'). |
| discipline_code | string | Filter by discipline code. |
{
"type": "object",
"fields": {
"total": "integer",
"athletes": "array of athlete objects with athlete_id, family_name, given_name, birth_date, disciplines, gender, country, url_slug"
},
"sample": {
"total": 30,
"athletes": [
{
"gender": "Men",
"country": "JAM",
"url_slug": "jamaica/usain-bolt-14201847",
"athlete_id": "14201847",
"birth_date": "21 AUG 1986",
"given_name": "Usain",
"disciplines": "100 Metres, 200 Metres, 400 Metres",
"family_name": "BOLT"
}
]
}
}About the WorldAthletics.org API
The World Athletics API gives developers access to three endpoints covering athlete search, annual competition results, and career championship history from WorldAthletics.org. Use search_athletes to find any athlete by name — with optional filters for gender, country, and discipline — then pull per-year race results or a full major-championship career timeline using the returned athlete ID and URL slug.
Athlete Search
The search_athletes endpoint accepts a name or partial name and returns a list of matching athlete profiles. Each result includes athlete_id, given_name, family_name, birth_date, disciplines, gender, country, and url_slug. You can narrow results with gender, country_code (ISO 3-letter codes like JAM or USA), or discipline_code. The athlete_id and url_slug returned here are the keys required by the other two endpoints.
Annual Competition Results
get_athlete_results takes a required athlete_id and an optional year parameter. When year is omitted, the endpoint defaults to the athlete's most recent active year. The response includes a results_by_event array — each object holds a discipline name and an array of individual competition results with marks, places, venues, and scores. The active_years field lists every year the athlete has recorded results, so you can iterate over a full history year by year.
Career Championship History
get_athlete_career requires both athlete_id and url_slug. It returns a career_results array organized by competition category — Olympic Games, World Championships, and other major competitions. Each category entry contains a results array covering every race the athlete contested at that level throughout their career. This endpoint is the right choice when you need a summary view of an athlete's peak-performance record rather than a full seasonal log.
- Build an athlete comparison tool showing head-to-head championship records using
get_athlete_careerresults. - Track a sprinter's seasonal progression by iterating over
active_yearswithget_athlete_results. - Power a country-specific leaderboard by filtering
search_athleteswithcountry_codeand a discipline code. - Generate career highlight pages for Olympic and World Championship performances from
career_resultscategory objects. - Automate alerts when a target athlete posts a new personal best by polling annual results with
get_athlete_results. - Feed an analytics dashboard with venue and mark data from
results_by_eventfor a given year. - Resolve athlete IDs for a bulk lookup pipeline using fuzzy name matching in
search_athletes.
| Tier | Price | Credits/month | Rate limit |
|---|---|---|---|
| Free | $0/mo | 100 | 5 req/min |
| Hobby | $30/mo | 1,000 | 20 req/min |
| Developer | $100/mo | 5,000 | 250 req/min |
One credit = one API call regardless of which marketplace API you call. Exceeding the rate limit returns a 429 response. Authenticate with the X-API-Key header.
Does World Athletics have an official developer API?+
What does `get_athlete_results` return, and how do I retrieve results for a specific year?+
year integer parameter (e.g. 2022) to select a specific year. If you omit year, the response defaults to the athlete's most recent active year. The active_years field in the response lists all years with available data, which you can loop over to build a multi-year dataset.Does the API expose world records, all-time rankings, or event-level leaderboards?+
Are relay or team event results included alongside individual event results?+
get_athlete_results are grouped by discipline name within results_by_event, so relay legs an athlete ran may appear if World Athletics records them against the individual. However, team-level relay splits and full relay squad rosters are not a dedicated part of the response. You can fork this API on Parse and revise it to build out relay-specific coverage.