ITTF APIittf.com ↗
Access WTT event calendars, match results, player profiles, and world rankings via 4 endpoints covering official ITTF table tennis data.
What is the ITTF API?
The ITTF API exposes 4 endpoints covering official World Table Tennis event schedules, match results, and player data. Use get_events to pull a full-year event calendar with locations, dates, and event types, or get_event_results to retrieve game-level scores and match cards for any completed WTT event. Player-facing endpoints return bio fields like grip style, handedness, world ranking, and ranking points.
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, NotFound
client = WorldTableTennis()
# 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)
# Get a featured player and check their ranking
featured = client.featuredplayers.list(limit=1).first()
if featured:
print(featured.full_name, featured.ranking, featured.ranking_points, featured.country_name)
# 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: events.list / featuredplayers.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 Calendar and Match Results
The get_events endpoint accepts a year integer and returns an array of event objects — each with EventName, EventType, Country, City, StartDateTime, EndDateTime, EventId, and ContinentCode. These EventId values feed directly into get_event_results, which returns up to 10 recent completed matches for that event including full match_card data with game scores, player names, match duration, and venue. Note that events without completed matches return a 404 rather than an empty result set.
Player Profiles and Rankings
get_player_details accepts an official ittf_id and returns a single player record with fields including PlayerName, DOB, Age, CountryName, Gender, Handedness, and Grip (e.g. Shakehand). This is useful for building player comparison tools or enriching match result data with biographical context.
get_featured_players requires no inputs and returns an array of currently featured athletes, each carrying fullName, ranking, rankingPoints, countryName, age, gender, and a nested additional_data block for season statistics. This is the fastest path to current world ranking data without needing a specific player ID.
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 WTT tournament tracker that surfaces upcoming and completed events by year and continent using
get_eventsfields likeContinentCodeandStartDateTime. - Display live match scorecards for a specific WTT event by querying
get_event_resultswith anevent_idand rendering thematch_carddata. - Enrich a player database with grip style, handedness, and nationality by fetching
get_player_detailsfor each ITTF ID. - Render a live world rankings widget using
get_featured_playerswithranking,rankingPoints, andcountryName. - Compare player biographies side-by-side by pulling
DOB,Handedness, andGripfields from multipleget_player_detailscalls. - Track a specific player's tournament appearances by cross-referencing their ITTF ID against event result data from
get_event_results.
| 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 ITTF or World Table Tennis offer an official developer API?+
What does `get_event_results` return for events that haven't started yet?+
get_events to check StartDateTime and EndDateTime before calling get_event_results to avoid unnecessary requests.Can I look up a player's historical ranking over time or see their full match history?+
get_player_details returns current biographical data, and get_featured_players returns current ranking and season statistics — neither exposes historical ranking timelines or career match logs. You can fork this API on Parse and revise it to add endpoints targeting historical ranking or match history data.Does the event calendar cover all WTT event types, or only major championships?+
get_events returns all scheduled and completed events for the requested year, including event type via the EventType field. The response does not currently filter by tier or series, so all event categories in the calendar are included in a single array.Is there a way to search for players by name rather than by ITTF ID?+
get_player_details requires a known ittf_id, and get_featured_players returns a fixed set of featured athletes without a name-search parameter. You can fork this API on Parse and revise it to add a player search endpoint that accepts a name query.