https://github.com/kkjdaniel/gogeek
A lightweight, easy-to-use Go module designed to streamline interactions with the BoardGameGeek API (XML API2).
https://github.com/kkjdaniel/gogeek
bgg bgg-api board-game boardgamegeek boardgames
Last synced: 5 months ago
JSON representation
A lightweight, easy-to-use Go module designed to streamline interactions with the BoardGameGeek API (XML API2).
- Host: GitHub
- URL: https://github.com/kkjdaniel/gogeek
- Owner: kkjdaniel
- License: mit
- Created: 2025-04-14T11:35:11.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2025-11-04T01:50:18.000Z (9 months ago)
- Last Synced: 2025-11-04T03:27:39.307Z (9 months ago)
- Topics: bgg, bgg-api, board-game, boardgamegeek, boardgames
- Language: Go
- Homepage:
- Size: 4.9 MB
- Stars: 2
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# GoGeek: Go Module for the BoardGameGeek API
[](https://pkg.go.dev/github.com/kkjdaniel/gogeek)
[](https://goreportcard.com/report/github.com/kkjdaniel/gogeek)
[](https://codecov.io/gh/kkjdaniel/gogeek)
GoGeek is a lightweight, easy-to-use Go module designed to streamline interactions with the [BoardGameGeek API](https://boardgamegeek.com/wiki/page/BGG_XML_API2) (XML API2).
## Key Features
- **🔄 Simple Request Handling**: GoGeek abstracts the BGG API request process, allowing you to focus on utilising the data rather than managing HTTP requests.
- **📄 Data Parsing**: Automatically converts and normalises XML responses from the BGG API into Go structs, so you can work with structured data effortlessly.
- **⚠️ Error Handling**: Robust error handling for common issues like network errors, rate limiting, queued requests and unexpected response formats.
## Setup
To setup GoGeek, use the following `go get` command:
```bash
go get github.com/kkjdaniel/gogeek
```
## Usage
Getting started with GoGeek is easy. Here’s a quick example to fetch details about specific board games:
```go
package main
import (
"fmt"
"log"
"github.com/kkjdaniel/gogeek/thing"
)
func main() {
games, err := thing.Query([]int{13, 12, 3})
if err != nil {
log.Fatal(err)
}
for _, game := range games.Items {
fmt.Printf("Name: %s\nYear Published: %d\n", game.Name[0].Value, game.YearPublished.Value)
}
}
```
```
Name: CATAN
Year Published: 1995
Name: Ra
Year Published: 1999
Name: Samurai
Year Published: 1998
```
The `thing` query allows you to fetch details about a specific or multiple board games by BGG ID.
_Note: There is a query limit of 20 IDs per query due to restrictions of the BGG API. If you wish to fetch multiple games you will need to batch your requests._
## Documentation
For the full documentation please see the [GoDoc here](https://pkg.go.dev/github.com/kkjdaniel/gogeek). Details on how to use each query function as well as the interfaces for each of the APIs can be found within their respective packages.
## Contributing
Contributions are welcome! Please feel free to submit a pull request or open an issue on GitHub to help improve GoGeek.