Volleyball Data

Volleyball Data (Nevobo — Dutch Volleyball)

Before writing queries, consult references/api-reference.md for endpoints, ID conventions, and data shapes.

Setup

Before first use, check if the CLI is available:

which sports-skills || pip install sports-skills

If pip install fails (package not found or Python version error), install from GitHub:

pip install git+https://github.com/machina-sports/sports-skills.git

The package requires Python 3.10+. If your default Python is older, use a specific version:

python3 --version  # check version
# If < 3.10, try: python3.12 -m pip install sports-skills
# On macOS with Homebrew: /opt/homebrew/bin/python3.12 -m pip install sports-skills

No API keys required. All data comes from the Nevobo (Nederlandse Volleybalbond) open API.

Quick Start

Prefer the CLI — it avoids Python import path issues:

sports-skills volleyball get_competitions
sports-skills volleyball get_standings --competition_id=nevobo-eredivisie-heren
sports-skills volleyball get_results --competition_id=nevobo-eredivisie-dames
sports-skills volleyball get_schedule --competition_id=nevobo-topdivisie-heren-a

Python SDK (alternative):

from sports_skills import volleyball

standings = volleyball.get_standings(competition_id="nevobo-eredivisie-heren")
results = volleyball.get_results(competition_id="nevobo-eredivisie-dames")

CRITICAL: Before Any Query

CRITICAL: Before calling any data endpoint, verify:

• The competition_id uses a valid value from references/competition-ids.md — never guess.
• For club-specific commands, you have a valid Nevobo club_id (use get_clubs to find one — the organisatiecode field).
• Do NOT guess club IDs or competition IDs. Use get_competitions or get_clubs to discover them.

The competition_id Parameter

8 leagues across the top 3 tiers of Dutch volleyball are pre-configured. The competition_id follows the pattern nevobo-<league>-<gender>[-<pool>]:

• Eredivisie (Tier 1, 8 teams): nevobo-eredivisie-heren, nevobo-eredivisie-dames
• Topdivisie (Tier 2, 10 teams/pool): nevobo-topdivisie-heren-a, nevobo-topdivisie-heren-b, nevobo-topdivisie-dames-a, nevobo-topdivisie-dames-b
• Superdivisie (Tier 3, 10 teams): nevobo-superdivisie-heren, nevobo-superdivisie-dames

For lower divisions (1e/2e/3e Divisie, regional, youth, beach — 6,400+ poules), use get_poules to discover them.

See references/competition-ids.md for the full reference with team counts and the Dutch volleyball pyramid.

Commands

See references/api-reference.md for full parameter lists and return shapes.

Examples

Example 1: Eredivisie standings User says: "What are the current Dutch volleyball standings?" Actions: 1. Call get_standings(competition_id="nevobo-eredivisie-heren") for men 2. Call get_standings(competition_id="nevobo-eredivisie-dames") for women Result: League tables with rank, team name, matches played, and points

Example 2: Recent match results User says: "Show me recent Eredivisie volleyball results" Actions: 1. Call get_results(competition_id="nevobo-eredivisie-heren") Result: Match results with home/away teams, match score (e.g. "3-1"), and set scores (e.g. ["25-21", "25-18", "21-25", "25-20"])

Example 3: Club schedule User says: "What matches does LSV have coming up?" Actions: 1. Call get_clubs(limit=10) and find LSV's organisatiecode (CKL5C67) 2. Call get_club_schedule(club_id="CKL5C67") Result: Upcoming matches for all of LSV's teams with venues and dates

Example 4: Second tier standings User says: "Show me the Topdivisie standings" Actions: 1. Call get_standings(competition_id="nevobo-topdivisie-heren-a") for men pool A 2. Call get_standings(competition_id="nevobo-topdivisie-heren-b") for men pool B Result: Two pool tables with 10 teams each

Example 5: Discover lower divisions User says: "What divisions are available in Dutch volleyball?" Actions: 1. Call get_poules(regio="nationale-competitie", limit=20) Result: List of national-level poules including 1e/2e/3e Divisie with their abbreviations and descriptions

Commands that DO NOT exist — never call these

• ~~get_scoreboard~~ — does not exist. Use get_results for recent match results.
• ~~get_rankings~~ — does not exist. Volleyball uses get_standings for league tables.
• ~~get_team_roster~~ — does not exist. Use get_clubs for club information.
• ~~get_player_info~~ — does not exist. Player-level data is not available via this API.

If a command is not listed in the Commands table above, it does not exist.

Error Handling

When a command fails, do not surface raw errors to the user. Instead: 1. Catch silently and try alternatives 2. If a club name is given instead of ID, use get_clubs to find the organisatiecode first 3. If a competition_id returns no data, use get_competitions to verify available leagues 4. Only report failure with a clean message after exhausting alternatives

Troubleshooting

Error: sports-skills command not found Cause: Package not installed Solution: Run pip install sports-skills. If not on PyPI, install from GitHub: pip install git+https://github.com/machina-sports/sports-skills.git

Error: Standings returns empty list Cause: The competition's regular season phase may have ended, or the season hasn't started yet Solution: Use get_results to check recent results, or get_poules to discover current active poule paths

