IMO Official APIimo-official.org ↗
Access IMO competition problems, shortlist PDFs, Hall of Fame names, and participant results by year via the imo-official.org API.
What is the IMO Official API?
The imo-official.org API exposes 4 endpoints covering International Mathematical Olympiad data: problem and shortlist PDF links organized by year, participant names from results pages, Hall of Fame listings with pagination, and name extraction from any page on the IMO website. The get_shortlists_and_problems endpoint, for example, returns per-year shortlist PDF URLs alongside language-specific problem PDF links in a single structured response.
No input parameters required.
curl -X GET 'https://api.parse.bot/scraper/d1cf9b10-7d90-4628-8a37-8ddc5a4b57c0/get_shortlists_and_problems' \ -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 imo-official-org-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: IMO Official Website API — bounded, re-runnable; every call capped."""
from parse_apis.imo_official_website_api import IMO, Year, PageNotFound
client = IMO()
# List all IMO editions with their problem PDFs and shortlists.
for edition in client.editions.list(limit=3):
shortlist = "available" if edition.shortlist_url else "not available"
print(f"IMO {edition.year}: shortlist {shortlist}, {len(edition.problem_links)} languages")
# Get the first edition and inspect its problem links.
edition = client.editions.list(limit=1).first()
if edition:
for link in edition.problem_links[:2]:
print(f" {link.language}: {link.url}")
# Fetch individual results for a specific year.
result = client.results.get(year=Year._2024)
print(f"IMO 2024: {len(result.names)} participants at {result.url}")
# Extract names from the IMO Board page.
try:
page = client.pages.get(path="board/")
print(f"Board members: {', '.join(page.names[:4])}")
except PageNotFound as exc:
print(f"Page not found: {exc}")
# List Hall of Fame contestants (top performers).
for name in client.contestants.list(limit=5):
print(f" Hall of Fame: {name}")
print("exercised: editions.list / results.get / pages.get / contestants.list")
Fetches all IMO competition years and extracts problem PDF download links (in multiple languages) and shortlist PDF URLs for each year. Iterates through all available years (1959-present) on the IMO problems pages. Shortlist URLs are null for years where shortlists are not yet released or unavailable.
No input parameters required.
{
"type": "object",
"fields": {
"items": "array of year objects, each containing year (integer), shortlist_url (string or null), and problem_links (array of objects with language string and url string)"
},
"sample": {
"data": {
"items": [
{
"year": 2025,
"problem_links": [
{
"url": "https://www.imo-official.org/assets/documents/problems/2025/2025_eng.pdf",
"language": "English"
}
],
"shortlist_url": null
},
{
"year": 2024,
"problem_links": [
{
"url": "https://www.imo-official.org/assets/documents/problems/2024/2024_eng.pdf",
"language": "English"
}
],
"shortlist_url": "https://www.imo-official.org/assets/documents/problems/2024/IMO2024SL.pdf"
}
]
},
"status": "success"
}
}About the IMO Official API
Problems and Shortlists
The get_shortlists_and_problems endpoint returns an array of year objects, each containing a year integer, a shortlist_url (string or null when no shortlist is published), and a problem_links array. Each entry in problem_links includes a language field and a url pointing to the corresponding PDF. This gives you a machine-readable index of every publicly available IMO problem set and shortlist across all recorded years without manual crawling.
Participant and Hall of Fame Names
get_results_by_year accepts a year integer and returns an object with the resolved url and a names array of alphabetically sorted participant name strings for that competition year. get_hall_of_fame targets the Hall of Fame page and supports pagination via a start integer parameter (0, 100, 200, and so on), returning up to 100 names per request alongside the source url.
Flexible Page Name Extraction
extract_names_from_page accepts any relative path or absolute URL from the IMO site — such as advisory.aspx, year_individual_r.aspx?year=2024, or hall.aspx — and returns all names found on that page as a sorted names array. This makes it usable against results pages, board member listings, advisory committee pages, or any other page that lists people, without needing a dedicated endpoint for each.
The IMO Official API is a managed, monitored endpoint for imo-official.org — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when imo-official.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 imo-official.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 a searchable archive of IMO problem PDFs indexed by year and language using
get_shortlists_and_problems. - Track which countries' participants appear in year-by-year results using
get_results_by_yearacross multiple years. - Compile a full Hall of Fame roster by paginating through
get_hall_of_famewith incrementalstartvalues. - Cross-reference advisory committee or board member names against academic databases using
extract_names_from_page. - Detect year-over-year participation changes by comparing name arrays from consecutive calls to
get_results_by_year. - Download and catalog all published shortlist PDFs by filtering
shortlist_urlfields where the value is non-null.
| 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 | 100 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 imo-official.org provide an official developer API?+
What does `get_shortlists_and_problems` return for years where no shortlist is published?+
shortlist_url field is returned as null. The problem_links array may still contain entries if language-specific problem PDFs exist for that year.How does pagination work in `get_hall_of_fame`?+
start=0 for the first page, start=100 for the second, and so on. The response always includes the resolved url and an alphabetically sorted names array for the requested slice.Does the API return individual scores, medals, or country affiliations alongside participant names?+
get_results_by_year, get_hall_of_fame, and extract_names_from_page — return names as plain strings with no attached score, medal, or country data. You can fork this API on Parse and revise it to extract those additional fields from the results pages.Can the API retrieve problem statement text rather than just PDF links?+
get_shortlists_and_problems returns PDF URLs for problems and shortlists, not the extracted text content of those documents. You can fork this API on Parse and revise it to add a problem-text extraction endpoint.