2BBL Go SDK

Go client for the 2. Basketball Bundesliga public API.

Based on the official API documentation: https://wiki.2basketballbundesliga.de/index.php/API

Installation

go get github.com/Senseering/2bbl-go-sdk

Quick Start

package main

import (
	"context"
	"fmt"
	"log"

	bbl "github.com/Senseering/2bbl-go-sdk"
)

func main() {
	client := bbl.NewClient("your-api-key")

	ctx := context.Background()

	// Get ProA standings
	standings, err := client.GetStandings(ctx, bbl.TableProA)
	if err != nil {
		log.Fatal(err)
	}

	fmt.Printf("League: %s (%s)\n", standings.Meta.League, standings.Meta.Season)
	for _, row := range standings.Table {
		fmt.Printf("#%d %s — %d pts (%d-%d)\n",
			row.Pos.Value, row.TeamCaption, row.Points.Value,
			row.Wins.Value, row.Losses.Value)
	}
}

Configuration

// Custom HTTP client (e.g. for timeouts or middleware)
client := bbl.NewClient("your-api-key",
	bbl.WithHTTPClient(&http.Client{Timeout: 10 * time.Second}),
)

// Custom base URL (e.g. for testing)
client := bbl.NewClient("your-api-key",
	bbl.WithBaseURL("http://localhost:8080"),
)

API Reference

Every endpoint requires a club/partner API key provided when creating the client.

Schedule

// Get schedule for a competition and season
schedule, err := client.GetSchedule(ctx, bbl.CompProA, "2023-2024")

// Access matchday games
for day, games := range schedule.Matchdays {
    fmt.Printf("Matchday %d: %d games\n", day, len(games))
}

Competitions: CompProA, CompProAPO, CompProBNord, CompProBSued, CompProBPO, CompProBNordPD, CompProBSuedPD, CompBBLPokal

Standings

standings, err := client.GetStandings(ctx, bbl.TableProA)

Competitions: TableProA, TableProBNord, TableProBSued, TableProBNordPD, TableProBSuedPD

Live Games

// Returns all currently live games (always as a slice)
games, err := client.GetLiveGames(ctx)

SwissTiming Data

// Get scoreboard snapshot for a game
game, err := client.GetSwissTimingGame(ctx, "2003328.JSN")

// Get play-by-play actions for a quarter
actions, err := client.GetQuarterActions(ctx, "2003328Q1.JSN")

// Get raw JSON for any livedata file
raw, err := client.GetSwissTimingRaw(ctx, "2003328.JSN")

Roster

// Own team roster (team API key)
roster, err := client.GetRoster(ctx)

// Specific team roster (partner API key)
roster, err := client.GetRosterByTeam(ctx, "447")

Player Statistics

stats, err := client.GetStats(ctx, bbl.PhaseRegularSeason)

// Total values
for _, p := range stats.Totals {
    fmt.Printf("%s %s: %.0f pts\n", p.Firstname, p.Lastname, p.Points.Value)
}

// Per-game averages
for _, p := range stats.Averages {
    fmt.Printf("%s %s: %.1f ppg\n", p.Firstname, p.Lastname, p.Points.Value)
}

Phases: PhaseRegularSeason (hauptrunde), PhasePlayoffs (po), PhasePlaydowns (pd)

Flexible Types

The 2BBL API frequently returns numeric values as strings and uses inconsistent typing. This SDK handles this transparently with custom types:

Type	Handles
FlexInt	42 or "42"
FlexFloat	9.5, 42, or "9.5"
FlexBool	true or "true"
FlexTimestamp	1411833600 or false
NullableFlexInt	42, "42", "", or null

Access the parsed value via .Value and check if it was present via .Set.

Notes

• Every endpoint requires a club API key as a path segment — this is handled automatically by the client
• Access to specific endpoints may need manual enablement by league administration
• The birthdate UNIX timestamp field on roster players is documented as faulty — use birthdate_ymd instead
• SwissTiming livedata files can return different payload shapes depending on the file; use GetSwissTimingRaw for non-standard formats

Release Process

Create a git tag with semantic versioning:

git tag -a v0.1.0 -m "Release v0.1.0"

6. Push the tag to trigger the release:

   git push origin v0.1.0

License

MIT