ITTF APIittf.com ↗
Access ITTF world rankings, player profiles, match results, and event calendars via 5 endpoints. Get grip style, handedness, ranking points, and full tournament scores.
What is the ITTF API?
This API exposes 5 endpoints covering official World Table Tennis and ITTF data including player profiles, world rankings, event calendars, and match results. The get_rankings endpoint returns a full ranked list of up to 100 players with points and ranking changes in a single request, while get_events delivers a complete annual calendar of 100+ scheduled and completed tournaments with location, dates, and event type.
curl -X GET 'https://api.parse.bot/scraper/d332c82e-1b62-499e-99ac-490db85dd8d3/get_events?year=2026' \ -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 ittf-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: World Table Tennis SDK — bounded, re-runnable; every call capped."""
from parse_apis.World_Table_Tennis_ITTF_API import WorldTableTennis, RankingCategory, NotFound
client = WorldTableTennis()
# Browse men's singles rankings
for player in client.rankings.list(category=RankingCategory.MS, limit=3):
print(player.rank, player.player_name, player.country_name, player.points)
# Browse women's singles rankings
for player in client.rankings.list(category=RankingCategory.WS, limit=3):
print(player.rank, player.player_name, player.country_name, player.points)
# List upcoming events for the current year
for event in client.events.list(year=2026, limit=3):
print(event.name, event.city, event.country, event.start_date)
# Fetch detailed player profile by ITTF ID
try:
player = client.players.get(ittf_id="102891")
print(player.name, player.handedness, player.grip, player.country_name)
except NotFound as exc:
print(f"Player not found: {exc}")
# Browse match results for a specific event
event = client.event(event_id=3231)
for result in event.results.list(limit=3):
print(result.sub_event_type, result.match_card.venue_name, result.match_card.overall_scores)
print("exercised: rankings.list / events.list / players.get / event.results.list")
Fetch the world table tennis event calendar for a specific year. Returns all scheduled and completed events including name, dates, location, and event type. A single request returns the full year's calendar (100+ events); no pagination needed.
| Param | Type | Description |
|---|---|---|
| year | integer | The calendar year to fetch events for. |
{
"type": "object",
"fields": {
"total": "integer count of events returned",
"events": "array of event objects with EventId, EventName, EventType, Country, City, ContinentCode, StartDateTime, EndDateTime"
},
"sample": {
"data": {
"total": 191,
"events": [
{
"City": "Doha",
"Country": "Qatar",
"EventId": 3231,
"EventName": "WTT Champions Doha 2026",
"EventType": "WTT Champions",
"EndDateTime": "2026-01-11T00:00:00",
"EventTypeId": 65,
"ContinentCode": "asia",
"StartDateTime": "2026-01-07T00:00:00"
}
]
},
"status": "success"
}
}About the ITTF API
Event and Match Data
The get_events endpoint accepts a year integer and returns an array of event objects covering the full calendar year. Each object includes EventId, EventName, EventType, Country, City, ContinentCode, StartDateTime, and EndDateTime. No pagination is required — one request returns all events for that year. The EventId values from this response can be passed directly to get_event_results to retrieve completed match data, including game scores, competitor names, match duration, venue, and subEventType classification.
Player Profiles and Rankings
The get_player_details endpoint takes an ittf_id string and returns a structured bio: PlayerName, CountryCode, CountryName, Handedness, Grip (e.g., Shakehand), Gender, DOB, Age, and a HeadShot image URL. ITTF IDs can be sourced from the get_featured_players endpoint or extracted from match result competitor data. The get_featured_players endpoint requires no inputs and returns a curated list of currently highlighted athletes, each with ranking, rankingPoints, ittfid, season StatsData, and full bio fields.
World Rankings
The get_rankings endpoint accepts an optional category string (MS for Men's Singles or WS for Women's Singles) and returns the full ranking table in a single response. Each entry includes rank, player_name, country_code, country_name, points, ittf_id, previous_rank, and the category code. The total field confirms the count of ranked players returned, typically 100 per category.
The ITTF API is a managed, monitored endpoint for ittf.com — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when ittf.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 ittf.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?+
- Build a live tournament tracker that displays event schedules and completed match scores using
get_eventsandget_event_results - Compare world ranking positions and point totals between men's and women's singles players via
get_rankings - Populate athlete profile cards with grip style, handedness, country, and headshot image from
get_player_details - Monitor ranking movements by comparing
rankandprevious_rankfields from theget_rankingsresponse - Display a featured player leaderboard combining ranking points and season statistics from
get_featured_players - Filter international events by continent or country using
ContinentCodeandCountryfields fromget_events
| 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 ITTF or World Table Tennis offer an official developer API?+
What does `get_event_results` return, and are all events guaranteed to have data?+
subEventType, and fullResults status for a given event_id. Only events with completed matches return data — events that have not yet started return no results. Use get_events first to confirm an event's date range before querying results.Does `get_rankings` cover doubles or mixed doubles categories?+
MS) and Women's Singles (WS) via the category parameter. Doubles and mixed doubles rankings are not included. You can fork the API on Parse and revise it to add the missing endpoint for those categories.Are historical match results beyond the most recent 10 per event available?+
get_event_results returns up to 10 recent official results for a given event. Deeper historical match archives per event are not currently exposed. You can fork the API on Parse and revise it to add pagination or a historical results endpoint.How do I find a player's ITTF ID to use with `get_player_details`?+
ittfid field returned by get_featured_players, and the competitor data embedded in match result objects from get_event_results. Either source gives you a valid ID to pass to get_player_details.