{ "openapi": "3.1.0", "info": { "title": "Handball API", "version": "1.0.0", "description": "Handball results and history. Results only: matches are served after they are over.", "contact": { "name": "DeveloperData.net", "url": "https://handballapi.com/support" }, "x-generated": "2026-10-30T02:27:33Z" }, "servers": [ { "url": "https://api.handballapi.com" } ], "security": [ { "bearer": [] }, { "apiKey": [] } ], "paths": { "/v1/results/yesterday": { "get": { "operationId": "yesterdays_results", "summary": "Yesterday's results", "description": "Every match finished yesterday (UTC), newest first.", "tags": [ "Results" ], "parameters": [ { "name": "country", "in": "query", "required": false, "description": "Country code (dk, se, si, de, sk, rs, es, ch, ihf, history)", "schema": { "type": "string" }, "example": "dk" }, { "name": "per_page", "in": "query", "required": false, "description": "Rows per page, 1 to 200 (100)", "schema": { "type": "integer" }, "example": 50 }, { "name": "page", "in": "query", "required": false, "description": "Page number, from 1. Wins over cursor", "schema": { "type": "integer" }, "example": 1 }, { "name": "cursor", "in": "query", "required": false, "description": "The next_cursor from the previous answer", "schema": { "type": "string" } } ], "externalDocs": { "url": "https://handballapi.com/documentation/results-yesterday" }, "x-free-key": true, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "default": { "description": "An error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/results/latest": { "get": { "operationId": "latest_results", "summary": "Latest results", "description": "Matches finished in the last days, newest first. Results only: served after full time.", "tags": [ "Results" ], "parameters": [ { "name": "days", "in": "query", "required": false, "description": "How many days back, 1 to 7 (2)", "schema": { "type": "integer" }, "example": 2 }, { "name": "country", "in": "query", "required": false, "description": "Country code", "schema": { "type": "string" }, "example": "dk" }, { "name": "per_page", "in": "query", "required": false, "description": "Rows per page, 1 to 200 (100)", "schema": { "type": "integer" }, "example": 50 }, { "name": "page", "in": "query", "required": false, "description": "Page number, from 1. Wins over cursor", "schema": { "type": "integer" }, "example": 1 }, { "name": "cursor", "in": "query", "required": false, "description": "The next_cursor from the previous answer", "schema": { "type": "string" } } ], "externalDocs": { "url": "https://handballapi.com/documentation/results-latest" }, "x-free-key": true, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "default": { "description": "An error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/results": { "get": { "operationId": "results_on_day", "summary": "Results on a day", "description": "Every match finished on one day (UTC). The free key reaches yesterday and today.", "tags": [ "Results" ], "parameters": [ { "name": "date", "in": "query", "required": true, "description": "The day, YYYY-MM-DD", "schema": { "type": "string", "format": "date" }, "example": "2026-10-04" }, { "name": "country", "in": "query", "required": false, "description": "Country code", "schema": { "type": "string" }, "example": "si" }, { "name": "per_page", "in": "query", "required": false, "description": "Rows per page, 1 to 200 (100)", "schema": { "type": "integer" }, "example": 50 }, { "name": "page", "in": "query", "required": false, "description": "Page number, from 1. Wins over cursor", "schema": { "type": "integer" }, "example": 1 }, { "name": "cursor", "in": "query", "required": false, "description": "The next_cursor from the previous answer", "schema": { "type": "string" } } ], "externalDocs": { "url": "https://handballapi.com/documentation/results-by-date" }, "x-free-key": true, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "default": { "description": "An error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/matches/{id}": { "get": { "operationId": "get_match", "summary": "One match", "description": "Score, half-time, date, venue, crowd, referees and shootout of one finished match.", "tags": [ "Matches" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Match id (mt_...)", "schema": { "type": "string" }, "example": "mt_00000000" } ], "externalDocs": { "url": "https://handballapi.com/documentation/match" }, "x-free-key": true, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "default": { "description": "An error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/matches/{id}/players": { "get": { "operationId": "match_players", "summary": "Player lines of a match", "description": "A line for every player listed for the match: goals, shots, 7m, assists, cards, and saves and shots faced for goalkeepers.", "tags": [ "Matches" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Match id (mt_...)", "schema": { "type": "string" }, "example": "mt_00000000" }, { "name": "team", "in": "query", "required": false, "description": "home or away", "schema": { "type": "string" }, "example": "home" } ], "externalDocs": { "url": "https://handballapi.com/documentation/match-players" }, "x-free-key": false, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "default": { "description": "An error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/fixtures": { "get": { "operationId": "fixtures", "summary": "Fixtures ahead", "description": "Matches scheduled in the coming days, soonest first, with throw-off in UTC and in the league's own time.", "tags": [ "Fixtures" ], "parameters": [ { "name": "days", "in": "query", "required": false, "description": "How many days ahead, 1 to 14 (7)", "schema": { "type": "integer" }, "example": 7 }, { "name": "country", "in": "query", "required": false, "description": "Country code", "schema": { "type": "string" }, "example": "de" }, { "name": "per_page", "in": "query", "required": false, "description": "Rows per page, 1 to 200 (100)", "schema": { "type": "integer" }, "example": 50 }, { "name": "page", "in": "query", "required": false, "description": "Page number, from 1. Wins over cursor", "schema": { "type": "integer" }, "example": 1 }, { "name": "cursor", "in": "query", "required": false, "description": "The next_cursor from the previous answer", "schema": { "type": "string" } } ], "externalDocs": { "url": "https://handballapi.com/documentation/fixtures" }, "x-free-key": true, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "default": { "description": "An error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/competitions/{id}/table": { "get": { "operationId": "league_table", "summary": "League table", "description": "The table of a competition and season, computed from the results held: played, won, drawn, lost, goals and points.", "tags": [ "Competitions" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Competition id (cp_...)", "schema": { "type": "string" }, "example": "cp_00000000" }, { "name": "season", "in": "query", "required": false, "description": "Season, such as 2025/26 (the latest with results)", "schema": { "type": "string" }, "example": "2025/26" } ], "externalDocs": { "url": "https://handballapi.com/documentation/competition-table" }, "x-free-key": false, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "default": { "description": "An error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/competitions/{id}/scorers": { "get": { "operationId": "top_scorers", "summary": "Top scorers", "description": "The leading scorers of a competition and season, from the player lines held, with matches, 7m goals and goals a match.", "tags": [ "Competitions" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Competition id (cp_...)", "schema": { "type": "string" }, "example": "cp_00000000" }, { "name": "season", "in": "query", "required": false, "description": "Season, such as 2025/26 (the latest with results)", "schema": { "type": "string" }, "example": "2025/26" }, { "name": "limit", "in": "query", "required": false, "description": "How many players, 1 to 200 (25)", "schema": { "type": "integer" }, "example": 25 } ], "externalDocs": { "url": "https://handballapi.com/documentation/competition-scorers" }, "x-free-key": false, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "default": { "description": "An error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/teams/{id}/head-to-head": { "get": { "operationId": "head_to_head", "summary": "Head to head", "description": "Every finished match between two teams, newest first, with a summary from the first team's side: won, drawn, lost and goals.", "tags": [ "Teams" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Team id (tm_...)", "schema": { "type": "string" }, "example": "tm_00000000" }, { "name": "opponent", "in": "query", "required": true, "description": "The other team's id (tm_...)", "schema": { "type": "string" }, "example": "tm_00000000" }, { "name": "per_page", "in": "query", "required": false, "description": "Rows per page, 1 to 200 (100)", "schema": { "type": "integer" }, "example": 50 }, { "name": "page", "in": "query", "required": false, "description": "Page number, from 1. Wins over cursor", "schema": { "type": "integer" }, "example": 1 }, { "name": "cursor", "in": "query", "required": false, "description": "The next_cursor from the previous answer", "schema": { "type": "string" } } ], "externalDocs": { "url": "https://handballapi.com/documentation/head-to-head" }, "x-free-key": false, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "default": { "description": "An error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/meta/coverage": { "get": { "operationId": "coverage", "summary": "Coverage", "description": "What the archive holds, counted from the data: matches, results and player lines by country, and what is never collected.", "tags": [ "Meta" ], "parameters": [], "externalDocs": { "url": "https://handballapi.com/documentation/meta-coverage" }, "x-free-key": true, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "default": { "description": "An error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/meta/completeness": { "get": { "operationId": "meta_completeness", "summary": "Completeness", "description": "Every 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.", "tags": [ "Meta" ], "parameters": [ { "name": "country", "in": "query", "required": false, "description": "Country code", "schema": { "type": "string" }, "example": "dk" }, { "name": "season", "in": "query", "required": false, "description": "Season, as YYYY/YYYY", "schema": { "type": "string" }, "example": "2025/2026" }, { "name": "per_page", "in": "query", "required": false, "description": "Rows per page, 1 to 200 (100)", "schema": { "type": "integer" }, "example": 50 }, { "name": "page", "in": "query", "required": false, "description": "Page number, from 1. Wins over cursor", "schema": { "type": "integer" }, "example": 1 }, { "name": "cursor", "in": "query", "required": false, "description": "The next_cursor from the previous answer", "schema": { "type": "string" } } ], "externalDocs": { "url": "https://handballapi.com/documentation/meta-completeness" }, "x-free-key": true, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "default": { "description": "An error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/usage": { "get": { "operationId": "usage", "summary": "Your usage", "description": "Your plan, calls today, the limits, when they reset and how far back your results reach. Never counted against your allowance.", "tags": [ "Account" ], "parameters": [], "externalDocs": { "url": "https://handballapi.com/documentation/usage" }, "x-free-key": true, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "default": { "description": "An error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/results/today": { "get": { "operationId": "results_today", "summary": "Today's results", "description": "Every match finished today so far (UTC), newest first.", "tags": [ "Results" ], "parameters": [ { "name": "country", "in": "query", "required": false, "description": "Country code", "schema": { "type": "string" }, "example": "de" }, { "name": "per_page", "in": "query", "required": false, "description": "Rows per page, 1 to 200 (100)", "schema": { "type": "integer" }, "example": 50 }, { "name": "page", "in": "query", "required": false, "description": "Page number, from 1. Wins over cursor", "schema": { "type": "integer" }, "example": 1 }, { "name": "cursor", "in": "query", "required": false, "description": "The next_cursor from the previous answer", "schema": { "type": "string" } } ], "externalDocs": { "url": "https://handballapi.com/documentation/results-today" }, "x-free-key": true, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "default": { "description": "An error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/results/range": { "get": { "operationId": "results_range", "summary": "Results between two days", "description": "Every match finished between two days (UTC), up to 32 days, newest first.", "tags": [ "Results" ], "parameters": [ { "name": "from", "in": "query", "required": true, "description": "First day, YYYY-MM-DD", "schema": { "type": "string", "format": "date" }, "example": "2026-10-01" }, { "name": "to", "in": "query", "required": true, "description": "Last day, YYYY-MM-DD", "schema": { "type": "string", "format": "date" }, "example": "2026-10-14" }, { "name": "country", "in": "query", "required": false, "description": "Country code", "schema": { "type": "string" }, "example": "de" }, { "name": "per_page", "in": "query", "required": false, "description": "Rows per page, 1 to 200 (100)", "schema": { "type": "integer" }, "example": 50 }, { "name": "page", "in": "query", "required": false, "description": "Page number, from 1. Wins over cursor", "schema": { "type": "integer" }, "example": 1 }, { "name": "cursor", "in": "query", "required": false, "description": "The next_cursor from the previous answer", "schema": { "type": "string" } } ], "externalDocs": { "url": "https://handballapi.com/documentation/results-range" }, "x-free-key": true, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "default": { "description": "An error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/fixtures/today": { "get": { "operationId": "fixtures_today", "summary": "Today's fixtures", "description": "Matches still to be played today (UTC), soonest first.", "tags": [ "Fixtures" ], "parameters": [ { "name": "country", "in": "query", "required": false, "description": "Country code", "schema": { "type": "string" }, "example": "de" }, { "name": "per_page", "in": "query", "required": false, "description": "Rows per page, 1 to 200 (100)", "schema": { "type": "integer" }, "example": 50 }, { "name": "page", "in": "query", "required": false, "description": "Page number, from 1. Wins over cursor", "schema": { "type": "integer" }, "example": 1 }, { "name": "cursor", "in": "query", "required": false, "description": "The next_cursor from the previous answer", "schema": { "type": "string" } } ], "externalDocs": { "url": "https://handballapi.com/documentation/fixtures-today" }, "x-free-key": true, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "default": { "description": "An error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/fixtures/tomorrow": { "get": { "operationId": "fixtures_tomorrow", "summary": "Tomorrow's fixtures", "description": "Every match scheduled tomorrow (UTC), soonest first.", "tags": [ "Fixtures" ], "parameters": [ { "name": "country", "in": "query", "required": false, "description": "Country code", "schema": { "type": "string" }, "example": "de" }, { "name": "per_page", "in": "query", "required": false, "description": "Rows per page, 1 to 200 (100)", "schema": { "type": "integer" }, "example": 50 }, { "name": "page", "in": "query", "required": false, "description": "Page number, from 1. Wins over cursor", "schema": { "type": "integer" }, "example": 1 }, { "name": "cursor", "in": "query", "required": false, "description": "The next_cursor from the previous answer", "schema": { "type": "string" } } ], "externalDocs": { "url": "https://handballapi.com/documentation/fixtures-tomorrow" }, "x-free-key": true, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "default": { "description": "An error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/matches": { "get": { "operationId": "search_matches", "summary": "Find matches", "description": "Matches by team, competition, season and dates, finished or scheduled. Give at least one of team, competition, season or from.", "tags": [ "Matches" ], "parameters": [ { "name": "team", "in": "query", "required": false, "description": "Team id (tm_...)", "schema": { "type": "string" }, "example": "tm_00000000" }, { "name": "competition", "in": "query", "required": false, "description": "Competition id (cp_...)", "schema": { "type": "string" }, "example": "cp_00000000" }, { "name": "season", "in": "query", "required": false, "description": "Season, such as 2025/26 (the latest with results)", "schema": { "type": "string" }, "example": "2025/26" }, { "name": "from", "in": "query", "required": false, "description": "From this day, YYYY-MM-DD", "schema": { "type": "string", "format": "date" }, "example": "2026-09-01" }, { "name": "to", "in": "query", "required": false, "description": "To this day, YYYY-MM-DD", "schema": { "type": "string", "format": "date" }, "example": "2026-10-31" }, { "name": "status", "in": "query", "required": false, "description": "finished or scheduled (finished)", "schema": { "type": "string" }, "example": "finished" }, { "name": "country", "in": "query", "required": false, "description": "Country code", "schema": { "type": "string" }, "example": "de" }, { "name": "per_page", "in": "query", "required": false, "description": "Rows per page, 1 to 200 (100)", "schema": { "type": "integer" }, "example": 50 }, { "name": "page", "in": "query", "required": false, "description": "Page number, from 1. Wins over cursor", "schema": { "type": "integer" }, "example": 1 }, { "name": "cursor", "in": "query", "required": false, "description": "The next_cursor from the previous answer", "schema": { "type": "string" } } ], "externalDocs": { "url": "https://handballapi.com/documentation/matches-search" }, "x-free-key": false, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "default": { "description": "An error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/matches/{id}/officials": { "get": { "operationId": "match_officials", "summary": "Officials of a match", "description": "The referees of one finished match, each with our referee id where the name is known to us.", "tags": [ "Matches" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Match id (mt_...)", "schema": { "type": "string" }, "example": "mt_00000000" } ], "externalDocs": { "url": "https://handballapi.com/documentation/match-officials" }, "x-free-key": true, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "default": { "description": "An error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/competitions": { "get": { "operationId": "find_competitions", "summary": "Competitions", "description": "Every competition with results, with country, men or women, league or cup, seasons and dates held.", "tags": [ "Competitions" ], "parameters": [ { "name": "country", "in": "query", "required": false, "description": "Country code", "schema": { "type": "string" }, "example": "de" }, { "name": "gender", "in": "query", "required": false, "description": "men or women", "schema": { "type": "string" }, "example": "women" }, { "name": "q", "in": "query", "required": false, "description": "Part of the name, 2 characters or more", "schema": { "type": "string" }, "example": "liga" }, { "name": "per_page", "in": "query", "required": false, "description": "Rows per page, 1 to 200 (100)", "schema": { "type": "integer" }, "example": 50 }, { "name": "page", "in": "query", "required": false, "description": "Page number, from 1. Wins over cursor", "schema": { "type": "integer" }, "example": 1 }, { "name": "cursor", "in": "query", "required": false, "description": "The next_cursor from the previous answer", "schema": { "type": "string" } } ], "externalDocs": { "url": "https://handballapi.com/documentation/competitions" }, "x-free-key": true, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "default": { "description": "An error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/competitions/{id}": { "get": { "operationId": "competition", "summary": "One competition", "description": "A competition: country, men or women, league or cup, seasons held, first and last match, and its latest season.", "tags": [ "Competitions" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Competition id (cp_...)", "schema": { "type": "string" }, "example": "cp_00000000" } ], "externalDocs": { "url": "https://handballapi.com/documentation/competition" }, "x-free-key": true, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "default": { "description": "An error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/competitions/{id}/seasons": { "get": { "operationId": "competition_seasons", "summary": "Seasons of a competition", "description": "Every season held for a competition, newest first: matches, teams, dates and how many matches have player lines.", "tags": [ "Competitions" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Competition id (cp_...)", "schema": { "type": "string" }, "example": "cp_00000000" } ], "externalDocs": { "url": "https://handballapi.com/documentation/competition-seasons" }, "x-free-key": true, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "default": { "description": "An error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/competitions/{id}/results": { "get": { "operationId": "competition_results", "summary": "Results of a competition", "description": "Every result of a competition in a season, newest first.", "tags": [ "Competitions" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Competition id (cp_...)", "schema": { "type": "string" }, "example": "cp_00000000" }, { "name": "season", "in": "query", "required": false, "description": "Season, such as 2025/26 (the latest with results)", "schema": { "type": "string" }, "example": "2025/26" }, { "name": "per_page", "in": "query", "required": false, "description": "Rows per page, 1 to 200 (100)", "schema": { "type": "integer" }, "example": 50 }, { "name": "page", "in": "query", "required": false, "description": "Page number, from 1. Wins over cursor", "schema": { "type": "integer" }, "example": 1 }, { "name": "cursor", "in": "query", "required": false, "description": "The next_cursor from the previous answer", "schema": { "type": "string" } } ], "externalDocs": { "url": "https://handballapi.com/documentation/competition-results" }, "x-free-key": true, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "default": { "description": "An error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/competitions/{id}/fixtures": { "get": { "operationId": "competition_fixtures", "summary": "Fixtures of a competition", "description": "The matches still to be played in a competition, soonest first.", "tags": [ "Competitions" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Competition id (cp_...)", "schema": { "type": "string" }, "example": "cp_00000000" }, { "name": "per_page", "in": "query", "required": false, "description": "Rows per page, 1 to 200 (100)", "schema": { "type": "integer" }, "example": 50 }, { "name": "page", "in": "query", "required": false, "description": "Page number, from 1. Wins over cursor", "schema": { "type": "integer" }, "example": 1 }, { "name": "cursor", "in": "query", "required": false, "description": "The next_cursor from the previous answer", "schema": { "type": "string" } } ], "externalDocs": { "url": "https://handballapi.com/documentation/competition-fixtures" }, "x-free-key": true, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "default": { "description": "An error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/competitions/{id}/teams": { "get": { "operationId": "competition_teams", "summary": "Teams of a competition", "description": "Every team that played in a competition and season, with matches played.", "tags": [ "Competitions" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Competition id (cp_...)", "schema": { "type": "string" }, "example": "cp_00000000" }, { "name": "season", "in": "query", "required": false, "description": "Season, such as 2025/26 (the latest with results)", "schema": { "type": "string" }, "example": "2025/26" } ], "externalDocs": { "url": "https://handballapi.com/documentation/competition-teams" }, "x-free-key": true, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "default": { "description": "An error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/competitions/{id}/goalkeepers": { "get": { "operationId": "top_goalkeepers", "summary": "Goalkeepers of a season", "description": "The best save rates of a competition and season, among goalkeepers who faced at least min_shots shots.", "tags": [ "Competitions" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Competition id (cp_...)", "schema": { "type": "string" }, "example": "cp_00000000" }, { "name": "season", "in": "query", "required": false, "description": "Season, such as 2025/26 (the latest with results)", "schema": { "type": "string" }, "example": "2025/26" }, { "name": "limit", "in": "query", "required": false, "description": "How many rows, 1 to 200 (25)", "schema": { "type": "integer" }, "example": 25 }, { "name": "min_shots", "in": "query", "required": false, "description": "Shots faced at least (30)", "schema": { "type": "integer" }, "example": 30 } ], "externalDocs": { "url": "https://handballapi.com/documentation/competition-goalkeepers" }, "x-free-key": false, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "default": { "description": "An error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/competitions/{id}/seven-metres": { "get": { "operationId": "competition_seven_metres", "summary": "7m takers of a season", "description": "The leading 7m scorers of a competition and season, with throws taken and the rate scored.", "tags": [ "Competitions" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Competition id (cp_...)", "schema": { "type": "string" }, "example": "cp_00000000" }, { "name": "season", "in": "query", "required": false, "description": "Season, such as 2025/26 (the latest with results)", "schema": { "type": "string" }, "example": "2025/26" }, { "name": "limit", "in": "query", "required": false, "description": "How many rows, 1 to 200 (25)", "schema": { "type": "integer" }, "example": 25 } ], "externalDocs": { "url": "https://handballapi.com/documentation/competition-seven-metres" }, "x-free-key": false, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "default": { "description": "An error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/competitions/{id}/discipline": { "get": { "operationId": "competition_discipline", "summary": "Discipline of a season", "description": "Players with the most red cards, 2 minute suspensions and yellow cards in a competition and season.", "tags": [ "Competitions" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Competition id (cp_...)", "schema": { "type": "string" }, "example": "cp_00000000" }, { "name": "season", "in": "query", "required": false, "description": "Season, such as 2025/26 (the latest with results)", "schema": { "type": "string" }, "example": "2025/26" }, { "name": "limit", "in": "query", "required": false, "description": "How many rows, 1 to 200 (25)", "schema": { "type": "integer" }, "example": 25 } ], "externalDocs": { "url": "https://handballapi.com/documentation/competition-discipline" }, "x-free-key": false, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "default": { "description": "An error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/competitions/{id}/assists": { "get": { "operationId": "competition_assists", "summary": "Assists of a season", "description": "The leading assist makers of a competition and season, where the league publishes assists.", "tags": [ "Competitions" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Competition id (cp_...)", "schema": { "type": "string" }, "example": "cp_00000000" }, { "name": "season", "in": "query", "required": false, "description": "Season, such as 2025/26 (the latest with results)", "schema": { "type": "string" }, "example": "2025/26" }, { "name": "limit", "in": "query", "required": false, "description": "How many rows, 1 to 200 (25)", "schema": { "type": "integer" }, "example": 25 } ], "externalDocs": { "url": "https://handballapi.com/documentation/competition-assists" }, "x-free-key": false, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "default": { "description": "An error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/competitions/{id}/home-away": { "get": { "operationId": "home_away_table", "summary": "Home and away tables", "description": "Two tables for a competition and season: home matches only and away matches only.", "tags": [ "Competitions" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Competition id (cp_...)", "schema": { "type": "string" }, "example": "cp_00000000" }, { "name": "season", "in": "query", "required": false, "description": "Season, such as 2025/26 (the latest with results)", "schema": { "type": "string" }, "example": "2025/26" } ], "externalDocs": { "url": "https://handballapi.com/documentation/competition-home-away" }, "x-free-key": false, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "default": { "description": "An error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/competitions/{id}/form": { "get": { "operationId": "league_form", "summary": "Form table", "description": "Every team of a competition and season with its last five results and its current run.", "tags": [ "Competitions" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Competition id (cp_...)", "schema": { "type": "string" }, "example": "cp_00000000" }, { "name": "season", "in": "query", "required": false, "description": "Season, such as 2025/26 (the latest with results)", "schema": { "type": "string" }, "example": "2025/26" } ], "externalDocs": { "url": "https://handballapi.com/documentation/competition-form" }, "x-free-key": false, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "default": { "description": "An error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/competitions/{id}/stats": { "get": { "operationId": "season_stats", "summary": "Season figures", "description": "A competition season in figures: goals a match, home and away goals, home win, draw and away win rates, average crowd.", "tags": [ "Competitions" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Competition id (cp_...)", "schema": { "type": "string" }, "example": "cp_00000000" }, { "name": "season", "in": "query", "required": false, "description": "Season, such as 2025/26 (the latest with results)", "schema": { "type": "string" }, "example": "2025/26" } ], "externalDocs": { "url": "https://handballapi.com/documentation/competition-stats" }, "x-free-key": false, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "default": { "description": "An error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/competitions/{id}/records": { "get": { "operationId": "competition_records", "summary": "Season records", "description": "The biggest win, the highest and lowest scoring match and the largest crowd of a competition season.", "tags": [ "Competitions" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Competition id (cp_...)", "schema": { "type": "string" }, "example": "cp_00000000" }, { "name": "season", "in": "query", "required": false, "description": "Season, such as 2025/26 (the latest with results)", "schema": { "type": "string" }, "example": "2025/26" } ], "externalDocs": { "url": "https://handballapi.com/documentation/competition-records" }, "x-free-key": false, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "default": { "description": "An error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/competitions/{id}/attendance": { "get": { "operationId": "competition_attendance", "summary": "Crowds of a season", "description": "Average, highest and total home crowd per team in a competition season, where crowds are published.", "tags": [ "Competitions" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Competition id (cp_...)", "schema": { "type": "string" }, "example": "cp_00000000" }, { "name": "season", "in": "query", "required": false, "description": "Season, such as 2025/26 (the latest with results)", "schema": { "type": "string" }, "example": "2025/26" } ], "externalDocs": { "url": "https://handballapi.com/documentation/competition-attendance" }, "x-free-key": false, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "default": { "description": "An error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/teams": { "get": { "operationId": "find_teams", "summary": "Find teams", "description": "Teams by part of the name or by country, with matches held and dates.", "tags": [ "Teams" ], "parameters": [ { "name": "q", "in": "query", "required": false, "description": "Part of the name, 2 characters or more", "schema": { "type": "string" }, "example": "kiel" }, { "name": "country", "in": "query", "required": false, "description": "Country code", "schema": { "type": "string" }, "example": "de" }, { "name": "per_page", "in": "query", "required": false, "description": "Rows per page, 1 to 200 (100)", "schema": { "type": "integer" }, "example": 50 }, { "name": "page", "in": "query", "required": false, "description": "Page number, from 1. Wins over cursor", "schema": { "type": "integer" }, "example": 1 }, { "name": "cursor", "in": "query", "required": false, "description": "The next_cursor from the previous answer", "schema": { "type": "string" } } ], "externalDocs": { "url": "https://handballapi.com/documentation/teams" }, "x-free-key": true, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "default": { "description": "An error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/teams/{id}": { "get": { "operationId": "team", "summary": "One team", "description": "A team: country, men or women, matches held, first and last match and the competitions it played in.", "tags": [ "Teams" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Team id (tm_...)", "schema": { "type": "string" }, "example": "tm_00000000" } ], "externalDocs": { "url": "https://handballapi.com/documentation/team" }, "x-free-key": true, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "default": { "description": "An error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/teams/{id}/results": { "get": { "operationId": "team_results", "summary": "Results of a team", "description": "Every result of a team, newest first, in every competition held.", "tags": [ "Teams" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Team id (tm_...)", "schema": { "type": "string" }, "example": "tm_00000000" }, { "name": "season", "in": "query", "required": false, "description": "Season, such as 2025/26 (the latest with results)", "schema": { "type": "string" }, "example": "2025/26" }, { "name": "per_page", "in": "query", "required": false, "description": "Rows per page, 1 to 200 (100)", "schema": { "type": "integer" }, "example": 50 }, { "name": "page", "in": "query", "required": false, "description": "Page number, from 1. Wins over cursor", "schema": { "type": "integer" }, "example": 1 }, { "name": "cursor", "in": "query", "required": false, "description": "The next_cursor from the previous answer", "schema": { "type": "string" } } ], "externalDocs": { "url": "https://handballapi.com/documentation/team-results" }, "x-free-key": true, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "default": { "description": "An error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/teams/{id}/fixtures": { "get": { "operationId": "team_fixtures", "summary": "Fixtures of a team", "description": "A team's matches still to be played, soonest first.", "tags": [ "Teams" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Team id (tm_...)", "schema": { "type": "string" }, "example": "tm_00000000" }, { "name": "per_page", "in": "query", "required": false, "description": "Rows per page, 1 to 200 (100)", "schema": { "type": "integer" }, "example": 50 }, { "name": "page", "in": "query", "required": false, "description": "Page number, from 1. Wins over cursor", "schema": { "type": "integer" }, "example": 1 }, { "name": "cursor", "in": "query", "required": false, "description": "The next_cursor from the previous answer", "schema": { "type": "string" } } ], "externalDocs": { "url": "https://handballapi.com/documentation/team-fixtures" }, "x-free-key": true, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "default": { "description": "An error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/teams/{id}/squad": { "get": { "operationId": "team_squad", "summary": "Squad of a season", "description": "Every player with a line for the team in a season, with matches and goals.", "tags": [ "Teams" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Team id (tm_...)", "schema": { "type": "string" }, "example": "tm_00000000" }, { "name": "season", "in": "query", "required": false, "description": "Season, such as 2025/26 (the latest with results)", "schema": { "type": "string" }, "example": "2025/26" } ], "externalDocs": { "url": "https://handballapi.com/documentation/team-squad" }, "x-free-key": false, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "default": { "description": "An error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/teams/{id}/stats": { "get": { "operationId": "team_stats", "summary": "Season figures of a team", "description": "A team's season per competition: record, goals, home and away, goals a match, form and current run.", "tags": [ "Teams" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Team id (tm_...)", "schema": { "type": "string" }, "example": "tm_00000000" }, { "name": "season", "in": "query", "required": false, "description": "Season, such as 2025/26 (the latest with results)", "schema": { "type": "string" }, "example": "2025/26" } ], "externalDocs": { "url": "https://handballapi.com/documentation/team-stats" }, "x-free-key": false, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "default": { "description": "An error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/teams/{id}/form": { "get": { "operationId": "team_form", "summary": "Form of a team", "description": "A team's last results in every competition, newest first, each marked won, drawn or lost.", "tags": [ "Teams" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Team id (tm_...)", "schema": { "type": "string" }, "example": "tm_00000000" }, { "name": "last", "in": "query", "required": false, "description": "How many matches, 1 to 20 (5)", "schema": { "type": "integer" }, "example": 5 } ], "externalDocs": { "url": "https://handballapi.com/documentation/team-form" }, "x-free-key": false, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "default": { "description": "An error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/teams/{id}/scorers": { "get": { "operationId": "team_scorers", "summary": "Scorers of a team", "description": "A team's leading scorers in a season, in every competition held.", "tags": [ "Teams" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Team id (tm_...)", "schema": { "type": "string" }, "example": "tm_00000000" }, { "name": "season", "in": "query", "required": false, "description": "Season, such as 2025/26 (the latest with results)", "schema": { "type": "string" }, "example": "2025/26" }, { "name": "limit", "in": "query", "required": false, "description": "How many rows, 1 to 200 (25)", "schema": { "type": "integer" }, "example": 25 } ], "externalDocs": { "url": "https://handballapi.com/documentation/team-scorers" }, "x-free-key": false, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "default": { "description": "An error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/teams/{id}/seasons": { "get": { "operationId": "team_seasons", "summary": "Seasons of a team", "description": "Every season a team played, per competition, newest first, with its record.", "tags": [ "Teams" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Team id (tm_...)", "schema": { "type": "string" }, "example": "tm_00000000" } ], "externalDocs": { "url": "https://handballapi.com/documentation/team-seasons" }, "x-free-key": false, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "default": { "description": "An error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/teams/{id}/streaks": { "get": { "operationId": "team_streaks", "summary": "Runs of a team", "description": "A team's current run and its longest winning, unbeaten and losing runs across every competition held.", "tags": [ "Teams" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Team id (tm_...)", "schema": { "type": "string" }, "example": "tm_00000000" } ], "externalDocs": { "url": "https://handballapi.com/documentation/team-streaks" }, "x-free-key": false, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "default": { "description": "An error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/players/leaders": { "get": { "operationId": "player_leaders", "summary": "Leaders", "description": "The leading players across every competition held, or one season or country: goals, 7m goals, assists or 2 minute suspensions.", "tags": [ "Players" ], "parameters": [ { "name": "stat", "in": "query", "required": false, "description": "goals, seven_m_goals, assists or two_min (goals)", "schema": { "type": "string" }, "example": "goals" }, { "name": "season", "in": "query", "required": false, "description": "Season, such as 2025/26 (the latest with results)", "schema": { "type": "string" }, "example": "2025/26" }, { "name": "country", "in": "query", "required": false, "description": "Country code", "schema": { "type": "string" }, "example": "de" }, { "name": "limit", "in": "query", "required": false, "description": "How many rows, 1 to 200 (25)", "schema": { "type": "integer" }, "example": 25 } ], "externalDocs": { "url": "https://handballapi.com/documentation/players-leaders" }, "x-free-key": false, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "default": { "description": "An error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/players": { "get": { "operationId": "find_players", "summary": "Find players", "description": "Players by part of the name, with matches, goals and their last match.", "tags": [ "Players" ], "parameters": [ { "name": "q", "in": "query", "required": true, "description": "Part of the name, 3 characters or more", "schema": { "type": "string" }, "example": "hansen" }, { "name": "per_page", "in": "query", "required": false, "description": "Rows per page, 1 to 200 (100)", "schema": { "type": "integer" }, "example": 50 }, { "name": "page", "in": "query", "required": false, "description": "Page number, from 1. Wins over cursor", "schema": { "type": "integer" }, "example": 1 }, { "name": "cursor", "in": "query", "required": false, "description": "The next_cursor from the previous answer", "schema": { "type": "string" } } ], "externalDocs": { "url": "https://handballapi.com/documentation/players-search" }, "x-free-key": true, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "default": { "description": "An error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/players/{id}": { "get": { "operationId": "player", "summary": "One player", "description": "A player: position, nationality and birth date where published, latest team, matches, goals and dates.", "tags": [ "Players" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Player id (pl_...)", "schema": { "type": "string" }, "example": "pl_00000000" } ], "externalDocs": { "url": "https://handballapi.com/documentation/player" }, "x-free-key": true, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "default": { "description": "An error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/players/{id}/matches": { "get": { "operationId": "player_matches", "summary": "Matches of a player", "description": "Every match a player has a line for, newest first, with the line: goals, shots, 7m, assists, suspensions, saves.", "tags": [ "Players" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Player id (pl_...)", "schema": { "type": "string" }, "example": "pl_00000000" }, { "name": "per_page", "in": "query", "required": false, "description": "Rows per page, 1 to 200 (100)", "schema": { "type": "integer" }, "example": 50 }, { "name": "page", "in": "query", "required": false, "description": "Page number, from 1. Wins over cursor", "schema": { "type": "integer" }, "example": 1 }, { "name": "cursor", "in": "query", "required": false, "description": "The next_cursor from the previous answer", "schema": { "type": "string" } } ], "externalDocs": { "url": "https://handballapi.com/documentation/player-matches" }, "x-free-key": false, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "default": { "description": "An error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/players/{id}/seasons": { "get": { "operationId": "player_seasons", "summary": "Seasons of a player", "description": "A player's seasons per competition and team, newest first, with the sums of the lines.", "tags": [ "Players" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Player id (pl_...)", "schema": { "type": "string" }, "example": "pl_00000000" } ], "externalDocs": { "url": "https://handballapi.com/documentation/player-seasons" }, "x-free-key": false, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "default": { "description": "An error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/players/{id}/career": { "get": { "operationId": "player_career", "summary": "Career of a player", "description": "A player's career totals, and per competition, across everything held.", "tags": [ "Players" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Player id (pl_...)", "schema": { "type": "string" }, "example": "pl_00000000" } ], "externalDocs": { "url": "https://handballapi.com/documentation/player-career" }, "x-free-key": false, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "default": { "description": "An error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/goalkeepers/leaders": { "get": { "operationId": "goalkeepers_leaders", "summary": "Goalkeeper leaders", "description": "The best save rates across every competition held, or one season or country, among goalkeepers who faced at least min_shots shots.", "tags": [ "Players" ], "parameters": [ { "name": "season", "in": "query", "required": false, "description": "Season, such as 2025/26 (the latest with results)", "schema": { "type": "string" }, "example": "2025/26" }, { "name": "country", "in": "query", "required": false, "description": "Country code", "schema": { "type": "string" }, "example": "de" }, { "name": "limit", "in": "query", "required": false, "description": "How many rows, 1 to 200 (25)", "schema": { "type": "integer" }, "example": 25 }, { "name": "min_shots", "in": "query", "required": false, "description": "Shots faced at least (100)", "schema": { "type": "integer" }, "example": 100 } ], "externalDocs": { "url": "https://handballapi.com/documentation/goalkeepers-leaders" }, "x-free-key": false, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "default": { "description": "An error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/referees": { "get": { "operationId": "find_referees", "summary": "Find referees", "description": "Referees by part of the name or by country, with matches held and dates.", "tags": [ "Referees" ], "parameters": [ { "name": "q", "in": "query", "required": false, "description": "Part of the name, 3 characters or more", "schema": { "type": "string" }, "example": "nygaard" }, { "name": "country", "in": "query", "required": false, "description": "Country code", "schema": { "type": "string" }, "example": "de" }, { "name": "per_page", "in": "query", "required": false, "description": "Rows per page, 1 to 200 (100)", "schema": { "type": "integer" }, "example": 50 }, { "name": "page", "in": "query", "required": false, "description": "Page number, from 1. Wins over cursor", "schema": { "type": "integer" }, "example": 1 }, { "name": "cursor", "in": "query", "required": false, "description": "The next_cursor from the previous answer", "schema": { "type": "string" } } ], "externalDocs": { "url": "https://handballapi.com/documentation/referees" }, "x-free-key": true, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "default": { "description": "An error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/referees/{id}": { "get": { "operationId": "referee", "summary": "One referee", "description": "A referee: countries, matches held, first and last match.", "tags": [ "Referees" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Referee id (rf_...)", "schema": { "type": "string" }, "example": "rf_00000000" } ], "externalDocs": { "url": "https://handballapi.com/documentation/referee" }, "x-free-key": true, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "default": { "description": "An error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/referees/{id}/matches": { "get": { "operationId": "referee_matches", "summary": "Matches of a referee", "description": "Every result a referee took charge of, newest first.", "tags": [ "Referees" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Referee id (rf_...)", "schema": { "type": "string" }, "example": "rf_00000000" }, { "name": "per_page", "in": "query", "required": false, "description": "Rows per page, 1 to 200 (100)", "schema": { "type": "integer" }, "example": 50 }, { "name": "page", "in": "query", "required": false, "description": "Page number, from 1. Wins over cursor", "schema": { "type": "integer" }, "example": 1 }, { "name": "cursor", "in": "query", "required": false, "description": "The next_cursor from the previous answer", "schema": { "type": "string" } } ], "externalDocs": { "url": "https://handballapi.com/documentation/referee-matches" }, "x-free-key": false, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "default": { "description": "An error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/referees/{id}/stats": { "get": { "operationId": "referee_stats", "summary": "Record of a referee", "description": "A 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.", "tags": [ "Referees" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Referee id (rf_...)", "schema": { "type": "string" }, "example": "rf_00000000" } ], "externalDocs": { "url": "https://handballapi.com/documentation/referee-stats" }, "x-free-key": false, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "default": { "description": "An error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/venues": { "get": { "operationId": "venues", "summary": "Find venues", "description": "Halls by part of the name or by country, with matches held and dates.", "tags": [ "Venues" ], "parameters": [ { "name": "q", "in": "query", "required": false, "description": "Part of the name, 3 characters or more", "schema": { "type": "string" }, "example": "arena" }, { "name": "country", "in": "query", "required": false, "description": "Country code", "schema": { "type": "string" }, "example": "de" }, { "name": "per_page", "in": "query", "required": false, "description": "Rows per page, 1 to 200 (100)", "schema": { "type": "integer" }, "example": 50 }, { "name": "page", "in": "query", "required": false, "description": "Page number, from 1. Wins over cursor", "schema": { "type": "integer" }, "example": 1 }, { "name": "cursor", "in": "query", "required": false, "description": "The next_cursor from the previous answer", "schema": { "type": "string" } } ], "externalDocs": { "url": "https://handballapi.com/documentation/venues" }, "x-free-key": true, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "default": { "description": "An error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/venues/{id}/matches": { "get": { "operationId": "venue_matches", "summary": "Matches at a venue", "description": "Every result played at a hall, newest first.", "tags": [ "Venues" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Venue id (vn_...)", "schema": { "type": "string" }, "example": "vn_00000000" }, { "name": "per_page", "in": "query", "required": false, "description": "Rows per page, 1 to 200 (100)", "schema": { "type": "integer" }, "example": 50 }, { "name": "page", "in": "query", "required": false, "description": "Page number, from 1. Wins over cursor", "schema": { "type": "integer" }, "example": 1 }, { "name": "cursor", "in": "query", "required": false, "description": "The next_cursor from the previous answer", "schema": { "type": "string" } } ], "externalDocs": { "url": "https://handballapi.com/documentation/venue-matches" }, "x-free-key": false, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "default": { "description": "An error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/countries": { "get": { "operationId": "countries", "summary": "Countries", "description": "Every country and group held, with matches, results, first match, latest result and player lines.", "tags": [ "Countries" ], "parameters": [], "externalDocs": { "url": "https://handballapi.com/documentation/countries" }, "x-free-key": true, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "default": { "description": "An error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/countries/{code}/competitions": { "get": { "operationId": "country_competitions", "summary": "Competitions of a country", "description": "Every competition held for a country, the busiest first.", "tags": [ "Countries" ], "parameters": [ { "name": "code", "in": "path", "required": true, "description": "Country code", "schema": { "type": "string" }, "example": "dk" }, { "name": "per_page", "in": "query", "required": false, "description": "Rows per page, 1 to 200 (100)", "schema": { "type": "integer" }, "example": 50 }, { "name": "page", "in": "query", "required": false, "description": "Page number, from 1. Wins over cursor", "schema": { "type": "integer" }, "example": 1 }, { "name": "cursor", "in": "query", "required": false, "description": "The next_cursor from the previous answer", "schema": { "type": "string" } } ], "externalDocs": { "url": "https://handballapi.com/documentation/country-competitions" }, "x-free-key": true, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "default": { "description": "An error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/meta/seasons": { "get": { "operationId": "meta_seasons", "summary": "Seasons held", "description": "Every season held, newest first, with matches and the countries it covers.", "tags": [ "Meta" ], "parameters": [], "externalDocs": { "url": "https://handballapi.com/documentation/meta-seasons" }, "x-free-key": true, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "default": { "description": "An error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/updates": { "get": { "operationId": "updates", "summary": "Changed since", "description": "Matches added or changed since a time (7 days back at most), oldest change first, for keeping a copy in step.", "tags": [ "Meta" ], "parameters": [ { "name": "since", "in": "query", "required": true, "description": "A UTC time, such as 2026-10-28T06:00:00Z", "schema": { "type": "string" }, "example": "2026-10-28T06:00:00Z" }, { "name": "country", "in": "query", "required": false, "description": "Country code", "schema": { "type": "string" }, "example": "de" }, { "name": "per_page", "in": "query", "required": false, "description": "Rows per page, 1 to 200 (100)", "schema": { "type": "integer" }, "example": 50 }, { "name": "page", "in": "query", "required": false, "description": "Page number, from 1. Wins over cursor", "schema": { "type": "integer" }, "example": 1 }, { "name": "cursor", "in": "query", "required": false, "description": "The next_cursor from the previous answer", "schema": { "type": "string" } } ], "externalDocs": { "url": "https://handballapi.com/documentation/updates" }, "x-free-key": false, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "default": { "description": "An error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/stats/home-advantage": { "get": { "operationId": "home_advantage", "summary": "Home advantage", "description": "Home win, draw and away win rates and home and away goals a match, by country and season.", "tags": [ "Stats" ], "parameters": [ { "name": "competition", "in": "query", "required": false, "description": "Competition id (cp_...)", "schema": { "type": "string" }, "example": "cp_00000000" }, { "name": "season", "in": "query", "required": false, "description": "Season, such as 2025/26 (the latest with results)", "schema": { "type": "string" }, "example": "2025/26" }, { "name": "country", "in": "query", "required": false, "description": "Country code", "schema": { "type": "string" }, "example": "de" }, { "name": "per_page", "in": "query", "required": false, "description": "Rows per page, 1 to 200 (100)", "schema": { "type": "integer" }, "example": 50 }, { "name": "page", "in": "query", "required": false, "description": "Page number, from 1. Wins over cursor", "schema": { "type": "integer" }, "example": 1 }, { "name": "cursor", "in": "query", "required": false, "description": "The next_cursor from the previous answer", "schema": { "type": "string" } } ], "externalDocs": { "url": "https://handballapi.com/documentation/stats-home-advantage" }, "x-free-key": false, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "default": { "description": "An error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/stats/half-time-full-time": { "get": { "operationId": "stats_half_time_full_time", "summary": "Half-time and full-time", "description": "How often each half-time outcome ends in each full-time outcome, for a competition, season or country, with the comebacks.", "tags": [ "Stats" ], "parameters": [ { "name": "competition", "in": "query", "required": false, "description": "Competition id (cp_...)", "schema": { "type": "string" }, "example": "cp_00000000" }, { "name": "season", "in": "query", "required": false, "description": "Season, such as 2025/26 (the latest with results)", "schema": { "type": "string" }, "example": "2025/26" }, { "name": "country", "in": "query", "required": false, "description": "Country code", "schema": { "type": "string" }, "example": "de" } ], "externalDocs": { "url": "https://handballapi.com/documentation/stats-half-time-full-time" }, "x-free-key": false, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "default": { "description": "An error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "components": { "securitySchemes": { "bearer": { "type": "http", "scheme": "bearer" }, "apiKey": { "type": "apiKey", "in": "header", "name": "X-API-Key" } }, "schemas": { "Envelope": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": [], "meta": { "type": "object" } } }, "Error": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "docs" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "upgrade_required", "not_found", "method_not_allowed", "unknown_parameter", "rate_limited", "quota_exceeded", "server_error" ] }, "message": { "type": "string" }, "plan": { "type": "string" }, "docs": { "type": "string" } } } } } } } }