diff --git a/CHANGELOG.md b/CHANGELOG.md index 36fd262..04859cc 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,6 +5,11 @@ All notable changes to the specification are recorded here. The API surface is versioned as `v1`. Changes within `v1` are **additive only**; removing a field or changing its type would require `v2`. +## [1.13.83] - 2026-11-12 + +### Added +- **A client libraries page.** `client-libraries.html` lists the eight official language clients and seven packages built on them. Each row has the install command, the latest published version, the minimum runtime, the licence and the source repository. A second table says whether each package covers REST, the live stream, file export and MCP. A third shows which endpoint groups each language client reaches, read from the source of each published version. The page ends with the smallest working call in each language, copied from that library's README. `scripts/check_client_versions.py` reads the registries again and names any row that is behind. The build fails when the page names an operation the spec does not define. The docs menu, the docs home, the sitemap, llms.txt and the README link the page. Nothing on the wire changed. + ## [1.13.82] - 2026-11-12 ### Fixed diff --git a/README.md b/README.md index 84e3218..1387826 100644 --- a/README.md +++ b/README.md @@ -136,6 +136,8 @@ Everything in the Live Tennis API developer surface: | Vercel AI SDK tools | `npm install livetennisapi-ai` ([guide](https://docs.livetennisapi.com/ai-sdk.html)) | [repo](https://github.com/livetennisapi/livetennisapi-ai) | [package](https://www.npmjs.com/package/livetennisapi-ai) | | CSV, JSON Lines and Parquet export | `pip install livetennisapi-export` ([guide](https://docs.livetennisapi.com/export-formats.html)) | [repo](https://github.com/livetennisapi/livetennisapi-export) | [package](https://pypi.org/project/livetennisapi-export/) | +The [client libraries page](https://docs.livetennisapi.com/client-libraries.html) lists every client library with its latest version and minimum runtime. It also shows which endpoints each language client covers. + - **API reference** — ([plain-HTML version](https://docs.livetennisapi.com/reference.html), no JavaScript required) - **Website and plans** — - **Get a free key** — diff --git a/docs/ai-sdk.html b/docs/ai-sdk.html index 013965e..1a71937 100644 --- a/docs/ai-sdk.html +++ b/docs/ai-sdk.html @@ -200,7 +200,7 @@ -
Live Tennis API DocsGet a free key
Explore the documentation
+
Live Tennis API DocsGet a free key
Explore the documentation

Live Tennis API · docs · guide

@@ -317,6 +317,7 @@ Tennis API authentication, quota and status Errors and rate limits Export tennis data to CSV, JSON Lines or Parquet +Live Tennis API client libraries

Written for livetennisapi-ai 1.3.0. Package source in livetennisapi/livetennisapi-ai, page source in livetennisapi/openapi.

Built by Synapse Research Ltd.

diff --git a/docs/auth-quota-and-health.html b/docs/auth-quota-and-health.html index 5d90c05..69e0019 100644 --- a/docs/auth-quota-and-health.html +++ b/docs/auth-quota-and-health.html @@ -199,10 +199,10 @@ -
Live Tennis API DocsGet a free key
Explore the documentation
+
Live Tennis API DocsGet a free key
Explore the documentation
-

Live Tennis API · docs · version 1.13.82

+

Live Tennis API · docs · version 1.13.83

Tennis API authentication, quota and status

How do you authenticate, and how do you see what quota is left? Send your key as X-API-Key on every request. GET /usage returns your own consumption against your plan's quota and works on every tier including FREE, so a client can check its own headroom before a burst. GET /health is the unauthenticated liveness probe.

2 endpoints on this page. Base URL @@ -254,6 +254,7 @@

Example

curl https://api.livetennisapi.com/api/public/v1/usag
 Live Tennis API tools for the Vercel AI SDK
 Errors and rate limits
 Export tennis data to CSV, JSON Lines or Parquet
+Live Tennis API client libraries
 
 

Generated from openapi.yaml by livetennisapi/openapi. Every endpoint on diff --git a/docs/broadcast-graphics.html b/docs/broadcast-graphics.html index e762aef..85e35c7 100644 --- a/docs/broadcast-graphics.html +++ b/docs/broadcast-graphics.html @@ -199,10 +199,10 @@ -

