Head-to-head across the results archive (1968–2022) and our own completed matches (2023→now) (BASIC)

The record between two players, assembled from BOTH halves of the product: the results archive, where the winner is a stored column, and our own completed matches, where the winner is derived from the final recorded state. Names are the keys — archive people have no roster ids. A fragment matching more than one player is refused with the candidate list (400 ambiguous_name), because two people summed into one record is a wrong answer, not a convenience. Passing a name EXACTLY selects that person, even where a longer name contains it, so Carlos Alcaraz resolves although Carlos Alcaraz Gonzalez also exists. A name you did not type in full stays a fragment: Sinner still refuses, and lists Jannik and Martin. Totals count meetings with a KNOWN winner; undecided counts the rest. Walkovers and retirements are part of the record, and each meeting carries outcome so you can exclude them. Requires BASIC, or any Historical Data API plan. On ULTRA, a per-player stats block adds serve/return/break-point aggregates over the pairing: archive_serve (serve-side, from 1991) and current (2023+, adding return and break-point conversion, aces and winners), each with meetings_with_stats.

get/h2h

Request

  • Base URL: https://api.livetennisapi.com/api/public/v1
  • URL: https://api.livetennisapi.com/api/public/v1/h2h
  • Auth: one of:
    • HTTP bearer
    • API key in header X-API-Key

Query parameters

p1string required

First player name (fragment, min 3 chars).

p2string required

Second player name (fragment, min 3 chars).

Response

The head-to-head record; empty totals when no player matches the names

playersobject nullable

The resolved names ({"p1":{"name"}, "p2":{"name"}}); null when no player matches the fragments.

by_surfaceobject

Per-surface win split of the decided meetings; keys are surface names plus 'unknown'.

statsobject nullable

ULTRA only — per-player serve/return/break-point aggregates over the pairing, keyed p1/p2. Each side carries archive_serve (serve-side figures, meetings from 1991) and current (2023+, adding return and break-point conversion, aces and winners), each with its own meetings_with_stats sample size. Absent below ULTRA.

Changes

No recorded changes to this operation across all 1 revision of this API.