LiveTennisApi 1.2.1

LiveTennisApi — .NET client for the Live Tennis API

Official .NET client for the Live Tennis API — real-time tennis scores, players, fixtures, deep match history and (on paid tiers) head-to-head, the 1968–2022 results archive, rankings, in-play statistics, rally/charting shot data, match events, market prices, webhooks and model analysis for ATP, WTA, Challenger, ITF and juniors.

• Multi-targeted: netstandard2.0 (Framework, Xamarin, Unity, older Core) and net8.0.
• HttpClient- and IHttpClientFactory-friendly, fully async with CancellationToken support.
• Typed models with correct nullability, and a typed exception hierarchy.
• Tolerant by design: unknown JSON fields are preserved, never rejected — additive changes ship within v1.

Install

dotnet add package LiveTennisApi

Quickstart

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}");
}

Get a free key (no card, 100 requests/day) at https://livetennisapi.com/subscribe/free. On a free key, poll no faster than every ~15 minutes; an always-on dashboard belongs on BASIC.

With IHttpClientFactory

Hand the client an HttpClient and it will not dispose it — the factory owns its lifetime:

services.AddHttpClient();

// elsewhere:
var http = httpClientFactory.CreateClient();
var client = new LiveTennisApiClient(http, "twjp_your_key");

Options

var client = new LiveTennisApiClient("twjp_your_key", new LiveTennisApiClientOptions
{
    AuthHeader = AuthHeader.Bearer, // or AuthHeader.ApiKey for X-API-Key
    Timeout = TimeSpan.FromSeconds(30),
    MaxRetries = 2,                 // 429 and 5xx only
});

Endpoints

¹ status=completed needs BASIC+ (or any History plan). ² Or any History plan — History grants work on a FREE core key. ³ kind=rankings, kind=rally and year= listings need ULTRA / History Business / a 1-year package; kind=archive shares the tape entitlement. The yearly kinds (rally, archive) use bare-year YYYY periods. ⁴ Direct keys only — a marketplace (RapidAPI) key gets 403 direct_key_required.

This covers every path of the public v1 OpenAPI spec. Deliberate exclusions: the undocumented gateway aliases (unstable, do not use); the server's HTML views and static assets (browser surfaces, not API); and the package file downloads — GetHistoryPackageAsync returns the manifest (filenames, sizes, SHA-256); stream the file itself with GET /history/packages/{period}?format=jsonl|csv using your own HTTP client, since a multi-GB download does not belong behind a JSON deserializer.

Quotas

Every response carries X-RateLimit-Limit / X-RateLimit-Remaining / X-RateLimit-Reset headers, and 429s carry Retry-After. The daily window resets at the absolute instant given in the daily-429 body's resets_at (surfaced as RateLimitedException.ResetsAt) — it is derived from the account's local midnight, not from any fixed UTC time, so always read the instant rather than assuming one.

Auth

Authorization: Bearer twjp_... is the preferred scheme (the default); X-API-Key: twjp_... also works via AuthHeader.ApiKey. Only /health is unauthenticated.

Reading a score — gotchas the models encode

var score = (await client.GetMatchScoreAsync(matchId));

• Points are strings — "0", "15", "30", "40", "AD", not integers.
• Games is player-major: [games_p1, games_p2], and each side is a per-set list. [[6,3,2],[4,6,1]] reads 6-4, 3-6, 2-1. Use score.GamesForSet(setIndex) instead of indexing by hand.
• Server is nullable (int?) — null between points and on a finished match.
• Match.Score is nullable — an upcoming match has no score yet.
• WinProbabilityP1 / Danger are populated on the ULTRA tier only.

Match metadata

• Match.Tour is the filter vocabulary (atp, wta, challenger, itf, juniors) and is safe to group on; null means the feed never stated a tour (exhibitions, team and mixed events). Match.TournamentId is a stable tournament identity; Match.RoundCode is the normalized round.
• On completed matches that ended early, Match.EventStatus says how (Retired, Walk Over, …) and Match.Withdrew says which player retired/conceded (1/2).

