GET
https://api.tennisdatabaseapi.com/v1/matchesEvery planMatches on a day, with scores and closing prices.
Free key yesterday on, no pricesLive 45 daysArchive every seasonComplete everything
Try itRuns against the live API with your key. Your key stays in this browser.API
GEThttps://api.tennisdatabaseapi.com/v1/matches?date=2026-11-17&tour=men&per_page=2
1Parameters
| Name | What it is |
|---|---|
date | YYYY-MM-DD, today or yesterday (default today). |
tour | Men or women: men, women. |
tier | The level of the event: slam, tour, challenger, itf, utr, team, other. |
tournament | A tournament id. |
page, per_page | Paging: 50 a page unless you ask, at most 50. See Paging. |
cursor | The meta.next_cursor of the page before, to walk a long list. |
Anything else in the address answers 422 unknown_parameter, with the list of parameters this endpoint takes.
2Request
curl -H "Authorization: Bearer $TDA_KEY" \ "https://api.tennisdatabaseapi.com/v1/matches?date=2026-11-17&tour=men&per_page=2"
$ch = curl_init('https://api.tennisdatabaseapi.com/v1/matches?date=2026-11-17&tour=men&per_page=2'); curl_setopt_array($ch, [ CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('TDA_KEY')], CURLOPT_RETURNTRANSFER => true, ]); $answer = json_decode(curl_exec($ch), true); print_r($answer['data']);
import os, requests r = requests.get( "https://api.tennisdatabaseapi.com/v1/matches?date=2026-11-17&tour=men&per_page=2", headers={"Authorization": f"Bearer {os.environ['TDA_KEY']}"}, ) print(r.json()["data"])
const r = await fetch("https://api.tennisdatabaseapi.com/v1/matches?date=2026-11-17&tour=men&per_page=2", { headers: { Authorization: `Bearer ${process.env.TDA_KEY}` }, }); const { data } = await r.json(); console.log(data);
The code follows the form in Try it, with your key in it once you have entered one. Without a key it reads $TDA_KEY.
3Answer
{
"data": [
{
"id": "mt_e0sf3h8j",
"date": "2026-11-17",
"start_time": "2026-11-17T18:00:00Z",
"tour": "men",
"event_type": "singles",
"tournament": {
"id": "tn_ythr3e6z",
"name": "Champaign",
"event_known": true,
"tier": "challenger",
"season": 2026,
"surface": null
},
"round": "round_1",
"winner": { "id": "pl_9zfrnj8q", "name": "Artnak B.", "country": "Slovenia" },
"loser": { "id": "pl_b5brhyty", "name": "Wiedenmann L.", "country": "Germany" },
"score": "6-1 6-3",
"sets": { "winner": 2, "loser": 0 },
"status": "completed",
"best_of": null,
"ranks": { "winner": 435, "loser": 488 },
"ranking_points": { "winner": 107, "loser": 91 },
"odds": {
"closing": { "winner": 1.61, "loser": 2.2 }
}
},
{
"id": "mt_jan5eszj",
"date": "2026-11-17",
"start_time": "2026-11-17T21:35:00Z",
"tour": "men",
"event_type": "singles",
"tournament": {
"id": "tn_ythr3e6z",
"name": "Champaign",
"event_known": true,
"tier": "challenger",
"season": 2026,
"surface": null
},
"round": "round_1",
"winner": { "id": "pl_8twp6cq3", "name": "Lee J.", "country": "USA" },
"loser": { "id": "pl_m11am1e8", "name": "Heck H.", "country": "USA" },
"score": "6-1 6-3",
"sets": { "winner": 2, "loser": 0 },
"status": "completed",
"best_of": null,
"ranks": { "winner": 1163, "loser": 581 },
"ranking_points": { "winner": 12, "loser": 66 },
"odds": {
"closing": { "winner": 1.66, "loser": 2.13 }
}
}
],
"meta": {
"count": 2,
"next_cursor": "eyJvIjoyLCJwIjoyfQ",
"page": 1,
"per_page": 2,
"total": 240,
"total_pages": 120,
"next_page": 2,
"prev_page": null
}
}{
"data": [
{
"id": "mt_e0sf3h8j",
"date": "2026-11-17",
"start_time": "2026-11-17T18:00:00Z",
"tour": "men",
"event_type": "singles",
"tournament": {
"id": "tn_ythr3e6z",
"name": "Champaign",
"event_known": true,
"tier": "challenger",
"season": 2026,
"surface": null
},
"round": "round_1",
"winner": { "id": "pl_9zfrnj8q", "name": "Artnak B.", "country": "Slovenia" },
"loser": { "id": "pl_b5brhyty", "name": "Wiedenmann L.", "country": "Germany" },
"score": "6-1 6-3",
"sets": { "winner": 2, "loser": 0 },
"status": "completed",
"best_of": null,
"ranks": { "winner": 435, "loser": 488 },
"ranking_points": { "winner": 107, "loser": 91 },
"odds": {
"closing": { "winner": 1.61, "loser": 2.2 }
}
},
{
"id": "mt_jan5eszj",
"date": "2026-11-17",
"start_time": "2026-11-17T21:35:00Z",
"tour": "men",
"event_type": "singles",
"tournament": {
"id": "tn_ythr3e6z",
"name": "Champaign",
"event_known": true,
"tier": "challenger",
"season": 2026,
"surface": null
},
"round": "round_1",
"winner": { "id": "pl_8twp6cq3", "name": "Lee J.", "country": "USA" },
"loser": { "id": "pl_m11am1e8", "name": "Heck H.", "country": "USA" },
"score": "6-1 6-3",
"sets": { "winner": 2, "loser": 0 },
"status": "completed",
"best_of": null,
"ranks": { "winner": 1163, "loser": 581 },
"ranking_points": { "winner": 12, "loser": 66 },
"odds": {
"closing": { "winner": 1.66, "loser": 2.13 }
}
}
],
"meta": {
"count": 2,
"next_cursor": "eyJvIjoyLCJwIjoyfQ",
"page": 1,
"per_page": 2,
"total": 240,
"total_pages": 120,
"next_page": 2,
"prev_page": null
}
}{
"error": {
"code": "upgrade_required",
"message": "Your plan does not read matches on 2026-09-13.",
"plan": "Archive",
"upgrade": "https://tennisdatabaseapi.com/pricing",
"docs": "https://tennisdatabaseapi.com/documentation/errors"
}
}Real answers from the API, made 2026-11-18. Long lists are cut to three items here.
A field your plan does not include is still there, as
null, so code written on the free key keeps working after an upgrade. meta.held_back names what was held back and meta.note the plan that adds it.4Fields
| Field | What it holds |
|---|---|
id | The match id, mt_ and 8 characters |
date | The day it was played, UTC |
start_time | When play began (or is set to begin) on the match's date, UTC, as listed for that day; for a match finished on a later day, the time it resumed that day; null where not known |
tournament | id, name, event_known, tier, season, surface |
round | final, semi_final, quarter_final, round_of_16, round_1, qualifying and so on |
winner, loser | id, name, country |
score | The score from the winner's side, tie-breaks in brackets |
sets | Sets won by the winner and the loser |
status | completed, retired, walkover or defaulted |
best_of | 3 or 5 |
ranks | Each player's ranking on the day, where known |
ranking_points | Each player's ranking points on the day, where known (from the same weekly list as the ranking) |
odds.closing | The market's closing prices for the winner and the loser, decimal |
5Errors
bad_request | A value out of range, such as a date or a tier that is not one of the list. |
unauthorized | No key, or a key that is unknown or revoked. |
upgrade_required | A date outside your plan's window; the error names the plan that reads it. |
unknown_parameter | A parameter this endpoint does not take. |
rate_limited | Too many calls this minute, or the allowance used (quota_exceeded). |