World Athletics APIWorldAthletics.org ↗
Access World Athletics data: search athletes, retrieve competition results, career histories, personal bests, and the full competition calendar via 5 structured endpoints.
What is the World Athletics API?
The World Athletics API exposes 5 endpoints covering athlete search, competition results, career histories, full profiles, and the global competition calendar. Use search_athletes to find any athlete by name with support for gender, country, and discipline filters, then follow up with get_athlete_results or get_athlete_career to pull structured performance records. Response fields span marks, venues, dates, world rankings, personal bests, and championship honours.
curl -X GET 'https://api.parse.bot/scraper/c818b331-d34b-4d51-b08b-f72111010743/search_athletes?query=Bolt' \ -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 World Athletics API
Athlete Search and Profiles
The search_athletes endpoint accepts a name or partial name and returns an array of athlete objects containing athlete_id, family_name, given_name, birth_date, disciplines, gender, country, and url_slug. Optional filters for gender, country_code (3-letter NOC code), and discipline_code narrow results when the name alone is ambiguous. The athlete_id and url_slug from these results are required inputs for all other athlete endpoints.
get_athlete_profile returns the most complete snapshot of a single athlete: biographical fields (birth_date, biography, country_code), an honours array grouped by category (Olympic Games, World Championships, Diamond League, Major Marathons, etc.) with per-result discipline, competition, venue, place, mark, and date, plus personal bests across all disciplines and current/best world rankings referenced via iaaf_id.
Competition Results and Career History
get_athlete_results returns all competitions an athlete entered in a given year, grouped by event in results_by_event. Each result includes the mark, place, venue, and date. The active_years array in the response tells you which years have data for that athlete, so you can paginate through a full career year by year. When year is omitted, the endpoint defaults to the most recent active year.
get_athlete_career organises major-championship results into category buckets (Olympic Games, World Championships, Other competitions), giving a condensed view of an athlete's performance at the highest level without filtering by year.
Competition Calendar
list_competitions covers the full World Athletics calendar — world, area, and national meetings — and returns results sorted chronologically. Filter by start_date and end_date (ISO YYYY-MM-DD), country, area, discipline, or free-text query. Each competition object includes competition_id, name, venue, country_code, area, start_date, end_date, permit_level, and competition_group. The has_more boolean and offset/limit parameters support straightforward pagination up to 100 results per page.
The World Athletics API is a managed, monitored endpoint for WorldAthletics.org — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when WorldAthletics.org 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 WorldAthletics.org 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?+
- Build an athlete performance tracker that displays year-by-year results using
get_athlete_resultsand theactive_yearsfield. - Populate a championship honours page for any athlete using the
honoursarray fromget_athlete_profile. - Create a competition finder that lets users browse upcoming meets by country, discipline, and date range via
list_competitions. - Cross-reference personal bests and world rankings for athletes in the same discipline before a major event.
- Aggregate career major-championship results across multiple athletes using
get_athlete_careerfor historical comparison. - Alert fans or coaches when new competitions are added to the calendar for a specific country or area.
- Identify all athletes from a given country and discipline for national federation dashboards using
search_athleteswithcountry_codeanddiscipline_codefilters.
| 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 World Athletics have an official public developer API?+
What does `get_athlete_results` return, and how do I retrieve results for past years?+
results_by_event array. Each entry includes the mark, place, venue, and date. The response also includes an active_years array listing every year for which results exist; use those values in the year parameter to retrieve a different season. When year is omitted, the most recent active year is returned.Does the API return real-time live results during an ongoing competition?+
Can I retrieve world rankings lists — for example, the top 100 athletes in the 100m?+
get_athlete_profile, but there is no endpoint that returns a ranked list of athletes by discipline or event. You can fork this API on Parse and revise it to add a rankings-list endpoint covering that use case.How does pagination work in `list_competitions`?+
total count, an offset, a limit (clamped to 100), and a has_more boolean. To fetch the next page, add the current limit to the current offset and pass that as the new offset. Continue while has_more is true.