Feature Engineering

Default data tool: AcesAPI (acesapi-tool). Bulk results: get_matches by season (2 credits per 100 matches, use offset). Per-match pre-match ratings: get_match (2 each) or get_player_matches (5 per 50). Ages, hand, height: get_player (5). Ranking on a date: get_rankings with date (2). The cheapest design: pull seasons of results with get_matches and compute your own Elo and rolling features locally. About 90 credits per tour-season.

You turn match records into a table where each row is one match and every feature was knowable before the first ball. The single biggest risk is leakage, so every feature below states what it is allowed to see.

When to Use

• "What features should I use to predict tennis matches?"
• "How do I build a rating feature without leakage?"
• "My model is 80 percent accurate, why?" (it is leaking)
• "Build a dataset from 2015 to 2025"

When NOT to Use

• Evaluating the model: see walk-forward-validation
• Probability quality: see probability-calibration
• Using a price as a feature: see odds-analysis first, and treat it separately (see below)

Commands Available

Commands That Do NOT Exist

Row Design: One Match, Symmetric Pair

Each match record has player1 and player2. Do not treat position as meaningful. Two valid layouts:

1. Difference layout. Pick the focal player at random per row (or alternate), compute feature_focal - feature_opponent, and the label is "focal won". Mirror the dataset (add the swapped row) so the model sees both orientations; evaluate on one orientation only.
2. Paired layout. Keep both players' features and enforce symmetry: P(A beats B) + P(B beats A) = 1, by averaging the model's output across the swap.

A model that learns "player1 wins more often" has learned data ordering, not tennis.

Feature Families

Strength (pre-match only)

Form and load

Context

Head to head with a time guard

Compute from get_head_to_head only meetings with match_date before the current match. Use wins_a - wins_b shrunk by n / (n + 10); set to zero when n < 3. Do not call get_head_to_head per row of a large dataset (3 credits each). Build the history from your own results table instead.

Rebuilding Elo Locally

If you compute ratings yourself from get_matches, you can reproduce the published method: start 1500, update both players with K = 250 / (matches + 5)^0.4 where matches is the player's own count of rated matches so far (separately for each surface rating), skip walkovers, defaults and retirements, and expected score 1 / (1 + 10^(-(Ra - Rb)/400)). Your numbers will differ from rating.before where your match pool differs from AcesAPI's (qualifying is included in theirs, from 2022). Validate on a sample: compare your pre-match value with rating_before from get_player_matches for one player, and expect agreement to within a few points when pools match.

def update(ra, rb, na, nb, a_won):
    ea = 1 / (1 + 10 ** (-(ra - rb) / 400))
    ka = 250 / (na + 5) ** 0.4
    kb = 250 / (nb + 5) ** 0.4
    s = 1.0 if a_won else 0.0
    return ra + ka * (s - ea), rb + kb * ((1 - s) - (1 - ea))

Process matches strictly in date order (starts_at), and write the pre-match rating into the row before applying the update.

Leakage Checklist

Sanity test: a pre-match tennis model that beats the closing line by a wide margin is leaking. Rating-only models usually land in the mid-60s for accuracy on tour-level matches (run the Elo baseline on your own data to confirm); treat 75 percent as a bug to explain.

Missing Data

• Walkovers, retirements: drop from training and from rating updates, keep as a "retired recently" flag for the next match.
• Qualifying draw matches: available from 2022; the rating updates include them, so models trained before and after 2022 see different coverage.
• Rank null: indicator plus cap. Never fill with 0.
• First matches of a career: few prior matches means the rating is unsettled; include matches_played_log as a feature so the model can discount.

Credit Usage

State the credit estimate before pulling more than one season.

Anti-patterns

What to Do Next