> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sportsapipro.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Handball V2 API Overview

> 115 endpoints for comprehensive handball data: live scores, standings, player stats, and betting odds

## Overview

The **Handball V2 (Enhanced)** API provides 115 endpoints covering live matches, tournament standings, team rosters, player statistics, and betting odds for handball leagues worldwide.

### Base URL

```
https://api.sportsapipro.com/v2/handball
```

### Authentication

Include your API key in the `x-api-key` header:

```bash theme={null}
curl -H "x-api-key: YOUR_API_KEY" \
  https://api.sportsapipro.com/v2/handball/live
```

***

## Handball-Specific Notes

### Match Format

* **2 halves × 30 minutes** (60 minutes total)
* Overtime in knockout stages (2 × 5 minutes)
* Score fields: `period1` and `period2` represent half-time scores

### Positions

| Position    | Abbreviation |
| ----------- | ------------ |
| Goalkeeper  | GK           |
| Left Wing   | LW           |
| Right Wing  | RW           |
| Left Back   | LB           |
| Center Back | CB           |
| Right Back  | RB           |
| Pivot       | PV           |

### Key Statistics

* **Goals** — total goals scored
* **Saves** — goalkeeper save percentage
* **Turnovers** — ball losses
* **7m Penalties** — 7-meter penalty conversion rate
* **2-min Suspensions** — temporary exclusions (like hockey penalties)

### Special Mechanics

* **Empty goal play** — team removes GK for extra outfield player
* **2-minute suspensions** — temporary player exclusions
* **7-meter penalties** — penalty shots from 7m line

***

## Test IDs for Development

| Entity     | Name                 | ID         |
| ---------- | -------------------- | ---------- |
| Tournament | EHF Champions League | `30`       |
| Season     | 2025/26              | `77630`    |
| Team       | Kolstad              | `117712`   |
| Team       | Industria Kielce     | `8077`     |
| Match      | Kolstad vs Kielce    | `14167791` |

***

## Endpoint Groups

| Group                                                           | Endpoints | Description                   |
| --------------------------------------------------------------- | --------- | ----------------------------- |
| [Live & Schedule](/api-reference/handball-v2/global)            | 14        | Live games, schedules, search |
| [Match](/api-reference/handball-v2/match)                       | 26        | Match details, stats, odds    |
| [Tournament](/api-reference/handball-v2/tournament)             | 27        | Leagues, seasons, standings   |
| [Team](/api-reference/handball-v2/team)                         | 15        | Rosters, form, transfers      |
| [Player](/api-reference/handball-v2/player)                     | 18        | Stats, career, media          |
| [Manager / Referee / Venue](/api-reference/handball-v2/manager) | 15        | Coaches, officials, arenas    |

***

## Example Requests

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://api.sportsapipro.com/v2/handball/live" \
    -H "x-api-key: YOUR_API_KEY"
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    'https://api.sportsapipro.com/v2/handball/live',
    { headers: { 'x-api-key': 'YOUR_API_KEY' } }
  );
  const data = await response.json();
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      'https://api.sportsapipro.com/v2/handball/live',
      headers={'x-api-key': 'YOUR_API_KEY'}
  )
  data = response.json()
  ```
</CodeGroup>

***

## UI Design Ideas

* **Score display**: Show half-time and full-time scores (e.g., HT 14-12, FT 28-25)
* **Key stats to visualize**: Goals scored/conceded, save percentage, 7m conversion rate, 2-min suspensions
* **Suspensions**: 2-minute temporary suspensions (like hockey penalties) — track active suspensions in live view
* **Empty goal**: Show indicator when team is playing with power play (extra outfield player)

## Sport Comparison — Handball vs Football vs Basketball

| Feature       | Handball                                           | Football (Soccer) | Basketball          |
| ------------- | -------------------------------------------------- | ----------------- | ------------------- |
| Scoring       | 2 halves (60 min)                                  | 2 halves (90 min) | 4 quarters (48 min) |
| Score range   | 20-35 per team typical                             | 0-5 typical       | 80-120 typical      |
| Score fields  | period1-period2 (halves)                           | period1-period2   | period1-period4     |
| Key stats     | Goals, saves, turnovers, 7m penalties, suspensions | Possession, shots | FG%, rebounds       |
| Positions     | GK, LW, RW, LB, CB, RB, Pivot                      | GK, D, M, F       | G, F, C             |
| Special rules | 2-min suspensions, 7-meter penalties, empty goal   | Yellow/Red cards  | Fouls/technicals    |