--- name: tabletennisapi description: Professional table tennis data from Table Tennis API (tabletennisapi.com): live scores, official results with every game score, the event calendar and draws, players and head to head since December 2024. Use when a question needs real table tennis matches, results, players or events. --- # Table Tennis API A JSON API for professional table tennis: every event since December 2024, each match with its game scores, matches in play now, the calendar ahead, players and head to head. Run by DeveloperData.net. ## When to use it - Use it for facts about professional table tennis: who won, the score in games, what is being played now, what is on next, a player's matches, two players' meetings, the world rankings. - Do not use it for predictions, tips or betting prices: it holds facts only. Match history starts in December 2024, ranking history in October 2026. ## Getting access - Make a free key at https://tabletennisapi.com/signup (sign in with Google). Paid plans: https://tabletennisapi.com/pricing. - Send it in a header on every call: `Authorization: Bearer ` (or `X-API-Key: `). A key in the address is refused with 400. - Base address: `https://api.tabletennisapi.com/v1`. GET only. Every answer is `{"data": ..., "meta": {...}}`. - Ids never change and carry their type: events `ev_`, matches `mt_`, players `pl_`. ## The calls for the common questions ### Matches on a day, with game scores: `GET /v1/matches` Matches on a day or across dates, every event. Plans: Free key, Live, Archive, Complete. ```bash curl "https://api.tabletennisapi.com/v1/matches?date=2026-09-13" -H "Authorization: Bearer $TT_KEY" ``` ```json { "data": [ { "id": "mt_6twqf194", "event": { "id": "ev_w5hw10am", "name": "Champions Macao 2026 Presented by Galaxy Entertainment Group" }, "date": "2026-09-13", "start_time": "2026-09-13T03:00:00Z", "discipline": "WS", "age_group": null, "para_class": null, "round": "semi_final", "round_name": "Semi-finals", "...": "..." } ], "meta": { "count": 2, "next_cursor": "eyJvIjoyLCJwIjoyfQ", "page": 1, "per_page": 2 } } ``` ### One match in full: `GET /v1/matches/{id}` One match: players, score, every game, length, table, format, real start, timeouts and cards. Plans: Free key, Live, Archive, Complete. ```bash curl "https://api.tabletennisapi.com/v1/matches/mt_fs5ttbe2" -H "Authorization: Bearer $TT_KEY" ``` ```json { "data": { "id": "mt_fs5ttbe2", "event": { "id": "ev_w5hw10am", "name": "Champions Macao 2026 Presented by Galaxy Entertainment Group" }, "date": "2026-09-13", "start_time": "2026-09-13T10:30:00Z", "discipline": "WS", "age_group": null, "para_class": null, "round": "final", "round_name": "Final", "...": "..." } } ``` ### Matches being played now: `GET /v1/live` Matches being played now, with the game in progress. Refreshed about every 10 seconds. Plans: Live, Complete. ```bash curl "https://api.tabletennisapi.com/v1/live" -H "Authorization: Bearer $TT_KEY" ``` Answers with a list of `Match` objects; the fields are in the manual. ### Yesterday's official results: `GET /v1/results/yesterday` Yesterday's finished matches, every event. On every plan. Plans: Free key, Live, Archive, Complete. ```bash curl "https://api.tabletennisapi.com/v1/results/yesterday" -H "Authorization: Bearer $TT_KEY" ``` Answers with a list of `Match` objects; the fields are in the manual. ### Find a player by name: `GET /v1/players` Find players by name or country. Plans: Free key, Live, Archive, Complete. ```bash curl "https://api.tabletennisapi.com/v1/players?q=Harimoto" -H "Authorization: Bearer $TT_KEY" ``` ```json { "data": [ { "id": "pl_51t63nz3", "name": "Harimoto Miwa", "country": "JPN" } ], "meta": { "count": 2, "next_cursor": null, "page": 1, "per_page": 2 } } ``` ### A player's matches: `GET /v1/players/{id}/matches` A player's matches, newest first, singles and doubles. Plans: Live, Archive, Complete. ```bash curl "https://api.tabletennisapi.com/v1/players/pl_51t63nz3/matches" -H "Authorization: Bearer $TT_KEY" ``` ```json { "data": [ { "id": "mt_fs5ttbe2", "event": { "id": "ev_w5hw10am", "name": "Champions Macao 2026 Presented by Galaxy Entertainment Group" }, "date": "2026-09-13", "start_time": "2026-09-13T10:30:00Z", "discipline": "WS", "age_group": null, "para_class": null, "round": "final", "round_name": "Final", "...": "..." } ], "meta": { "count": 2, "next_cursor": "eyJvIjoyLCJwIjoyfQ", "page": 1, "per_page": 2 } } ``` ### Two players' meetings: `GET /v1/h2h/{a}/{b}` Two players against each other: wins, games, and every meeting. Plans: Live, Archive, Complete. ```bash curl "https://api.tabletennisapi.com/v1/h2h/pl_51t63nz3/pl_yp1ww51h" -H "Authorization: Bearer $TT_KEY" ``` ```json { "data": [ { "id": "mt_y4m2qe95", "event": { "id": "ev_5mgjtt6p", "name": "China Smash 2026 Presented by Beijing Shijingshan Culture & Tourism Group" }, "date": "2026-10-07", "start_time": "2026-10-07T12:55:00Z", "discipline": "XD", "age_group": null, "para_class": null, "round": "quarter_final", "round_name": "Quarter-finals", "...": "..." } ], "meta": { "count": 2, "next_cursor": "eyJvIjoyLCJwIjoyfQ", "page": 1, "per_page": 2 } } ``` ### The world rankings: `GET /v1/rankings` World rankings: the top 100 of a list for a week, with points and movement. The latest week unless you ask for one. Plans: Free key, Live, Archive, Complete. ```bash curl "https://api.tabletennisapi.com/v1/rankings?discipline=WS" -H "Authorization: Bearer $TT_KEY" ``` ```json { "data": [ { "rank": 1, "previous_rank": 3, "movement": 2, "points": 6930, "player": { "id": "pl_5p9a00yg", "name": "Matsushima Sora", "country": "JPN" }, "partner": null, "age_group": "U19" } ], "meta": { "week": "2026-41", "published": "2026-10-05", "discipline": "MS", "doubles": null } } ``` ### Events in a date range: `GET /v1/events` Events: past, running and scheduled, newest first. Plans: Free key, Live, Archive, Complete. ```bash curl "https://api.tabletennisapi.com/v1/events?from=2026-09-13&to=2026-09-13" -H "Authorization: Bearer $TT_KEY" ``` ```json { "data": [ { "id": "ev_c9k4098k", "name": "Contender Panagyurishte 2026 Presented by ASAREL", "start_date": "2026-09-08", "end_date": "2026-09-13", "venue": "Arena Asarel", "city": "Panagyurishte", "country": "BUL", "tier": 2, "utc_offset_min": 180, "...": "..." } ], "meta": { "count": 2, "next_cursor": null, "page": 1, "per_page": 2 } } ``` Every endpoint, filter and field: https://tabletennisapi.com/documentation/manual.md (one markdown file) and https://tabletennisapi.com/openapi.json. ## MCP server - Address: `https://tabletennisapi.com/mcp/`, or `https://tabletennisapi.com/mcp` with the key in an `Authorization: Bearer` header. Streamable HTTP, JSON-RPC 2.0. - Tools (14): `find_events`, `get_event`, `event_matches`, `find_matches`, `get_match`, `match_points`, `live_matches`, `results_yesterday`, `find_players`, `get_player`, `player_matches`, `head_to_head`, `world_rankings`, `player_rankings`. Each calls the API with the caller's key, on the caller's plan. - Setup for Claude, ChatGPT and Cursor: https://tabletennisapi.com/mcp ## Limits - **Free key**: 10 calls a minute, 50 a day; yesterday, today and the calendar ahead; 11 of 15 endpoints. - **Live**: 60 calls a minute, 20,000 a day; 1 January this year onward, today and the calendar ahead; every endpoint. - **Archive**: 60 calls a minute, 20,000 a day; all history (since December 2024), up to yesterday; 14 of 15 endpoints. - **Complete**: 120 calls a minute, 50,000 a day; all history (since December 2024), today and the calendar ahead; every endpoint. - The Free key returns `games`, `duration_s`, `table` as null, with a note in `meta`. - `GET /v1/usage` shows your plan, calls today and limits, and is never counted. Every answer carries `X-RateLimit-Limit`, `X-RateLimit-Remaining` and `X-RateLimit-Reset`; daily allowances reset at 00:00 UTC. - Lists page with `per_page` (default 50, at most 200) and `page` or `cursor`. Times are UTC; `date` filters use the local day of play. ## Errors Every error is `{"error": {"code": "...", "message": "...", "docs": "https://tabletennisapi.com/documentation/errors"}}`. The message says what to change. - `400 bad_request`: A value is malformed, a required filter is missing, or the key was put in the address. - `401 unauthorized`: No key, or a key that is not recognised or has been revoked. - `403 upgrade_required`: The endpoint or the dates are outside your plan; the message names the plans that include it, and pricing links to them. - `404 not_found`: No such endpoint, or no match, event or player with that id. - `405 bad_request`: The API answers GET only. - `422 unknown_parameter`: A filter name the endpoint does not take; the message lists the ones it does. - `429 rate_limited`: Too many calls this minute; wait for Retry-After. - `429 quota_exceeded`: Today's allowance is used; it resets at 00:00 UTC (resets_at). - `500 server_error`: Our fault, already logged; try again shortly. ## A typical workflow 1. Call `GET /v1/usage` once to see the plan and the dates it reads. 2. Find ids: `GET /v1/players?q=` for a player, `GET /v1/events?q=` for an event. 3. Fetch what was asked: `GET /v1/matches?date=YYYY-MM-DD`, `GET /v1/players/{id}/matches`, `GET /v1/h2h/{a}/{b}` or `GET /v1/live`. 4. For one match in full, `GET /v1/matches/{id}` with its `mt_` id. 5. On `403 upgrade_required`, tell the user which plan includes it (the message names them); on `429`, wait for `Retry-After`.