API-Handball
App · Sports · 15 actions
Follow handball with API-Handball: games and results with the score by half, standings, team season statistics, head-to-head records and bookmakers' pre-match odds, for more than 200 leagues and cups, from Germany's Bundesliga, France's Starligue and Spain's Liga ASOBAL to the EHF Champions League and the world and European championships. Needs an API-SPORTS key; the free plan allows 100 requests a day.
Actions
| Action | What it does |
|---|---|
| Find leagues and cups | Find handball competitions by name, country, season or type, each with its ID, logo, country and every season on file with its dates. |
| Find teams | Find teams by name, by league and season, by country or by ID, each with its logo and country, and whether it is a national side. |
| Get a game | Get one game by ID: its start time, round, status, the score and each half's goals. |
| Get account status | See the connected key's API-Handball plan, when it renews, and how many of today's requests are used and left. |
| Get pre-match odds | Get bookmakers' pre-match odds for a game, or for a league's games in a season, optionally from one bookmaker or for one bet type. |
| Get standings | Get a season's tables, such as the Bundesliga's one table or the EHF Champions League's two groups: each team's place, games played, won, drawn and lost, goals scored and conceded, points and form. |
| Get team statistics | Get a team's season in one competition: games played, won, drawn and lost at home, away and in all, with their percentages, and goals scored and conceded in total and per game. |
| List bet types | List the kinds of bet API-Handball has odds for, such as 3Way Result or Over/Under, with the IDs the odds filter takes. |
| List bookmakers | List the bookmakers API-Handball has odds from, with the IDs the odds filter takes. |
| List countries | List the countries and regions that have handball competitions in API-Handball, each with its ID, code and flag. |
| List games | List games and results by day, by league and season, or by team, each with its start time, round, status, the score and each half's goals. |
| List head-to-head games | List the games two teams have played each other, in every season or only one league, season or day, with a count of each side's wins, the draws and each side's goals across the finished ones. |
| List seasons | List the seasons API-Handball has data for, oldest first, as the four-digit years the Season fields take. |
| List standings groups | List the groups a competition's season has, such as the EHF Champions League's Group A and Group B, by the names Get standings takes as its Group. |
| List standings stages | List the stages of a competition's season, such as its regular season, which Get standings can narrow to. |
Find leagues and cups
Find handball competitions by name, country, season or type, each with its ID, logo, country and every season on file with its dates. With no filter it lists all of them.
Inputs
- League
league_idtext - Optional. Only this competition. Pick one from the list, or pass a league ID such as 39 for the Bundesliga.
- Search
searchtext - Optional. Only names containing this, at least 3 characters.
- Country
countrytext - Optional. Only this country, by name as the list gives it, such as Germany, France or Denmark.
- Season
seasonnumber - Optional. Only this season, as the four-digit year it starts in, such as 2024 for 2024-25. The free plan reads the 2022 to 2024 seasons.From 1900 to 2100.
- Type
league_typetext - Optional. Only leagues, or only cups.One of:
league,cup.
Outputs
countnumber- How many came back.
leagueslist- The competitions.
Example output
{
"count": 1,
"leagues": [
{
"country": {
"code": "DE",
"flag": "https://media.api-sports.io/flags/de.svg",
"id": 13,
"name": "Germany"
},
"current_season": {
"current": true,
"end": "2027-06-06",
"season": 2026,
"start": "2026-08-27"
},
"id": 39,
"logo": "https://media.api-sports.io/handball/leagues/39.png",
"name": "Bundesliga",
"seasons": [
{
"current": false,
"end": "2025-06-08",
"season": 2024,
"start": "2024-09-05"
},
{
"current": false,
"end": "2026-06-07",
"season": 2025,
"start": "2025-08-27"
},
{
"current": true,
"end": "2027-06-06",
"season": 2026,
"start": "2026-08-27"
}
],
"type": "League"
}
]
}Find teams
Find teams by name, by league and season, by country or by ID, each with its logo and country, and whether it is a national side.
Inputs
- Team ID
team_idtext - Optional. Only this team, by ID, such as 315 for Fuchse Berlin.
- Search
searchtext - Optional. Only names containing this, at least 3 characters.
- League
league_idtext - Optional. Only this competition. Pick one from the list, or pass a league ID such as 39 for the Bundesliga.
- Season
seasonnumber - Optional. Only this season, as the four-digit year it starts in, such as 2024 for 2024-25. The free plan reads the 2022 to 2024 seasons.From 1900 to 2100.
- Country
countrytext - Optional. Only this country, by name as the list gives it, such as Germany, France or Denmark.
Outputs
countnumber- How many came back.
teamslist- The teams.
Example output
{
"count": 1,
"teams": [
{
"country": {
"code": "DE",
"flag": "https://media.api-sports.io/flags/de.svg",
"id": 13,
"name": "Germany"
},
"id": 315,
"logo": "https://media.api-sports.io/handball/teams/315.png",
"name": "Fuchse Berlin",
"national": false
}
]
}Get a game
Get one game by ID: its start time, round, status, the score and each half's goals.
Inputs
- Game ID
game_idtextRequired - The game's ID, such as 166376. List games returns them.
- Time zone
timezonetext - Optional. Give dates and times in this time zone, such as Europe/Berlin or Europe/Paris. UTC when left empty.
Outputs
countryobject- A country, or a region such as Europe or World for international competitions.
datetext- When it starts, with the time zone's offset (ISO 8601).
idnumber- The game's ID.
leagueobject- The competition, and the season this is from.
periodsobject- The goals in each half, without extra time.
scoresobject- Each side's goals, extra time included. Null before the game starts.
statusobject- Where the game stands.
teamsobject- Both sides.
timetext- Its start time, HH:MM, in that time zone.
timestampnumber- When it starts, as a Unix timestamp.
timezonetext- The time zone date and time are given in.
weektext- The round: a number such as 17 in a league, or a cup round such as Quarter-finals or Final. Null when the API has none.
Example output
{
"country": {
"code": "DE",
"flag": "https://media.api-sports.io/flags/de.svg",
"id": 13,
"name": "Germany"
},
"date": "2024-09-05T17:00:00+00:00",
"id": 166376,
"league": {
"id": 39,
"logo": "https://media.api-sports.io/handball/leagues/39.png",
"name": "Bundesliga",
"season": 2024,
"type": "League"
},
"periods": {
"first": {
"away": 15,
"home": 15
},
"second": {
"away": 17,
"home": 13
}
},
"scores": {
"away": 32,
"home": 28
},
"status": {
"long": "Finished",
"short": "FT"
},
"teams": {
"away": {
"id": 339,
"logo": "https://media.api-sports.io/handball/teams/339.png",
"name": "Gummersbach"
},
"home": {
"id": 320,
"logo": "https://media.api-sports.io/handball/teams/320.png",
"name": "Hannover-Burgdorf"
}
},
"time": "17:00",
"timestamp": 1725555600,
"timezone": "UTC",
"week": "1"
}Get account status
See the connected key's API-Handball plan, when it renews, and how many of today's requests are used and left. It is free: it never counts against the day.
Inputs
None.
Outputs
activetrue/false- True while the subscription is active.
daily_limitnumber- Requests allowed a day.
plantext- The plan, such as Free.
requests_remainingnumber- Requests left today; the day starts at midnight UTC.
requests_todaynumber- Requests used today.
subscription_endtext- When the plan renews or ends.
Example output
{
"active": true,
"daily_limit": 100,
"plan": "Free",
"requests_remaining": 88,
"requests_today": 12,
"subscription_end": "2027-10-01T00:00:00+00:00"
}Get pre-match odds
Get bookmakers' pre-match odds for a game, or for a league's games in a season, optionally from one bookmaker or for one bet type. Odds appear 1 to 7 days before a game, are updated once a day and are kept for 7 days after it.
Inputs
- Game ID
game_idtext - Optional. Only this game's odds. Set this, or a league and a season.
- League
league_idtext - Optional. Only this competition. Pick one from the list, or pass a league ID such as 39 for the Bundesliga.
- Season
seasonnumber - Optional. Only this season, as the four-digit year it starts in, such as 2024 for 2024-25. The free plan reads the 2022 to 2024 seasons.From 1900 to 2100.
- Bookmaker
bookmaker_idtext - Optional. Only this bookmaker's odds. Pick one from the list.
- Bet type
bet_idtext - Optional. Only this kind of bet, such as 3Way Result. Pick one from the list.
Outputs
countnumber- How many came back.
oddslist- Each game's odds.
Example output
{
"count": 1,
"odds": [
{
"bookmakers": [
{
"bets": [
{
"id": 1,
"name": "3Way Result",
"values": [
{
"odd": 4.75,
"value": "Home"
},
{
"odd": 9.5,
"value": "Draw"
},
{
"odd": 1.32,
"value": "Away"
}
]
}
],
"id": 4,
"name": "Bet365"
}
],
"country": {
"code": "DE",
"flag": "https://media.api-sports.io/flags/de.svg",
"id": 13,
"name": "Germany"
},
"game_id": 194963,
"league": {
"id": 39,
"logo": "https://media.api-sports.io/handball/leagues/39.png",
"name": "Bundesliga",
"season": 2026,
"type": "League"
},
"updated": "2026-10-02T04:25:04+00:00"
}
]
}Get standings
Get a season's tables, such as the Bundesliga's one table or the EHF Champions League's two groups: each team's place, games played, won, drawn and lost, goals scored and conceded, points and form. Narrow to one team, stage or group.
Inputs
- League
league_idtextRequired - The competition, such as 39 for the Bundesliga, 131 for the EHF Champions League or 34 for the Starligue. Pick one from the list, or pass a league ID from an earlier step.
- Season
seasonnumberRequired - The season, as the four-digit year it starts in, such as 2024 for 2024-25. The free plan reads the 2022 to 2024 seasons.From 1900 to 2100.
- Team ID
team_idtext - Optional. Only this team's line in each table it is in.
- Stage
stagetext - Optional. Only this stage, by name. List standings stages gives a season's stages.
- Group
grouptext - Optional. Only this group, by name, such as Group A. List standings groups gives a season's groups.
Outputs
countnumber- How many came back.
standingslist- The tables, in the API's order.
Example output
{
"count": 2,
"standings": [
{
"country": {
"code": null,
"flag": null,
"id": 40,
"name": "Europe"
},
"group": "Group A",
"league": {
"id": 131,
"logo": "https://media.api-sports.io/handball/leagues/131.png",
"name": "Champions League",
"season": 2024,
"type": "cup"
},
"stage": "Champions League - Regular Season",
"table": [
{
"description": "Promotion - Champions League (Play Offs: Quarter-finals)",
"form": "LWWWW",
"games": {
"draws": {
"percentage": 0.0,
"total": 0
},
"losses": {
"percentage": 14.29,
"total": 2
},
"played": 14,
"wins": {
"percentage": 85.71,
"total": 12
}
},
"goals": {
"against": 408,
"for": 468
},
"points": 24,
"position": 1,
"team": {
"id": 4616,
"logo": "https://media.api-sports.io/handball/teams/4616.png",
"name": "Veszprem"
}
},
{
"description": "Promotion - Champions League (Play Offs: Quarter-finals)",
"form": "DWLWL",
"games": {
"draws": {
"percentage": 14.29,
"total": 2
},
"losses": {
"percentage": 28.57,
"total": 4
},
"played": 14,
"wins": {
"percentage": 57.14,
"total": 8
}
},
"goals": {
"against": 399,
"for": 454
},
"points": 18,
"position": 2,
"team": {
"id": 791,
"logo": "https://media.api-sports.io/handball/teams/791.png",
"name": "Sporting"
}
}
]
},
{
"country": {
"code": null,
"flag": null,
"id": 40,
"name": "Europe"
},
"group": "Group B",
"league": {
"id": 131,
"logo": "https://media.api-sports.io/handball/leagues/131.png",
"name": "Champions League",
"season": 2024,
"type": "cup"
},
"stage": "Champions League - Regular Season",
"table": [
{
"description": "Promotion - Champions League (Play Offs: Quarter-finals)",
"form": "WDWLW",
"games": {
"draws": {
"percentage": 14.29,
"total": 2
},
"losses": {
"percentage": 14.29,
"total": 2
},
"played": 14,
"wins": {
"percentage": 71.43,
"total": 10
}
},
"goals": {
"against": 409,
"for": 454
},
"points": 22,
"position": 1,
"team": {
"id": 962,
"logo": "https://media.api-sports.io/handball/teams/962.png",
"name": "Barcelona"
}
},
{
"description": "Promotion - Champions League (Play Offs: Quarter-finals)",
"form": "DWLWW",
"games": {
"draws": {
"percentage": 14.29,
"total": 2
},
"losses": {
"percentage": 28.57,
"total": 4
},
"played": 14,
"wins": {
"percentage": 57.14,
"total": 8
}
},
"goals": {
"against": 421,
"for": 434
},
"points": 18,
"position": 2,
"team": {
"id": 172,
"logo": "https://media.api-sports.io/handball/teams/172.png",
"name": "Aalborg"
}
}
]
}
]
}Get team statistics
Get a team's season in one competition: games played, won, drawn and lost at home, away and in all, with their percentages, and goals scored and conceded in total and per game.
Inputs
- League
league_idtextRequired - The competition, such as 39 for the Bundesliga, 131 for the EHF Champions League or 34 for the Starligue. Pick one from the list, or pass a league ID from an earlier step.
- Season
seasonnumberRequired - The season, as the four-digit year it starts in, such as 2024 for 2024-25. The free plan reads the 2022 to 2024 seasons.From 1900 to 2100.
- Team ID
team_idtextRequired - The team's ID, such as 315 for Fuchse Berlin. Find teams looks one up. A team's ID is the same in every competition.
- Up to date
on_datedate - Optional. Count only games up to this day. The free plan takes only yesterday, today or tomorrow.
Outputs
countryobject- A country, or a region such as Europe or World for international competitions.
gamesobject- The team's record.
goalsobject- Goals scored and conceded.
leagueobject- The competition, and the season this is from.
teamobject- A team.
Example output
{
"country": {
"code": "DE",
"flag": "https://media.api-sports.io/flags/de.svg",
"id": 13,
"name": "Germany"
},
"games": {
"draws": {
"all": {
"percentage": 11.76,
"total": 4
},
"away": {
"percentage": 17.65,
"total": 3
},
"home": {
"percentage": 5.88,
"total": 1
}
},
"losses": {
"all": {
"percentage": 8.82,
"total": 3
},
"away": {
"percentage": 17.65,
"total": 3
},
"home": {
"percentage": 0.0,
"total": 0
}
},
"played": {
"all": 34,
"away": 17,
"home": 17
},
"wins": {
"all": {
"percentage": 79.41,
"total": 27
},
"away": {
"percentage": 64.71,
"total": 11
},
"home": {
"percentage": 94.12,
"total": 16
}
}
},
"goals": {
"against": {
"average": {
"all": 28.9,
"away": 29.5,
"home": 28.4
},
"total": {
"all": 984,
"away": 501,
"home": 483
}
},
"for": {
"average": {
"all": 35.2,
"away": 34.4,
"home": 36.1
},
"total": {
"all": 1197,
"away": 584,
"home": 613
}
}
},
"league": {
"id": 39,
"logo": "https://media.api-sports.io/handball/leagues/39.png",
"name": "Bundesliga",
"season": 2024,
"type": "League"
},
"team": {
"id": 315,
"logo": "https://media.api-sports.io/handball/teams/315.png",
"name": "Fuchse Berlin"
}
}List bet types
List the kinds of bet API-Handball has odds for, such as 3Way Result or Over/Under, with the IDs the odds filter takes.
Inputs
- Search
searchtext - Optional. Only names containing this, at least 3 characters.
Outputs
betslist- The bet types.
countnumber- How many came back.
Example output
{
"bets": [
{
"id": 1,
"name": "3Way Result"
},
{
"id": 2,
"name": "Home/Away"
}
],
"count": 2
}List bookmakers
List the bookmakers API-Handball has odds from, with the IDs the odds filter takes. These IDs are API-Handball's own: the same bookmaker can have another ID in another API-SPORTS API.
Inputs
- Search
searchtext - Optional. Only names containing this, at least 3 characters.
Outputs
bookmakerslist- The bookmakers.
countnumber- How many came back.
Example output
{
"bookmakers": [
{
"id": 1,
"name": "Bwin"
},
{
"id": 4,
"name": "Bet365"
}
],
"count": 2
}List countries
List the countries and regions that have handball competitions in API-Handball, each with its ID, code and flag. The names are what the Country filters take.
Inputs
- Search
searchtext - Optional. Only names containing this, at least 3 characters.
- Country code
codetext - Optional. Only the country with this two-letter code, such as DE, FR or DK.
Outputs
countnumber- How many came back.
countrieslist- The countries.
Example output
{
"count": 2,
"countries": [
{
"code": "DE",
"flag": "https://media.api-sports.io/flags/de.svg",
"id": 13,
"name": "Germany"
},
{
"code": null,
"flag": null,
"id": 40,
"name": "Europe"
}
]
}List games
List games and results by day, by league and season, or by team, each with its start time, round, status, the score and each half's goals.
Inputs
- Date
on_datedate - Optional. Only games on this day, in the time zone chosen below. The free plan takes only yesterday, today or tomorrow.
- League
league_idtext - Optional. Only this competition. Pick one from the list, or pass a league ID such as 39 for the Bundesliga.
- Season
seasonnumber - Optional. Only this season, as the four-digit year it starts in, such as 2024 for 2024-25. The free plan reads the 2022 to 2024 seasons.From 1900 to 2100.
- Team ID
team_idtext - Optional. Only this team, by ID, such as 315 for Fuchse Berlin.
- Time zone
timezonetext - Optional. Give dates and times in this time zone, such as Europe/Berlin or Europe/Paris. UTC when left empty.
Outputs
countnumber- How many came back.
gameslist- The games, in the order given.
Example output
{
"count": 1,
"games": [
{
"country": {
"code": "DE",
"flag": "https://media.api-sports.io/flags/de.svg",
"id": 13,
"name": "Germany"
},
"date": "2024-09-05T17:00:00+00:00",
"id": 166376,
"league": {
"id": 39,
"logo": "https://media.api-sports.io/handball/leagues/39.png",
"name": "Bundesliga",
"season": 2024,
"type": "League"
},
"periods": {
"first": {
"away": 15,
"home": 15
},
"second": {
"away": 17,
"home": 13
}
},
"scores": {
"away": 32,
"home": 28
},
"status": {
"long": "Finished",
"short": "FT"
},
"teams": {
"away": {
"id": 339,
"logo": "https://media.api-sports.io/handball/teams/339.png",
"name": "Gummersbach"
},
"home": {
"id": 320,
"logo": "https://media.api-sports.io/handball/teams/320.png",
"name": "Hannover-Burgdorf"
}
},
"time": "17:00",
"timestamp": 1725555600,
"timezone": "UTC",
"week": "1"
}
]
}List head-to-head games
List the games two teams have played each other, in every season or only one league, season or day, with a count of each side's wins, the draws and each side's goals across the finished ones.
Inputs
- First team ID
first_team_idtextRequired - One of the two teams, by ID, such as 315 for Fuchse Berlin. The summary counts its wins first.
- Second team ID
second_team_idtextRequired - The other team, by ID, such as 339 for Gummersbach.
- League
league_idtext - Optional. Only this competition. Pick one from the list, or pass a league ID such as 39 for the Bundesliga.
- Season
seasonnumber - Optional. Only this season, as the four-digit year it starts in, such as 2024 for 2024-25. The free plan reads the 2022 to 2024 seasons.From 1900 to 2100.
- Date
on_datedate - Optional. Only games on this day, in the time zone chosen below. The free plan takes only yesterday, today or tomorrow.
- Time zone
timezonetext - Optional. Give dates and times in this time zone, such as Europe/Berlin or Europe/Paris. UTC when left empty.
Outputs
countnumber- How many came back.
gameslist- Their games, oldest first.
summaryobject- A count of the finished games among them, extra time included.
Example output
{
"count": 2,
"games": [
{
"country": {
"code": "DE",
"flag": "https://media.api-sports.io/flags/de.svg",
"id": 13,
"name": "Germany"
},
"date": "2024-12-26T18:00:00+00:00",
"id": 166525,
"league": {
"id": 39,
"logo": "https://media.api-sports.io/handball/leagues/39.png",
"name": "Bundesliga",
"season": 2024,
"type": "League"
},
"periods": {
"first": {
"away": 15,
"home": 12
},
"second": {
"away": 14,
"home": 10
}
},
"scores": {
"away": 29,
"home": 22
},
"status": {
"long": "Finished",
"short": "FT"
},
"teams": {
"away": {
"id": 315,
"logo": "https://media.api-sports.io/handball/teams/315.png",
"name": "Fuchse Berlin"
},
"home": {
"id": 339,
"logo": "https://media.api-sports.io/handball/teams/339.png",
"name": "Gummersbach"
}
},
"time": "18:00",
"timestamp": 1735236000,
"timezone": "UTC",
"week": "17"
},
{
"country": {
"code": "DE",
"flag": "https://media.api-sports.io/flags/de.svg",
"id": 13,
"name": "Germany"
},
"date": "2025-06-05T17:00:00+00:00",
"id": 166670,
"league": {
"id": 39,
"logo": "https://media.api-sports.io/handball/leagues/39.png",
"name": "Bundesliga",
"season": 2024,
"type": "League"
},
"periods": {
"first": {
"away": 15,
"home": 22
},
"second": {
"away": 20,
"home": 23
}
},
"scores": {
"away": 35,
"home": 45
},
"status": {
"long": "Finished",
"short": "FT"
},
"teams": {
"away": {
"id": 339,
"logo": "https://media.api-sports.io/handball/teams/339.png",
"name": "Gummersbach"
},
"home": {
"id": 315,
"logo": "https://media.api-sports.io/handball/teams/315.png",
"name": "Fuchse Berlin"
}
},
"time": "17:00",
"timestamp": 1749142800,
"timezone": "UTC",
"week": "33"
}
],
"summary": {
"draws": 0,
"first_team_goals": 74,
"first_team_wins": 2,
"played": 2,
"second_team_goals": 57,
"second_team_wins": 0
}
}List seasons
List the seasons API-Handball has data for, oldest first, as the four-digit years the Season fields take. A season played across two years is named by the year it starts in.
Inputs
None.
Outputs
countnumber- How many came back.
seasonslist- The seasons, oldest first.
Example output
{
"count": 5,
"seasons": [
2022,
2023,
2024,
2025,
2026
]
}List standings groups
List the groups a competition's season has, such as the EHF Champions League's Group A and Group B, by the names Get standings takes as its Group. A season played as one table, as the Bundesliga is, lists none.
Inputs
- League
league_idtextRequired - The competition, such as 39 for the Bundesliga, 131 for the EHF Champions League or 34 for the Starligue. Pick one from the list, or pass a league ID from an earlier step.
- Season
seasonnumberRequired - The season, as the four-digit year it starts in, such as 2024 for 2024-25. The free plan reads the 2022 to 2024 seasons.From 1900 to 2100.
Outputs
countnumber- How many came back.
groupslist- The groups, by name.
Example output
{
"count": 2,
"groups": [
"Group A",
"Group B"
]
}List standings stages
List the stages of a competition's season, such as its regular season, which Get standings can narrow to.
Inputs
- League
league_idtextRequired - The competition, such as 39 for the Bundesliga, 131 for the EHF Champions League or 34 for the Starligue. Pick one from the list, or pass a league ID from an earlier step.
- Season
seasonnumberRequired - The season, as the four-digit year it starts in, such as 2024 for 2024-25. The free plan reads the 2022 to 2024 seasons.From 1900 to 2100.
Outputs
countnumber- How many came back.
stageslist- The stages, by name.
Example output
{
"count": 1,
"stages": [
"Champions League - Regular Season"
]
}