Error: Schedule returns 0 matches Cause: The competition phase has completed and no more matches are scheduled for that poule Solution: This is expected between season phases. Check other leagues (Topdivisie/Superdivisie may still be active)

Error: Club schedule/results returns error Cause: The club_id may be incorrect Solution: Use get_clubs to find valid club IDs (the organisatiecode field, e.g. "CKL5C67")

Error: Connection errors or timeouts Cause: The Nevobo API may be temporarily unavailable Solution: Wait a moment and retry. The API is public and unauthenticated but may have brief outages

Volleyball Data — API Reference

Commands

get_competitions

List all available volleyball competitions and leagues. No parameters required.

Returns configured_leagues[] with competition_id, name, country, gender, and source. Also returns api_competitions with the full list from the Nevobo API.

get_standings

Get league table for a volleyball competition.

• competition_id (str, required): League identifier (e.g. "nevobo-eredivisie-heren").

Returns standings[] with rank, team, matches_played, points, sets_won, sets_lost, points_for, points_against.

get_schedule

Get upcoming match schedule for a competition.

• competition_id (str, required): League identifier.

Returns matches[] with home_team, away_team, date, and details.

get_results

Get match results for a competition.

• competition_id (str, required): League identifier.

Returns results[] with home_team, away_team, score, set_scores[], date, and details.

get_clubs

List volleyball clubs.

• competition_id (str, optional): Competition context (informational).
• limit (int, optional): Max clubs to return.

Returns items[] with club data from the Nevobo API (name, location, coordinates, contact).

get_club_schedule

Get upcoming matches for a club across all its teams.

• club_id (str, required): Nevobo club identifier (e.g. "CKL5C67").

Returns matches[] with home_team, away_team, date, and details.

get_club_results

Get match results for a club across all its teams.

• club_id (str, required): Nevobo club identifier.

Returns results[] with home_team, away_team, score, set_scores[], date, and details.

get_poules

Browse Nevobo poules for advanced discovery of divisions and regional leagues.

• competition_id (str, optional): Filter context.
• regio (str, optional): Region slug (e.g. "nationale-competitie").
• limit (int, optional): Max poules to return.

Returns items[] with poule data from the Hydra API and total count.

get_tournaments

Get volleyball tournament calendar.

• limit (int, optional): Max tournaments to return.

Returns tournaments[] with title, link, date, and description.

get_news

Get volleyball federation news.

• limit (int, optional): Max news items to return.

Returns news[] with title, link, date, and summary.

Data Source

All data comes from the Nevobo (Nederlandse Volleybalbond) open API at https://api.nevobo.nl. No authentication required.

Two interfaces are used:

• JSON-LD / Hydra: Paginated collections for competitions, poules, clubs
• RSS Export: Per-poule standings, schedules, results; per-club feeds

Volleyball Scoring

• Matches are best-of-5 sets (first to 3 sets wins)
• Sets are played to 25 points (deciding set to 15)
• Set scores appear as e.g. "25-21, 25-18, 21-25, 25-20"
• Match result appears as e.g. "3-1" (sets won by each team)
• Points: 3 for a 3-0 or 3-1 win, 2 for a 3-2 win, 1 for a 2-3 loss, 0 otherwise

Volleyball — Competition IDs

All available competition_id values for the volleyball module. These map to Nevobo poules in the Dutch volleyball pyramid.

Eredivisie (Top Tier — 8 teams each)

The highest level of Dutch professional volleyball.

Topdivisie (Second Tier — 10 teams per pool)

Split into two pools (A and B) per gender.

Superdivisie (Third Tier — 10 teams each)

Lower Divisions & Regional Leagues

For divisions below Superdivisie (1e Divisie, 2e Divisie, 3e Divisie, regional leagues, youth, beach), use the get_poules command to discover available poules:

# National-level poules (115 total): 1e/2e/3e Divisie, cups, playoffs
sports-skills volleyball get_poules --regio=nationale-competitie --limit=20

# Regional poules (by region)
sports-skills volleyball get_poules --regio=regio-noord --limit=20
sports-skills volleyball get_poules --regio=regio-west --limit=20
sports-skills volleyball get_poules --regio=regio-oost --limit=20
sports-skills volleyball get_poules --regio=regio-zuid --limit=20

# Championships
sports-skills volleyball get_poules --regio=kampioenschappen --limit=20

# All poules (6,400+ across the entire pyramid)
sports-skills volleyball get_poules --limit=30

Naming Convention

Competition IDs follow the pattern: nevobo-<league>-<gender>[-<pool>]

• nevobo — data source prefix (Nevobo API)
• <league> — eredivisie, topdivisie, superdivisie
• <gender> — heren (men), dames (women)
• <pool> — optional pool letter (a, b) for split divisions like Topdivisie

Dutch Volleyball Pyramid

Eredivisie          (Tier 1)  — 8 teams, professional
Topdivisie          (Tier 2)  — 2 pools x 10 teams
Superdivisie        (Tier 3)  — 10 teams
1e Divisie          (Tier 4)  — multiple pools
2e Divisie          (Tier 5)  — multiple pools
3e Divisie          (Tier 6)  — multiple pools
Regional leagues    (Tier 7+) — organized by regio