# API-Handball

> 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.

App · Sports · 15 actions. Web page: https://docs.lodol.com/docs/integrations/api-handball

## Actions

### 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_id`, text): Optional. Only this competition. Pick one from the list, or pass a league ID such as 39 for the Bundesliga.
- Search (`search`, text): Optional. Only names containing this, at least 3 characters.
- Country (`country`, text): Optional. Only this country, by name as the list gives it, such as Germany, France or Denmark.
- Season (`season`, number): 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_type`, text): Optional. Only leagues, or only cups. One of: `league`, `cup`.

**Outputs**

- `count` (number): How many came back.
- `leagues` (list): The competitions.

**Example output**

```json
{
  "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_id`, text): Optional. Only this team, by ID, such as 315 for Fuchse Berlin.
- Search (`search`, text): Optional. Only names containing this, at least 3 characters.
- League (`league_id`, text): Optional. Only this competition. Pick one from the list, or pass a league ID such as 39 for the Bundesliga.
- Season (`season`, number): 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 (`country`, text): Optional. Only this country, by name as the list gives it, such as Germany, France or Denmark.

**Outputs**

- `count` (number): How many came back.
- `teams` (list): The teams.

**Example output**

```json
{
  "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_id`, text, required): The game's ID, such as 166376. List games returns them.
- Time zone (`timezone`, text): Optional. Give dates and times in this time zone, such as Europe/Berlin or Europe/Paris. UTC when left empty.

**Outputs**

- `country` (object): A country, or a region such as Europe or World for international competitions.
- `date` (text): When it starts, with the time zone's offset (ISO 8601).
- `id` (number): The game's ID.
- `league` (object): The competition, and the season this is from.
- `periods` (object): The goals in each half, without extra time.
- `scores` (object): Each side's goals, extra time included. Null before the game starts.
- `status` (object): Where the game stands.
- `teams` (object): Both sides.
- `time` (text): Its start time, HH:MM, in that time zone.
- `timestamp` (number): When it starts, as a Unix timestamp.
- `timezone` (text): The time zone date and time are given in.
- `week` (text): 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**

```json
{
  "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**

- `active` (true/false): True while the subscription is active.
- `daily_limit` (number): Requests allowed a day.
- `plan` (text): The plan, such as Free.
- `requests_remaining` (number): Requests left today; the day starts at midnight UTC.
- `requests_today` (number): Requests used today.
- `subscription_end` (text): When the plan renews or ends.

**Example output**

```json
{
  "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_id`, text): Optional. Only this game's odds. Set this, or a league and a season.
- League (`league_id`, text): Optional. Only this competition. Pick one from the list, or pass a league ID such as 39 for the Bundesliga.
- Season (`season`, number): 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_id`, text): Optional. Only this bookmaker's odds. Pick one from the list.
- Bet type (`bet_id`, text): Optional. Only this kind of bet, such as 3Way Result. Pick one from the list.

**Outputs**

- `count` (number): How many came back.
- `odds` (list): Each game's odds.

**Example output**

```json
{
  "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_id`, text, required): 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 (`season`, number, required): 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_id`, text): Optional. Only this team's line in each table it is in.
- Stage (`stage`, text): Optional. Only this stage, by name. List standings stages gives a season's stages.
- Group (`group`, text): Optional. Only this group, by name, such as Group A. List standings groups gives a season's groups.

**Outputs**

- `count` (number): How many came back.
- `standings` (list): The tables, in the API's order.

**Example output**

```json
{
  "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_id`, text, required): 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 (`season`, number, required): 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_id`, text, required): 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_date`, date): Optional. Count only games up to this day. The free plan takes only yesterday, today or tomorrow.

**Outputs**

- `country` (object): A country, or a region such as Europe or World for international competitions.
- `games` (object): The team's record.
- `goals` (object): Goals scored and conceded.
- `league` (object): The competition, and the season this is from.
- `team` (object): A team.

**Example output**

```json
{
  "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 (`search`, text): Optional. Only names containing this, at least 3 characters.

**Outputs**

- `bets` (list): The bet types.
- `count` (number): How many came back.

**Example output**

```json
{
  "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 (`search`, text): Optional. Only names containing this, at least 3 characters.

**Outputs**

- `bookmakers` (list): The bookmakers.
- `count` (number): How many came back.

**Example output**

```json
{
  "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 (`search`, text): Optional. Only names containing this, at least 3 characters.
- Country code (`code`, text): Optional. Only the country with this two-letter code, such as DE, FR or DK.

**Outputs**

- `count` (number): How many came back.
- `countries` (list): The countries.

**Example output**

```json
{
  "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_date`, date): Optional. Only games on this day, in the time zone chosen below. The free plan takes only yesterday, today or tomorrow.
- League (`league_id`, text): Optional. Only this competition. Pick one from the list, or pass a league ID such as 39 for the Bundesliga.
- Season (`season`, number): 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_id`, text): Optional. Only this team, by ID, such as 315 for Fuchse Berlin.
- Time zone (`timezone`, text): Optional. Give dates and times in this time zone, such as Europe/Berlin or Europe/Paris. UTC when left empty.

**Outputs**

- `count` (number): How many came back.
- `games` (list): The games, in the order given.

**Example output**

```json
{
  "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_id`, text, required): One of the two teams, by ID, such as 315 for Fuchse Berlin. The summary counts its wins first.
- Second team ID (`second_team_id`, text, required): The other team, by ID, such as 339 for Gummersbach.
- League (`league_id`, text): Optional. Only this competition. Pick one from the list, or pass a league ID such as 39 for the Bundesliga.
- Season (`season`, number): 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_date`, date): Optional. Only games on this day, in the time zone chosen below. The free plan takes only yesterday, today or tomorrow.
- Time zone (`timezone`, text): Optional. Give dates and times in this time zone, such as Europe/Berlin or Europe/Paris. UTC when left empty.

**Outputs**

- `count` (number): How many came back.
- `games` (list): Their games, oldest first.
- `summary` (object): A count of the finished games among them, extra time included.

**Example output**

```json
{
  "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**

- `count` (number): How many came back.
- `seasons` (list): The seasons, oldest first.

**Example output**

```json
{
  "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_id`, text, required): 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 (`season`, number, required): 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**

- `count` (number): How many came back.
- `groups` (list): The groups, by name.

**Example output**

```json
{
  "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_id`, text, required): 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 (`season`, number, required): 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**

- `count` (number): How many came back.
- `stages` (list): The stages, by name.

**Example output**

```json
{
  "count": 1,
  "stages": [
    "Champions League - Regular Season"
  ]
}
```