# Handball API

> Handball results and history. 62 REST endpoints covering national leagues in Denmark, Sweden, Slovenia, Croatia, Czech Republic, Turkey, Greece, Brazil, international events and archive seasons: finished matches by day, scores with half-time, venues, crowds, referees and player lines with goalkeeper saves.
> Factual data only: no predictions, ratings or tips, and nothing during play.

## Complete reference

- [Full manual, one file](https://handballapi.com/documentation/manual.md): every endpoint, parameter, field and guide in a single markdown document.
- [OpenAPI](https://handballapi.com/openapi.json): machine-readable API description.
- [MCP server](https://handballapi.com/mcp): Model Context Protocol endpoint.

## Agent skill

- [Handball API agent skill](https://handballapi.com/.well-known/agent-skills/handballapi/SKILL.md): how agents use Handball API. Index: https://handballapi.com/.well-known/agent-skills/index.json

## Guides

- [Quick start](https://handballapi.com/documentation/quick-start): Your first call in a minute: the key, the base address and the answer's shape.
- [Authentication](https://handballapi.com/documentation/authentication): Sending your key in either of two headers, why never in the address, and rotating a key.
- [Plans and limits](https://handballapi.com/documentation/plans-and-limits): What each plan reaches, its requests a minute and calls a day, and the headers on every answer.
- [Pagination](https://handballapi.com/documentation/pagination): Pages and cursors on every list.
- [Errors](https://handballapi.com/documentation/errors): The error shape and every code, fixed for v1.
- [Results](https://handballapi.com/documentation/results): Finished matches by day, by the last few days or yesterday, filtered by country, and how to walk a busy day.
- [Matches](https://handballapi.com/documentation/matches): One match in full: venue, crowd, referees, shootout and discipline.
- [Players and goalkeepers](https://handballapi.com/documentation/players): Player lines: scorers, 7m throws, cards, and goalkeepers with saves and save rate.
- [Competitions and seasons](https://handballapi.com/documentation/competitions-and-seasons): Leagues and cups: finding them, their seasons, tables, leaders, form, figures and records.
- [Teams and form](https://handballapi.com/documentation/teams-and-form): Clubs: finding them, their results and fixtures, squads, season figures, form, runs and head to head.
- [Referees and venues](https://handballapi.com/documentation/referees-and-venues): The referees of each match and their record, and the halls matches are played in.
- [League stats](https://handballapi.com/documentation/league-stats): League-wide figures: home advantage and half-time against full-time, the seasons held, and keeping a copy in step.
- [Coverage](https://handballapi.com/documentation/coverage): What the archive holds and what it never holds.
- [Changelog](https://handballapi.com/documentation/changelog): Every change to the API, newest first. v1 only ever gains fields.
- [MCP server](https://handballapi.com/documentation/mcp): Using Handball API from Claude, Cursor and other agents over the Model Context Protocol.
- [Use with Claude and agents](https://handballapi.com/documentation/agent-skill): The agent skill: one file that teaches an agent to use Handball API.

## Endpoints

- [GET /v1/results/yesterday](https://handballapi.com/documentation/results-yesterday): Yesterday's results
- [GET /v1/results/latest](https://handballapi.com/documentation/results-latest): Latest results
- [GET /v1/results](https://handballapi.com/documentation/results-by-date): Results on a day
- [GET /v1/matches/{id}](https://handballapi.com/documentation/match): One match
- [GET /v1/matches/{id}/players](https://handballapi.com/documentation/match-players): Player lines of a match
- [GET /v1/fixtures](https://handballapi.com/documentation/fixtures): Fixtures ahead
- [GET /v1/competitions/{id}/table](https://handballapi.com/documentation/competition-table): League table
- [GET /v1/competitions/{id}/scorers](https://handballapi.com/documentation/competition-scorers): Top scorers
- [GET /v1/teams/{id}/head-to-head](https://handballapi.com/documentation/head-to-head): Head to head
- [GET /v1/meta/coverage](https://handballapi.com/documentation/meta-coverage): Coverage
- [GET /v1/meta/completeness](https://handballapi.com/documentation/meta-completeness): Completeness
- [GET /v1/usage](https://handballapi.com/documentation/usage): Your usage
- [GET /v1/results/today](https://handballapi.com/documentation/results-today): Today's results
- [GET /v1/results/range](https://handballapi.com/documentation/results-range): Results between two days
- [GET /v1/fixtures/today](https://handballapi.com/documentation/fixtures-today): Today's fixtures
- [GET /v1/fixtures/tomorrow](https://handballapi.com/documentation/fixtures-tomorrow): Tomorrow's fixtures
- [GET /v1/matches](https://handballapi.com/documentation/matches-search): Find matches
- [GET /v1/matches/{id}/officials](https://handballapi.com/documentation/match-officials): Officials of a match
- [GET /v1/competitions](https://handballapi.com/documentation/competitions): Competitions
- [GET /v1/competitions/{id}](https://handballapi.com/documentation/competition): One competition
- [GET /v1/competitions/{id}/seasons](https://handballapi.com/documentation/competition-seasons): Seasons of a competition
- [GET /v1/competitions/{id}/results](https://handballapi.com/documentation/competition-results): Results of a competition
- [GET /v1/competitions/{id}/fixtures](https://handballapi.com/documentation/competition-fixtures): Fixtures of a competition
- [GET /v1/competitions/{id}/teams](https://handballapi.com/documentation/competition-teams): Teams of a competition
- [GET /v1/competitions/{id}/goalkeepers](https://handballapi.com/documentation/competition-goalkeepers): Goalkeepers of a season
- [GET /v1/competitions/{id}/seven-metres](https://handballapi.com/documentation/competition-seven-metres): 7m takers of a season
- [GET /v1/competitions/{id}/discipline](https://handballapi.com/documentation/competition-discipline): Discipline of a season
- [GET /v1/competitions/{id}/assists](https://handballapi.com/documentation/competition-assists): Assists of a season
- [GET /v1/competitions/{id}/home-away](https://handballapi.com/documentation/competition-home-away): Home and away tables
- [GET /v1/competitions/{id}/form](https://handballapi.com/documentation/competition-form): Form table
- [GET /v1/competitions/{id}/stats](https://handballapi.com/documentation/competition-stats): Season figures
- [GET /v1/competitions/{id}/records](https://handballapi.com/documentation/competition-records): Season records
- [GET /v1/competitions/{id}/attendance](https://handballapi.com/documentation/competition-attendance): Crowds of a season
- [GET /v1/teams](https://handballapi.com/documentation/teams): Find teams
- [GET /v1/teams/{id}](https://handballapi.com/documentation/team): One team
- [GET /v1/teams/{id}/results](https://handballapi.com/documentation/team-results): Results of a team
- [GET /v1/teams/{id}/fixtures](https://handballapi.com/documentation/team-fixtures): Fixtures of a team
- [GET /v1/teams/{id}/squad](https://handballapi.com/documentation/team-squad): Squad of a season
- [GET /v1/teams/{id}/stats](https://handballapi.com/documentation/team-stats): Season figures of a team
- [GET /v1/teams/{id}/form](https://handballapi.com/documentation/team-form): Form of a team
- [GET /v1/teams/{id}/scorers](https://handballapi.com/documentation/team-scorers): Scorers of a team
- [GET /v1/teams/{id}/seasons](https://handballapi.com/documentation/team-seasons): Seasons of a team
- [GET /v1/teams/{id}/streaks](https://handballapi.com/documentation/team-streaks): Runs of a team
- [GET /v1/players/leaders](https://handballapi.com/documentation/players-leaders): Leaders
- [GET /v1/players](https://handballapi.com/documentation/players-search): Find players
- [GET /v1/players/{id}](https://handballapi.com/documentation/player): One player
- [GET /v1/players/{id}/matches](https://handballapi.com/documentation/player-matches): Matches of a player
- [GET /v1/players/{id}/seasons](https://handballapi.com/documentation/player-seasons): Seasons of a player
- [GET /v1/players/{id}/career](https://handballapi.com/documentation/player-career): Career of a player
- [GET /v1/goalkeepers/leaders](https://handballapi.com/documentation/goalkeepers-leaders): Goalkeeper leaders
- [GET /v1/referees](https://handballapi.com/documentation/referees): Find referees
- [GET /v1/referees/{id}](https://handballapi.com/documentation/referee): One referee
- [GET /v1/referees/{id}/matches](https://handballapi.com/documentation/referee-matches): Matches of a referee
- [GET /v1/referees/{id}/stats](https://handballapi.com/documentation/referee-stats): Record of a referee
- [GET /v1/venues](https://handballapi.com/documentation/venues): Find venues
- [GET /v1/venues/{id}/matches](https://handballapi.com/documentation/venue-matches): Matches at a venue
- [GET /v1/countries](https://handballapi.com/documentation/countries): Countries
- [GET /v1/countries/{code}/competitions](https://handballapi.com/documentation/country-competitions): Competitions of a country
- [GET /v1/meta/seasons](https://handballapi.com/documentation/meta-seasons): Seasons held
- [GET /v1/updates](https://handballapi.com/documentation/updates): Changed since
- [GET /v1/stats/home-advantage](https://handballapi.com/documentation/stats-home-advantage): Home advantage
- [GET /v1/stats/half-time-full-time](https://handballapi.com/documentation/stats-half-time-full-time): Half-time and full-time