// Handball API players and goalkeepers

GET /v1/matches/{id}/players returns a line for every player listed for the match, with team=home or team=away to take one side.

Each line has the player's own player_id (pl_), team, name, shirt and position, then goals, shots, seven_m_goals, seven_m_shots, assists, yellow, two_min and red. Goalkeepers also carry saves, shots_faced and save_rate (saves divided by shots faced).

Positions are our own codes: GK, LW, LB, CB, RB, RW and PV (pivot), or null where not known. A figure the match sheet did not carry is null, never 0, so a missing number is never mistaken for none.

Common jobs

• Top scorers: sum goals by player_id over a competition's matches.
• Goalkeeper tables: sum saves and shots_faced by player_id, then divide; leave out keepers under a minimum of shots.
• Discipline: count two_min and red by team.

Player lines are on the paid plans (Plans and limits). player_lines on one match says whether a match has any.

A player across matches

The sums are compiled every night from the lines held, so these calls never count across the archive while you wait.

• GET /v1/players?q=hansen: find a player by part of the name. Free key.
• GET /v1/players/{id}: one player, with the latest team, matches, goals and dates. Free key.
• GET /v1/players/{id}/matches: every match the player has a line for, newest first, with the line itself.
• GET /v1/players/{id}/seasons: the sums per season, competition and team.
• GET /v1/players/{id}/career: the totals, and per competition, across everything held.

Leaders

• GET /v1/players/leaders?stat=goals&season=2025/26: the top players by goals, seven_m_goals, assists or two_min, for one season or all time, one country or all.
• GET /v1/goalkeepers/leaders?season=2025/26&min_shots=100: the best save rates among keepers who faced at least min_shots shots.

A season looks like 2025/26; calendar-year leagues use the year alone. Without a season, leaders count everything held, which needs a plan that reaches the whole archive.