
Live tennis scores, fixtures, players and rankings from the Live Tennis API, as tibbles.
Covers the ATP, WTA, Challenger and ITF tours, plus head-to-head records and the 1968 to 2022 results archive.
Website · Documentation · Pricing · Changelog · Get a free API key
# install.packages("remotes")
remotes::install_github("livetennisapi/livetennisapi-r")
Get a free key at livetennisapi.com/subscribe/free. No card is needed. Put it in ~/.Renviron so every session has it:
LIVETENNISAPI_KEY=twjp_...
You can also pass key to any function that needs one. It wins over the environment.
library(livetennisapi)
live <- live_matches(tour = "atp")
if (nrow(live) > 0) {
print(live[, c("id", "tournament", "players.p1.name", "players.p2.name")])
match_score(live$id[1])
}
search_players("sinner")
list_fixtures(tour = "wta", limit = 20)
The results archive (1968 to 2022) and head-to-head records are on the Basic plan and up:
finals <- archive_matches(tour = "atp", name = "federer", round = "F", level = "G")
head_to_head("djokovic", "nadal")$totals
Ranking tables are on the Pro plan and up. Elo ratings and per-player records come in through the same function:
rankings(system = "atp", limit = 100)
rankings(system = "elo", tour = "wta", surface = "clay")
The vignette Today's tennis fixtures in R walks through a full example. It reads the day's schedule, reshapes the tibble and charts fixtures by tour and hour with ggplot2. r-universe builds the rendered page from this repository.
List endpoints return a tibble with nested fields flattened into columns, such as players.p1.name. lta_meta(x) returns the paging details. To read a whole filtered set, raise offset by limit until lta_meta(x)$has_more is FALSE. Single resources come back as lists.
| Function | Endpoint | Returns |
|---|---|---|
api_health() |
GET /health (no key) |
list |
api_usage() |
GET /usage |
list |
live_matches(), list_matches()
|
GET /matches |
tibble |
get_match(), match_score()
|
GET /matches/{id}, /score
|
list |
list_fixtures() |
GET /fixtures |
tibble |
search_players() |
GET /players |
tibble |
get_player(), player_stats()
|
GET /players/{id}, /stats
|
list |
list_tournaments() |
GET /tournaments |
tibble |
get_tournament() |
GET /tournaments/{id} |
list |
archive_matches(), archive_players()
|
GET /history/archive/... |
tibble |
archive_career() |
GET /history/archive/career |
list |
head_to_head() |
GET /h2h |
list |
rankings() |
GET /rankings |
tibble |
lta_get() |
any endpoint | list |
The free plan opens live and upcoming matches, scores, players, fixtures and tournaments, at 30 requests a minute and 100 a day. Each paid plan adds more, and the pricing page lists what each one opens. A call your plan does not cover raises lta_plan_error.
lta_get() calls any endpoint in the API reference that has no wrapper yet.
A failed call raises a condition of class lta_error, with a subclass you can catch on its own:
| Class | When |
|---|---|
lta_auth_error |
401: the key is missing, wrong or revoked |
lta_plan_error |
403: the endpoint needs a higher plan |
lta_rate_limited |
429: a rate limit or the daily quota was reached |
lta_abuse_throttled |
429 abuse_throttled: a 24-hour block, also an lta_rate_limited
|
lta_not_found |
404 |
lta_bad_request |
400: a parameter the API refused |
lta_gone |
410: the record was merged into another, which the body names |
lta_connection_error |
the API could not be reached, after three tries |
lta_http_error |
any other failure, such as a 5xx after three tries |
tryCatch(rankings(system = "atp"),
lta_plan_error = function(e) message("Rankings need the PRO plan"))
Each condition carries status, code (the API's own error code), body and retry_after.
A call is tried up to three times, each with a 30-second timeout. Dropped connections, timeouts, server errors (5xx) and the per-minute 429 are retried. The client waits what the Retry-After header asks for, up to a minute, or backs off briefly when there is no header. The daily-quota 429 and abuse_throttled are raised straight away, because neither clears in seconds. The Python and JavaScript clients follow the same policy.
The same API has official clients for Python, JavaScript and TypeScript, Go, PHP, .NET, Dart and Swift, and an MCP server.
Package releases are listed in NEWS.md. Changes to the API itself are in the API changelog.
MIT. Built by Live Tennis API.