Live Tennis API DocsGet a free key
Explore the documentation
+
Live Tennis API DocsGet a free key
Explore the documentation
-

Live Tennis API · docs · version 1.13.82

+

Live Tennis API · docs · version 1.13.83

Tennis scores for on-air graphics

How do you put live tennis scores into a broadcast graphics template? GET /broadcast/match/{matchId} returns ONE flat object for one match and GET /broadcast/live the same object for every live match in a single call. Both are ULTRA. A graphics template binds each field to a fixed path, so three things are contractual: the object is flat, every key is present on every read (null, never missing), and the score is already in display form — p1_points reads "40" or "AD" and set_line is one string. Built for 1 Hz: every response carries a strong ETag, so If-None-Match makes an unchanged state a 304 with no body. Detect a new state on sequence, never on served_at, which changes on every read.

2 endpoints on this page. Base URL @@ -274,6 +274,7 @@

Example

curl https://api.livetennisapi.com/api/public/v1/broa
 Live Tennis API tools for the Vercel AI SDK
 Errors and rate limits
 Export tennis data to CSV, JSON Lines or Parquet
+Live Tennis API client libraries
 
 

Generated from openapi.yaml by livetennisapi/openapi. Every endpoint on diff --git a/docs/changelog.html b/docs/changelog.html index 5eab430..58b69cf 100644 --- a/docs/changelog.html +++ b/docs/changelog.html @@ -4,7 +4,7 @@ Live Tennis API — Changelog - + @@ -14,7 +14,7 @@ @@ -199,13 +199,18 @@ -

Live Tennis API DocsGet a free key
Explore the documentation
+
Live Tennis API DocsGet a free key
Explore the documentation

Live Tennis API · docs

Changelog

-

Every change to the specification, dated and versioned. The API surface is v1; changes within it are additive only. Current version 1.13.82, last change . Also as the full reference, OpenAPI YAML / JSON, and the dated facts file.

+

Every change to the specification, dated and versioned. The API surface is v1; changes within it are additive only. Current version 1.13.83, last change . Also as the full reference, OpenAPI YAML / JSON, and the dated facts file.

+

1.13.83

+

Added

+
    +
  • A client libraries page. client-libraries.html lists the eight official language clients and seven packages built on them. Each row has the install command, the latest published version, the minimum runtime, the licence and the source repository. A second table says whether each package covers REST, the live stream, file export and MCP. A third shows which endpoint groups each language client reaches, read from the source of each published version. The page ends with the smallest working call in each language, copied from that library's README. scripts/check_client_versions.py reads the registries again and names any row that is behind. The build fails when the page names an operation the spec does not define. The docs menu, the docs home, the sitemap, llms.txt and the README link the page. Nothing on the wire changed.
  • +

1.13.82

