Handball API holds finished matches from national leagues in fifteen countries and groups, international events and archive seasons going back to the 1930s: scores with half-time, venues, crowds, referees, and a line for every player with goalkeeper saves where it is published.
Results land after full time and never change shape: every id is our own and permanent, every answer is the same envelope, and v1 only ever gains fields. Build league tables, form guides, player and goalkeeper stats, match archives, or give an assistant the whole history of the sport.
Sign up and your free key is made at once. It is kept in this browser for every docs page, so Try it works everywhere.
Get a free keyYesterday's results, in one line. Paste your key below and run it here, or copy the curl into a terminal.
Every answer is data and meta. Take a match id from the list and ask for its details or its player lines.
See the answerOne guide for each part of the data: what it covers, how the records link, and the jobs people do with it, each with its calls.
Every finished match: by day, the last few days or yesterday, filtered by country. Scores with half-time where it is published, the competition and its season, and permanent ids for the match, the teams and the competition.
Read the guideOne match in full: the hall, the crowd, the referees, a 7m shootout where there was one, and whether it was indoor, beach or wheelchair handball, with how many player lines it carries.
Read the guideA line for every player listed: goals, shots, 7m throws, assists and cards, and for goalkeepers saves, shots faced and the save rate. Positions are our own codes, GK to PV.
Every league and cup held, with its seasons, results and fixtures, tables overall and home and away, form, scorers, goalkeepers, 7m takers, discipline, season figures, records and crowds.
Every club held, with its results and fixtures in every competition, its squad and scorers by season, season figures home and away, form, its longest runs and every meeting with another club.
Every referee named on a match, with the matches they took charge of and their record, and every hall, with the matches played in it.
Home advantage by country and season, how often a half-time lead holds and how often it is turned round, the seasons held, and every change since a time for keeping your copy in step.
Read the guideWhat the archive holds, counted from the data on every call: matches, results and player lines by country, the first and latest dates, and the competitions never collected and why.
Read the guideThe green dot opens on the free key; the orange dot on the Results plan and up. Every endpoint page has Try it, its parameters, what it returns, a real example answer and its errors.
GET /v1/results/yesterdayEvery match finished yesterday (UTC), newest first.GET /v1/results/latestMatches finished in the last days, newest first. Results only: served after full time.GET /v1/results?date=Every match finished on one day (UTC). The free key reaches yesterday and today.GET /v1/results/todayEvery match finished today so far (UTC), newest first.GET /v1/results/rangeEvery match finished between two days (UTC), up to 32 days, newest first.GET /v1/matches/{id}Score, half-time, date, venue, crowd, referees and shootout of one finished match.GET /v1/matches/{id}/playersA line for every player listed for the match: goals, shots, 7m, assists, cards, and saves and shots faced for goalkeepers.GET /v1/matchesMatches by team, competition, season and dates, finished or scheduled. Give at least one of team, competition, season or from.GET /v1/matches/{id}/officialsThe referees of one finished match, each with our referee id where the name is known to us.GET /v1/fixturesMatches scheduled in the coming days, soonest first, with throw-off in UTC and in the league's own time.GET /v1/fixtures/todayMatches still to be played today (UTC), soonest first.GET /v1/fixtures/tomorrowEvery match scheduled tomorrow (UTC), soonest first.GET /v1/competitions/{id}/tableThe table of a competition and season, computed from the results held: played, won, drawn, lost, goals and points.GET /v1/competitions/{id}/scorersThe leading scorers of a competition and season, from the player lines held, with matches, 7m goals and goals a match.GET /v1/competitionsEvery competition with results, with country, men or women, league or cup, seasons and dates held.GET /v1/competitions/{id}A competition: country, men or women, league or cup, seasons held, first and last match, and its latest season.GET /v1/competitions/{id}/seasonsEvery season held for a competition, newest first: matches, teams, dates and how many matches have player lines.GET /v1/competitions/{id}/resultsEvery result of a competition in a season, newest first.GET /v1/competitions/{id}/fixturesThe matches still to be played in a competition, soonest first.GET /v1/competitions/{id}/teamsEvery team that played in a competition and season, with matches played.GET /v1/competitions/{id}/goalkeepersThe best save rates of a competition and season, among goalkeepers who faced at least min_shots shots.GET /v1/competitions/{id}/seven-metresThe leading 7m scorers of a competition and season, with throws taken and the rate scored.GET /v1/competitions/{id}/disciplinePlayers with the most red cards, 2 minute suspensions and yellow cards in a competition and season.GET /v1/competitions/{id}/assistsThe leading assist makers of a competition and season, where the league publishes assists.GET /v1/competitions/{id}/home-awayTwo tables for a competition and season: home matches only and away matches only.GET /v1/competitions/{id}/formEvery team of a competition and season with its last five results and its current run.GET /v1/competitions/{id}/statsA competition season in figures: goals a match, home and away goals, home win, draw and away win rates, average crowd.GET /v1/competitions/{id}/recordsThe biggest win, the highest and lowest scoring match and the largest crowd of a competition season.GET /v1/competitions/{id}/attendanceAverage, highest and total home crowd per team in a competition season, where crowds are published.GET /v1/teams/{id}/head-to-headEvery finished match between two teams, newest first, with a summary from the first team's side: won, drawn, lost and goals.GET /v1/teamsTeams by part of the name or by country, with matches held and dates.GET /v1/teams/{id}A team: country, men or women, matches held, first and last match and the competitions it played in.GET /v1/teams/{id}/resultsEvery result of a team, newest first, in every competition held.GET /v1/teams/{id}/fixturesA team's matches still to be played, soonest first.GET /v1/teams/{id}/squadEvery player with a line for the team in a season, with matches and goals.GET /v1/teams/{id}/statsA team's season per competition: record, goals, home and away, goals a match, form and current run.GET /v1/teams/{id}/formA team's last results in every competition, newest first, each marked won, drawn or lost.GET /v1/teams/{id}/scorersA team's leading scorers in a season, in every competition held.GET /v1/teams/{id}/seasonsEvery season a team played, per competition, newest first, with its record.GET /v1/teams/{id}/streaksA team's current run and its longest winning, unbeaten and losing runs across every competition held.GET /v1/meta/coverageWhat the archive holds, counted from the data: matches, results and player lines by country, and what is never collected.GET /v1/meta/completenessEvery competition season held, with how complete it is: results, half-time, venue, crowd, player lines, and how many of those lines add up to the score.GET /v1/meta/seasonsEvery season held, newest first, with matches and the countries it covers.GET /v1/updatesMatches added or changed since a time (7 days back at most), oldest change first, for keeping a copy in step.GET /v1/usageYour plan, calls today, the limits, when they reset and how far back your results reach. Never counted against your allowance.GET /v1/players/leadersThe leading players across every competition held, or one season or country: goals, 7m goals, assists or 2 minute suspensions.GET /v1/playersPlayers by part of the name, with matches, goals and their last match.GET /v1/players/{id}A player: position, nationality and birth date where published, latest team, matches, goals and dates.GET /v1/players/{id}/matchesEvery match a player has a line for, newest first, with the line: goals, shots, 7m, assists, suspensions, saves.GET /v1/players/{id}/seasonsA player's seasons per competition and team, newest first, with the sums of the lines.GET /v1/players/{id}/careerA player's career totals, and per competition, across everything held.GET /v1/goalkeepers/leadersThe best save rates across every competition held, or one season or country, among goalkeepers who faced at least min_shots shots.GET /v1/refereesReferees by part of the name or by country, with matches held and dates.GET /v1/referees/{id}A referee: countries, matches held, first and last match.GET /v1/referees/{id}/matchesEvery result a referee took charge of, newest first.GET /v1/referees/{id}/statsA referee's record: home win, draw and away win rates, goals a match, and 2 minute suspensions and 7m throws a match where player lines are held.GET /v1/venuesHalls by part of the name or by country, with matches held and dates.GET /v1/venues/{id}/matchesEvery result played at a hall, newest first.GET /v1/countriesEvery country and group held, with matches, results, first match, latest result and player lines.GET /v1/countries/{code}/competitionsEvery competition held for a country, the busiest first.GET /v1/stats/home-advantageHome win, draw and away win rates and home and away goals a match, by country and season.GET /v1/stats/half-time-full-timeHow often each half-time outcome ends in each full-time outcome, for a competition, season or country, with the comebacks.GET/v1/results/yesterdayLast night's results, every league02GET/v1/results?date=2026-10-30A whole day, every league03GET/v1/matches/mt_r42fra39One match with venue, crowd and referees04GET/v1/matches/mt_r42fra39/players?team=homeThe home side's scorers and goalkeeper05GET/v1/results/latest?days=2The last two days, newest firstHandball API is built to be used by AI as much as by code. Give an assistant the tools, teach an agent with the skill, or paste the whole API in one file.
Add Handball API to Claude, Cursor or any MCP client: 30 tools, your key, your plan.
https://handballapi.com/mcpEvery tool, its arguments, the endpoint it calls and the plan it needs.
https://handballapi.com/documentation/mcp-toolsOne file that teaches an agent the key, the calls and the limits. Save it as a skill.
https://handballapi.com/skill.mdThe whole API in one markdown file, sized to paste into an assistant.
https://handballapi.com/documentation/manual.mdThe short index an assistant reads first to decide what to fetch.
https://handballapi.com/llms.txtThe machine-readable description, for code generators and API tools.
https://handballapi.com/openapi.json| plan | price | results reach back | requests a minute | calls a day | endpoints |
|---|---|---|---|---|---|
| Free key | free | yesterday and today | 10 | 50 | the free ones |
| Results | not on sale yet | 400 days | 60 | 5,000 | all |
| Archive | not on sale yet | the whole archive | 120 | 25,000 | all |
No, on any plan. A match appears once it is over: finished, or awarded at the table. That is the whole product: results and history you can rely on, without the cost and fragility of a live feed. See Coverage.
Some competitions have an official data partner holding their data rights, and we never collect those from any source: Handball-Bundesliga, EHF competitions, Superliga, Austrian Handball Leagues, Liga ASOBAL and Czech men's Extraliga and the Czech cups. Everything else we hold is counted live by GET /v1/meta/coverage.
Yesterday and today's results, single matches from those days, coverage and your own usage, at 10 requests a minute and 50 calls a day. Player lines and older dates are on the Results plan and up. See Plans and limits.
No. Every id is our own and permanent: mt_ for matches, tm_ teams, cp_ competitions, pl_ players, rf_ referees, vn_ venues. Store them; v1 only ever gains fields, nothing is renamed or removed.
UTC everywhere. date_utc ends in Z, and ?date= means one UTC day. Convert to local time in your own code.
Yes, three ways: the MCP server for tools, the agent skill to teach an agent the API, or the one-file manual to paste. See MCP server.