1. What Does Head-to-Head Data Contain?

Head-to-head data describes previous direct meetings between two players. A useful H2H endpoint should expose much more than a simple win-loss total.

{
  "meetings": 8,
  "player_a_wins": 5,
  "player_b_wins": 3,
  "player_a_sets_won": 22,
  "player_b_sets_won": 17
}

2. Why Can H2H Improve Predictions?

Rankings and general win rates describe how players perform against the field. H2H adds a different question: how do these two players perform against each other?

Some matchups can behave differently from broad player-strength indicators. Direct history may reveal that one player consistently performs better against a particular opponent, even when their overall records are closer.

3. Useful H2H Features for a Prediction Model

These features turn a raw list of matches into structured inputs that a model can evaluate consistently.

4. Start With a Simple H2H Win Rate

h2h_win_rate =
player_wins / total_meetings

That number is useful, but it should not be interpreted without sample size and recency.

5. Sample Size Changes How Much H2H Should Matter

6. Set History Can Reveal More Than Match Wins

Two players can have a 3–3 match record while one player has consistently won their matches comfortably and lost only narrow contests.

h2h_set_win_rate =
player_sets_won /
(player_sets_won + opponent_sets_won)

7. Look at the Margin of Previous Sets

A model can also describe whether previous sets were consistently close or one-sided.

set_margin =
player_points - opponent_points

average_h2h_set_margin =
mean(set_margin across supported H2H sets)

Point-level historical depth may not exist for every competition or old match, so use this only where the dataset supports it.

8. Recent H2H Usually Deserves More Attention Than Old H2H

A meeting from several years ago may describe two very different versions of the players compared with a match from last month.

weight =
exp(-decay_rate × days_since_match)

weighted_h2h =
sum(match_result × weight) /
sum(weight)

9. Keep Career H2H and Recent H2H Separate

That tells a more nuanced story than either number alone.

10. Combine H2H With Player Rankings

Ranking difference describes general player strength while H2H describes the direct matchup.

In this example, current ranking favours Player A while recent H2H and form lean toward Player B. A model can evaluate all three instead of relying on one headline metric.

11. Use Historical Rankings for Historical H2H

If you are analysing an old H2H match, current ranking is not the ranking that existed when the match was played.

historical_match_date
        ↓
latest ranking release
BEFORE historical_match_date
        ↓
ranking difference at match time

12. Combine H2H With Recent Form

Direct matchup history can become stale. Recent form helps describe the player’s current competitive state.

13. Add an Elo-Style Rating Difference

Elo-style systems provide a continuously updated player-strength signal that can complement official rankings and H2H.

elo_difference =
player_a_elo - player_b_elo

14. H2H Is Evidence, Not Causality

A player may lead the direct series for reasons that no longer apply. Their opponent may have improved, the ranking gap may have reversed or the sample may come from a different stage of both players’ careers.

“Player A leads the H2H” is a data statement. “Player A will win because they lead the H2H” is a prediction claim that still needs model support.

15. Retrieve H2H Data Through an API

GET /v1/table-tennis/head-to-head
    ?player_a_id=player_tt_101
    &player_b_id=player_tt_204
    &limit=20

{
  "summary": {
    "meetings": 8,
    "player_a_wins": 5,
    "player_b_wins": 3,
    "player_a_sets_won": 22,
    "player_b_sets_won": 17
  },
  "matches": [
    {
      "match_id": "match_tt_40021",
      "played_at": "2026-05-14T11:00:00Z",
      "winner_id": "player_tt_101",
      "sets": {
        "player_a": 4,
        "player_b": 2
      }
    }
  ]
}

16. Build H2H Features in JavaScript

function buildH2HFeatures(h2h, playerAId) {
  const meetings = h2h.matches.length;

  const wins = h2h.matches.filter(
    match => match.winner_id === playerAId
  ).length;

  const winRate = meetings
    ? wins / meetings
    : null;

  return {
    h2h_meetings: meetings,
    h2h_wins: wins,
    h2h_win_rate: winRate
  };
}

17. Add Recency-Aware H2H Features

function recentH2H(matches, playerId, limit = 5) {
  const recent = [...matches]
    .sort(
      (a, b) =>
        new Date(b.played_at) - new Date(a.played_at)
    )
    .slice(0, limit);

  const wins = recent.filter(
    match => match.winner_id === playerId
  ).length;

  return {
    recent_h2h_matches: recent.length,
    recent_h2h_wins: wins,
    recent_h2h_win_rate:
      recent.length ? wins / recent.length : null
  };
}

18. Create One Model-Ready Feature Row

After joining H2H, ranking and form data, your model can consume a compact feature vector.

{
  "ranking_difference": -7,
  "elo_difference": 42,
  "h2h_meetings": 8,
  "h2h_win_rate": 0.625,
  "recent_h2h_win_rate": 0.60,
  "h2h_set_win_rate": 0.564,
  "recent_form_win_rate": 0.80,
  "days_since_last_h2h": 51
}

The values above are illustrative. Real features must be calculated only from historical data available before the target match.

19. Avoid H2H Leakage in Model Training

When creating a training row for a historical match, include only H2H meetings that happened before that match.

training_match_date = 2026-06-10

allowed_h2h =
all_direct_meetings
WHERE played_at < training_match_date

20. Treat First-Time Matchups Differently

Some players have never met. That is not an error condition.

{
  "h2h_meetings": 0,
  "h2h_win_rate": null,
  "recent_h2h_win_rate": null,
  "h2h_set_win_rate": null
}

The model should then rely naturally on rankings, Elo, recent form, tournament performance and other available features.

21. Do Not Invent Missing H2H History

Historical coverage may vary by competition and date. A provider returning two previous meetings does not necessarily prove that the players met only twice in their careers.

22. Validate Whether H2H Actually Improves the Model

23. H2H Is Useful Beyond Prediction Models

24. Production Checklist

• Use stable player IDs for both sides of the matchup
• Store direct meeting dates
• Preserve set-level scores where available
• Store tournament context where available
• Keep a direct meeting count as a sample-size feature
• Separate career H2H from recent H2H
• Use historical rankings from before each old match
• Exclude future H2H meetings from training rows
• Return null instead of fabricating missing H2H data
• Validate that H2H improves out-of-sample performance
• Keep H2H separate from official rankings and Elo ratings
• Confirm historical depth before claiming career-complete H2H

Common H2H Prediction Mistakes

Frequently Asked Questions