Fixed

    diff --git a/docs/client-libraries.html b/docs/client-libraries.html new file mode 100644 index 0000000..bf99eda --- /dev/null +++ b/docs/client-libraries.html @@ -0,0 +1,474 @@ + + + + + +Tennis API client libraries and SDKs | Live Tennis API + + + + + + + + + + + + + + + + + + + + + +
    Live Tennis API DocsGet a free key
    Explore the documentation
    +
    +
    +

    Live Tennis API · docs · guide

    +

    Live Tennis API client libraries

    +

    Which client libraries does the Live Tennis API have? There are official clients for Python, JavaScript and TypeScript, Go, PHP, .NET, Dart, R and Swift. Seven more packages build on them, among them an MCP server and an export command. The tables list the install command, the latest version and the coverage of each.

    +

    Versions read from each registry on . Coverage read from the source of each published version.

    + +
    +
    +

    Which client library should I use?

    +

    Pick the row for your language. Every package calls the same REST API with the same key. +The version is the newest release on the registry named under each install command. +These client libraries are the official SDKs for the API.

    +
    + + + + + + + + + + + + + + +
    Every official client library and tool, with its install command and version
    LibraryLatest versionMinimum runtimeInstall and packageLanguageLicenceSource
    Python client1.8.0Python 3.9pip install livetennisapi
    livetennisapi on PyPI
    PythonMITGitHub
    JavaScript and TypeScript client1.10.2Node 18npm install livetennisapi
    livetennisapi on npm
    JavaScript, TypeScriptMITGitHub
    Go client1.2.1Go 1.25go get github.com/livetennisapi/livetennisapi-go
    github.com/livetennisapi/livetennisapi-go on Go modules
    GoMITGitHub
    PHP client1.1.1PHP 8.1composer require livetennisapi/livetennisapi
    livetennisapi/livetennisapi on Packagist
    PHPMITGitHub
    .NET client1.2.1.NET Standard 2.0 or .NET 8dotnet add package LiveTennisApi
    LiveTennisApi on NuGet
    C#MITGitHub
    Dart and Flutter client1.2.1Dart 3.5dart pub add livetennisapi
    livetennisapi on pub.dev
    DartMITGitHub
    Swift client1.1.1Swift 5.9.package(url: "https://github.com/livetennisapi/livetennisapi-swift.git", from: "1.1.1")
    livetennisapi-swift on Git tag
    SwiftMITGitHub
    R client0.2.0R 4.1install.packages("livetennisapi", repos = c("https://livetennisapi.r-universe.dev", "https://cloud.r-project.org"))
    livetennisapi on R-universe
    RMITGitHub
    MCP server1.6.5Node 20npx -y livetennisapi-mcp
    livetennisapi-mcp on npm
    TypeScriptMITGitHub
    Vercel AI SDK tools1.3.0Node 22npm install livetennisapi-ai
    livetennisapi-ai on npm
    TypeScriptMITGitHub
    Export command0.1.0Python 3.9pip install livetennisapi-export
    livetennisapi-export on PyPI
    PythonMITGitHub
    Laravel package1.1.0PHP 8.2composer require livetennisapi/livetennisapi-laravel
    livetennisapi/livetennisapi-laravel on Packagist
    PHPMITGitHub
    Haystack integration0.2.0Python 3.10pip install livetennisapi-haystack
    livetennisapi-haystack on PyPI
    PythonMITGitHub
    LangChain integration0.2.0Python 3.10pip install -U langchain-livetennis
    langchain-livetennis on PyPI
    PythonMITGitHub
    LlamaIndex tools0.1.0Python 3.10pip install llama-index-tools-livetennisapi
    llama-index-tools-livetennisapi on PyPI
    PythonMITGitHub
    +

    Every package is MIT licensed. Plugins for apps and automation platforms are not in this table. +They live in the GitHub organisation.

    + +

    Which libraries support REST, the live stream, file export and MCP?

    +

    Every library reads the REST API. Two open the live stream, one writes files and one is an MCP server.

    +
    + + + + + + + + + + + + + + +
    Which parts of the API each library covers
    LibraryRESTLive streamFile exportMCP
    Python clientYesYesNoNo
    JavaScript and TypeScript clientYesYesNoNo
    Go clientYesToken onlyNoNo
    PHP clientYesToken onlyNoNo
    .NET clientYesToken onlyNoNo
    Dart and Flutter clientYesToken onlyNoNo
    Swift clientYesToken onlyNoNo
    R clientYesNoNoNo
    MCP serverYesNoNoYes
    Vercel AI SDK toolsYesNoNoNo
    Export commandYesNoCSV, JSON Lines, ParquetNo
    Laravel packageYesToken onlyNoNo
    Haystack integrationYesNoNoNo
    LangChain integrationYesNoNoNo
    LlamaIndex toolsYesNoNoNo
    +

    Live stream says whether the package opens the WebSocket feed for you. The Python and +JavaScript clients do. In Python, pip install "livetennisapi[all]" adds the WebSocket feed.

    +

    Token only means the client calls GET /ws-token for a push feed token. +You open the socket with your own WebSocket library. The +push feed and webhooks page describes the frames.

    +

    The MCP server also runs hosted at https://mcp.livetennisapi.com/mcp, with nothing to install. +The AI SDK guide and the export guide +cover those two packages in full.

    +

    Which endpoints does each client cover?

    +

    The eight language clients do not all reach the same endpoints. Each cell was read from the source +of the published version in the first table.

    +
    + + + + + + + + + + + + + + +
    Endpoint groups and the language clients that cover them
    EndpointsPythonJSGoPHP.NETDartSwiftRPaths
    Matches and live scoresYesYesYesYesYesYesYesYes/matches
    /matches/{matchId}
    /matches/{matchId}/score
    Players, fixtures and tournamentsYesYesYesYesYesYesYesYes/players
    /players/{playerId}
    /fixtures
    /tournaments
    /tournaments/{tournamentId}
    Player recordNoYesNoNoNoNoNoYes/players/{playerId}/stats
    RankingsYesYesYesYesYesYesYesYes/rankings
    Results archive and head-to-headYesYesYesYesYesYesYesPart/history/archive/matches
    /history/archive/matches/{archiveId}
    /history/archive/players
    /history/archive/career
    /h2h
    Completed matches and the point-by-point tapeYesYesYesYesYesYesYesNo/history/matches
    /history/matches/{matchId}
    History coverage reportYesYesNoNoNoNoNoNo/history/coverage
    Match events, statistics and analysisYesYesYesYesYesYesYesNo/matches/{matchId}/events
    /matches/{matchId}/statistics
    /matches/{matchId}/analysis
    Per-point events over RESTYesYesNoNoNoNoNoNo/matches/{matchId}/points
    Markets and pricesYesYesYesYesYesYesYesNo/markets
    /markets/{matchId}/prices
    Rally and charting dataYesYesYesYesYesYesYesNo/rally/matches
    /rally/matches/{rallyMatchId}
    /history/matches/{matchId}/rally
    /charting/players
    /charting/matches/{chartingMatchId}
    History packagesYesYesYesYesYesYesYesNo/history/packages
    /history/packages/{period}
    WebhooksNoNoYesYesYesYesYesNoPOST /webhooks
    /webhooks
    DELETE /webhooks/{webhookId}
    Push feed tokenYesYesYesYesYesYesYesNo/ws-token
    Usage and quotaYesNoYesYesYesYesYesYes/usage
    +

    Part for R means it lists archive results, players, careers and head-to-head records. +It has no call for a single archive result.

    +

    An endpoint with no method in your client is still one HTTP request away. The +reference lists every path. The +errors page says when to retry.

    + +

    What is the smallest working call in each language?

    +

    Each example lists live matches. Every call needs an API key, and +a free key is enough for these. The free plan has 100 requests a day.

    +

    Python

    +
    pip install livetennisapi
    +
    from livetennisapi import LiveTennisAPI
    +
    +with LiveTennisAPI(api_key="twjp_…") as client:   # or set LIVETENNISAPI_KEY
    +    for match in client.list_matches(status="live"):
    +        print(match.tournament, match.p1.name, "vs", match.p2.name, match.score.sets)
    +

    The client reads LIVETENNISAPI_KEY when you pass no key. The spec lets score be null, so check it before you read sets. The example is from the README of version 1.8.0.

    +

    JavaScript and TypeScript

    +
    npm install livetennisapi
    +
    import { LiveTennisAPI } from 'livetennisapi';
    +
    +const client = new LiveTennisAPI({ apiKey: 'twjp_…' });   // or $LIVETENNISAPI_KEY
    +
    +const { data } = await client.listMatches({ status: 'live' });
    +for (const match of data) {
    +  console.log(match.tournament, match.players?.p1?.name, 'vs', match.players?.p2?.name);
    +}
    +

    The package has no runtime dependencies and ships its own types. The example is from the README of version 1.10.2.

    +

    Go

    +
    go get github.com/livetennisapi/livetennisapi-go
    +
    package main
    +
    +import (
    +	"context"
    +	"fmt"
    +	"log"
    +	"os"
    +
    +	"github.com/livetennisapi/livetennisapi-go"
    +)
    +
    +func main() {
    +	client := livetennisapi.New(os.Getenv("LIVETENNISAPI_KEY"))
    +
    +	page, err := client.ListMatches(context.Background(), livetennisapi.ListMatchesParams{
    +		Status:     livetennisapi.StatusLive,
    +		ListParams: livetennisapi.ListParams{Limit: 10},
    +	})
    +	if err != nil {
    +		log.Fatal(err)
    +	}
    +
    +	for _, match := range page.Data {
    +		fmt.Printf("%-28s %s vs %s — %s\n",
    +			match.Tournament,
    +			match.Players.P1.Name,
    +			match.Players.P2.Name,
    +			match.Score, // nil-safe: prints "-" before a match starts
    +		)
    +	}
    +}
    +

    The module uses the standard library only. The example is from the README of version 1.2.1.

    +

    PHP

    +
    composer require livetennisapi/livetennisapi
    +composer require guzzlehttp/guzzle
    +
    use LiveTennisApi\LiveTennisApi;
    +
    +$client = new LiveTennisApi('twjp_…');      // or set LIVETENNISAPI_KEY
    +
    +foreach ($client->listMatches('live') as $match) {
    +    echo $match->tournament, ' [', $match->tour, ']: ',
    +         $match->p1()?->name, ' vs ', $match->p2()?->name, "\n";
    +
    +    // score is nullable — an upcoming match has none yet
    +    if ($match->score !== null) {
    +        // points are STRINGS ("40", "AD"); games are player-major per-set lists
    +        echo '  ', implode('-', $match->score->points), "\n";
    +    }
    +}
    +

    The client needs a PSR-18 HTTP client and PSR-17 factories. The second line installs Guzzle, which provides both. The example is from the README of version 1.1.1.

    +

    .NET

    +
    dotnet add package LiveTennisApi
    +
    using LiveTennisApi;
    +using LiveTennisApi.Models;
    +
    +using var client = new LiveTennisApiClient("twjp_your_key");
    +
    +var live = await client.ListMatchesAsync(MatchStatus.Live);
    +foreach (var m in live.Data)
    +{
    +    Console.WriteLine($"{m.Tournament}: {m.Players?.P1?.Name} vs {m.Players?.P2?.Name}");
    +}
    +

    The package targets .NET Standard 2.0 and .NET 8. The example is from the README of version 1.2.1.

    +

    Dart and Flutter

    +
    dart pub add livetennisapi
    +
    import 'package:livetennisapi/livetennisapi.dart';
    +
    +Future<void> main() async {
    +  final client = LiveTennisApi(apiKey: 'twjp_your_key');
    +  try {
    +    final page = await client.listMatches(status: MatchStatus.live);
    +    for (final match in page.data) {
    +      final s = match.score;
    +      final (g1, g2) = s?.gamesForSet(0) ?? (null, null);
    +      print('${match.tournament} [${match.tour}]: '
    +          '${match.p1?.name} vs ${match.p2?.name} '
    +          '(${g1 ?? '-'}-${g2 ?? '-'}, serving: ${s?.server ?? '—'})');
    +    }
    +  } on UpgradeRequiredException catch (e) {
    +    print('Needs the ${e.requiredTier} tier');
    +  } on RateLimitedException catch (e) {
    +    print('Slow down; retry after ${e.retryAfter}s');
    +  } finally {
    +    client.close();
    +  }
    +}
    +

    The package is pure Dart and depends only on package:http. The example is from the README of version 1.2.1.

    +

    Swift

    +
    .package(url: "https://github.com/livetennisapi/livetennisapi-swift.git", from: "1.1.1")
    +
    import LiveTennisApi
    +
    +let client = LiveTennisApiClient(apiKey: "twjp_your_key_here")
    +
    +let live = try await client.listMatches(status: .live, tour: .atp)
    +for match in live.data {
    +    let p1 = match.players?.p1?.name ?? "?"
    +    let p2 = match.players?.p2?.name ?? "?"
    +    print("\(match.tournament): \(p1) vs \(p2) — \(match.score?.description ?? "-")")
    +}
    +

    Add the first line to the dependencies in Package.swift. The package supports macOS 12, iOS 15, tvOS 15, watchOS 8 and Linux. The example is from the README of version 1.1.1.

    +

    R

    +
    install.packages("livetennisapi", repos = c("https://livetennisapi.r-universe.dev", "https://cloud.r-project.org"))
    +
    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)
    +

    List functions return a tibble. Put the key in ~/.Renviron as LIVETENNISAPI_KEY. The example is from the README of version 0.2.0.

    + +

    How do I check that a version here is current?

    +

    The versions were read from the registries on +. The registry link under each +install command always shows the newest release.

    +

    The docs repository has a script, scripts/check_client_versions.py. It reads every +registry again and names each row that is behind.

    + + + +
    + +
    + + + + diff --git a/docs/errors-and-rate-limits.html b/docs/errors-and-rate-limits.html index 6fc0c34..a63aa08 100644 --- a/docs/errors-and-rate-limits.html +++ b/docs/errors-and-rate-limits.html @@ -200,7 +200,7 @@ -
    Live Tennis API DocsGet a free key
    Explore the documentation
    +
    Live Tennis API DocsGet a free key
    Explore the documentation

    Live Tennis API · docs · guide

    @@ -421,6 +421,7 @@ Tennis API authentication, quota and status Live Tennis API tools for the Vercel AI SDK Export tennis data to CSV, JSON Lines or Parquet +Live Tennis API client libraries

    Built from openapi.yaml. Page source in livetennisapi/openapi.

    Built by Synapse Research Ltd.

    diff --git a/docs/export-formats.html b/docs/export-formats.html index 3326d11..6d6fe4d 100644 --- a/docs/export-formats.html +++ b/docs/export-formats.html @@ -200,7 +200,7 @@ -
    Live Tennis API DocsGet a free key
    Explore the documentation
    +
    Live Tennis API DocsGet a free key
    Explore the documentation

    Live Tennis API · docs · guide

    @@ -423,6 +423,7 @@ Tennis API authentication, quota and status Live Tennis API tools for the Vercel AI SDK Errors and rate limits +Live Tennis API client libraries

    Written for livetennisapi-export 0.1.0. Package source in livetennisapi/livetennisapi-export, page source in livetennisapi/openapi.

    Built by Synapse Research Ltd.

    diff --git a/docs/historical-results-archive.html b/docs/historical-results-archive.html index 2e7f408..9e2b49f 100644 --- a/docs/historical-results-archive.html +++ b/docs/historical-results-archive.html @@ -199,10 +199,10 @@ -
    Live Tennis API DocsGet a free key
    Explore the documentation
    +
    Live Tennis API DocsGet a free key
    Explore the documentation
    -

    Live Tennis API · docs · version 1.13.82

    +

    Live Tennis API · docs · version 1.13.83

    Historical tennis results API — 1968 onward

    How far back does the historical tennis data go, and what is in it? The results archive covers 1968 to 2022: GET /history/archive/matches for results, /archive/players for bios, /archive/career for career aggregates and GET /h2h for head-to-head across both the archive and our own completed matches. All BASIC. Matches from 2013 onward additionally carry a reconstructed point-by-point tape at /archive/matches/{archiveId}/tape (ULTRA).

    6 endpoints on this page. Base URL @@ -314,6 +314,7 @@

    Example

    curl https://api.livetennisapi.com/api/public/v1/h2h
     Live Tennis API tools for the Vercel AI SDK
     Errors and rate limits
     Export tennis data to CSV, JSON Lines or Parquet
    +Live Tennis API client libraries
     
     

    Generated from openapi.yaml by livetennisapi/openapi. Every endpoint on diff --git a/docs/index.html b/docs/index.html index 9c0c2f0..102b5b7 100644 --- a/docs/index.html +++ b/docs/index.html @@ -345,7 +345,7 @@ -

    Live Tennis API DocsGet a free key
    Explore the documentation
    +
    Live Tennis API DocsGet a free key
    Explore the documentation
    @@ -389,9 +389,10 @@

    Tennis data.
    Start building.

    10 / AI SDKVercel AI SDK toolsGive a model live scores and history with livetennisapi-ai. 11 / ERRORSErrors & rate limitsEvery error code, what causes it and when to retry. 12 / EXPORTCSV, JSON Lines & ParquetExport matches, fixtures, players and rankings to a file. + 13 / CLIENTSClient librariesInstall commands, versions and coverage for eight languages. -
    Official clientspip install livetennisapinpm install livetennisapinpx livetennisapi-mcpnpm install livetennisapi-ai
    +
    Official clientspip install livetennisapinpm install livetennisapinpx livetennisapi-mcpnpm install livetennisapi-aiAll client libraries