// Competitions
Competitions
Free key and every planMCP: find_competitions
Every competition with results, with country, men or women, league or cup, seasons and dates held.
GEThttps://api.handballapi.com/v1/competitions
Try itruns against the live API with your key
keyGet a free key
Kept in this browser and filled in on every docs page. A key made in your account appears here by itself.
Parameters6
| name | type | what it does | |
|---|---|---|---|
country | string | optional | Country code dksesihrcztrgrbrdeskrseschihfhistory |
gender | string | optional | men or women |
q | string | optional | Part of the name, 2 characters or more |
per_page | integer | optional | Rows per page, 1 to 200 (100) |
page | integer | optional | Page number, from 1. Wins over cursor |
cursor | string | optional | The next_cursor from the previous answer |
Returns9 fields
| field | type | what it holds |
|---|---|---|
id | string | Our id for the record. Permanent. |
name | string | The name as published. |
country | string | |
gender | string | men or women. |
kind | string | league, or cup for a knockout competition. |
matches | integer | Matches with a line for the player. |
seasons | integer | |
first_match | date | The first match held. |
last_match | date | The latest match held. |
Example answerGET /v1/competitions?country=de&per_page=3
2003 of 308 rows
{
"data": [
{
"id": "cp_7dmjf1px",
"name": "3. Liga Männer, Nord-Ost",
"country": "de",
"gender": "men",
"kind": "league",
"matches": 29,
"seasons": 1,
"first_match": "2026-10-02",
"last_match": "2026-10-24"
},
{
"id": "cp_xrq3ynrd",
"name": "Regionalliga SW Männer, RLSW-M",
"country": "de",
"gender": "men",
"kind": "league",
"matches": 20,
"seasons": 1,
"first_match": "2026-09-26",
"last_match": "2026-10-25"
},
{
"id": "cp_jcc2ve3q",
"name": "Oberliga MÄNNLICH, HVW Männer Oberliga Staffel 1",
"country": "de",
"gender": "men",
"kind": "league",
"matches": 19,
"seasons": 1,
"first_match": "2026-10-02",
"last_match": "2026-10-17"
}
],
"meta": {
"count": 3,
"next_cursor": "cDI",
"page": 1,
"per_page": 3,
"total": 308,
"total_pages": 103,
"next_page": 2,
"prev_page": null,
"took_ms": 55
}
}