The tape (point-by-point history)

GetMatchTapeAsync(matchId, TapeSequence.Clean) returns one row per distinct score state — and only clean rows carry PointWinner (who won the point; null on gaps and the first row, never guessed). The response also carries per-set tiebreak final scores (Tiebreaks) from observed states only. A null row Timestamp marks a reconstructed row. Check Meta.Coverage / Meta.PointSource before backtesting — tapes are not guaranteed to cover the whole match. Works on live matches too.

Players and doubles

• Player.Tour is the record's own granular tour string (for example juniors_boys), and a doubles team reports it UPPERCASE (ATP). It is an opaque string — do not confuse it with the Tour request filter enum or with Match.Tour.
• On a doubles team, DataCompleteness.Known and .Of are null (per-player biography does not apply — distinct from 0), and .Note explains why.

Filters

• Tour enum: Atp, Wta, Challenger, Itf, Juniors. An unrecognised wire value is a 400 (BadRequestException), never a silent pass-through.
• players: accepts up to 50 ids (either participant matches; the client rejects more before the wire). from:/to: take YYYY-MM-DD or ISO 8601 datetimes. country: takes the lowercase 3-letter code the Player.Country field returns (IOC-style, e.g. ned, sui — not ISO-3166).
• Archive and h2h endpoints key on names (archive people have no roster ids); a fragment matching more than one player is a 400 ambiguous_name listing the candidates.

Note: /fixtures (ListFixturesAsync) currently also returns some already finished matches (Status == "finished"). This is a known upstream quirk; the client passes it through unfiltered.

Webhooks (ULTRA, direct keys only)

The API POSTs the same frames the WebSocket sends to your HTTPS endpoint on every live score commit:

var hook = await client.CreateWebhookAsync(
    "https://example.com/hooks/tennis",
    new[] { WebhookEvent.Score, WebhookEvent.BreakPoint });

// hook.Secret is shown EXACTLY ONCE, on this response — store it now.
// ListWebhooksAsync() never returns it again.

• Max 3 webhooks per key — a fourth registration throws ConflictException (409 webhook_limit); delete one first.
• The registration POST is never retried automatically, so a transient failure cannot register the same webhook twice.
• Verify deliveries against the stored signing secret.

Errors

Everything derives from LiveTennisApiException (carrying StatusCode, Code, Body, Headers, RequestUri). The common cases are distinguishable by type:

try
{
    var analysis = await client.GetMatchAnalysisAsync(matchId);
}
catch (AbuseThrottledException ex)       // 429 abuse_throttled — 24h block
{
    // Fix the retry loop; blocked until ex.RetryAt (from retry_at_epoch).
}
catch (RateLimitedException ex)          // 429
{
    if (ex.ResetsAt is not null)
    {
        // Daily quota — resets at the absolute instant from the body.
        var resumeAt = ex.ResetsAtTime;
    }
    else
    {
        await Task.Delay(TimeSpan.FromSeconds(ex.RetryAfterSeconds ?? 60));
    }
}
catch (UpgradeRequiredException ex)      // 403 — tier too low
{
    Console.WriteLine(ex.RequiredTier);  // e.g. "ULTRA"
}
catch (UnauthorizedException)            // 401 — bad/missing key
{
}

Transient failures (429, 5xx) are retried automatically (default 2 attempts), honouring Retry-After — except a 429 whose Retry-After exceeds 60 s (a daily/abuse block), which is surfaced immediately rather than retried against. POST requests (webhook registration) are never retried; GET and DELETE are.

Links

• Docs: https://docs.livetennisapi.com
• Free API key: https://livetennisapi.com/subscribe/free
• Discord: https://discord.gg/f8WUZHgDm6
• GitHub org: https://github.com/livetennisapi

License

MIT — see LICENSE.

Affiliate program

Know developers who need tennis data? The affiliate program pays 51% recurring commission for the life of every referred subscription — 30-day cookie, and the people you refer get 10% off.