{"id":29108458,"url":"https://github.com/bram--/bggclient","last_synced_at":"2026-04-24T12:03:01.405Z","repository":{"id":224997954,"uuid":"716669280","full_name":"Bram--/bggclient","owner":"Bram--","description":"Unofficial Board Game Geek Client for the JVM","archived":false,"fork":false,"pushed_at":"2024-03-23T18:11:05.000Z","size":1726,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2024-03-24T16:57:44.671Z","etag":null,"topics":["api-client","board-game","boardgamegeek","boardgames","example-code","google-truth","java","kotlin","kotlin-android","kotlin-coroutines","ktor-client","xml"],"latest_commit_sha":null,"homepage":"","language":"Kotlin","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Bram--.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2023-11-09T16:09:50.000Z","updated_at":"2024-04-23T12:38:20.569Z","dependencies_parsed_at":"2024-04-23T12:38:16.990Z","dependency_job_id":"d2990f3a-5afe-48f6-ae13-f5b9fedf161e","html_url":"https://github.com/Bram--/bggclient","commit_stats":null,"previous_names":["bram--/bggclient"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/Bram--/bggclient","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Bram--%2Fbggclient","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Bram--%2Fbggclient/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Bram--%2Fbggclient/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Bram--%2Fbggclient/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Bram--","download_url":"https://codeload.github.com/Bram--/bggclient/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Bram--%2Fbggclient/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":262545043,"owners_count":23326663,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api-client","board-game","boardgamegeek","boardgames","example-code","google-truth","java","kotlin","kotlin-android","kotlin-coroutines","ktor-client","xml"],"created_at":"2025-06-29T06:11:29.399Z","updated_at":"2026-04-24T12:03:01.399Z","avatar_url":"https://github.com/Bram--.png","language":"Kotlin","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Module Board Game Geek Client/BGGClient\n\n[![GitHub License](https://img.shields.io/badge/license-Apache%20License%202.0-blue.svg?style=flat)](http://www.apache.org/licenses/LICENSE-2.0) [![Build](https://github.com/Bram--/bggclient/actions/workflows/ci.yml/badge.svg)](https://github.com/Bram--/bggclient/actions/workflows/ci.yml) [![codecov](https://codecov.io/gh/Bram--/bggclient/graph/badge.svg?token=FJDN8I5FR1)](https://codecov.io/gh/Bram--/bggclient) [![Maven Central](https://img.shields.io/maven-central/v/org.audux.bgg/bggclient.svg)](https://central.sonatype.com/artifact/org.audux.bgg/bggclient)\n\nBggClient is a API client for the Board Game Geek XML APIs. These APIs work for all geek domains,\nmeaning Board games, video games and RPGs can be retrieved. It works on both the JVM and Android (\n24+). Before using the BGG APIs please refer to\nthe [Terms of Use](https://boardgamegeek.com/wiki/page/XML_API_Terms_of_Use#) for the APIs. Finally\n\nIf you're looking for all Board game IDs and some basic information please refer to\n[this page](https://boardgamegeek.com/data_dumps/bg_ranks) that contains CSV with all boardgames\ninstead.\n\n**Note** Ensure that the `BggClient.authToken` method is called with a valid Bearer token. Board Game Geek [now \nrequires](https://boardgamegeek.com/using_the_xml_api#toc10) a valid Auth token to be set.\n\n## APIs overview\n\nA short summary of all available APIs/Endpoints is available\nin [the documentation](https://bram--.github.io/bggclient/).\n\n## Usage\n\nThe library is published\non [MavenCentral as bggclient](https://central.sonatype.com/artifact/org.audux.bgg/bggclient) so\nusing it is as simple as adding a single line to Gradle.\n\n##### Gradle\n\n```kotlin\nimplementation(\"org.audux.bgg:bggclient:1.3.0\")\n```\n\n##### Maven\n\n```xml\n\n\u003cdependency\u003e\n    \u003cgroupId\u003eorg.audux.bgg\u003c/groupId\u003e\n    \u003cartifactId\u003ebggclient\u003c/artifactId\u003e\n    \u003cversion\u003e1.3.0\u003c/version\u003e\n\u003c/dependency\u003e\n```\n\n## Examples\n\nBelow are few short example more complicated examples can be found in\nthe [examples folder](/Bram--/bggclient/tree/main/examples).\n\n### Simple board game request in Kotlin\n\nBelow is a code snippet that calls the `things` XML2 API retrieving info about \"Nucleum\" including\ncomments left on the game.\n\n```kotlin\nrunBlocking {\n    val response = BggClient.things(ids = arrayOf(396790), comments = true).call()\n\n    print(response.data?.things!![0].name) // Prints \"Nucleum\"\n}\n```\n\nThis returns all information about a `Thing` - in this case a board game including any comments\nusers have left on the thing. Comments are paginated and would only return the last 100.\nSee [BggClient#things](/Bram--/bggclient/blob/main/src/main/kotlin/org/audux/bgg/BggClient.kt#:~:text=fun%20things)\nfor the full API. The actual response is `Response\u003cThing\u003e` which is a wrapper that holds the\nresponse data or holds an\nerror instead. Depending on what is requested (e.g. are comments included in the request?) the\nobject is (partially)\nfilled: [Thing object](/Bram--/bggclient/blob/main/src/main/kotlin/org/audux/bgg/response/Things.kt)\n\n_Note that `call()` needs to be called in a suspense function._\n\n### Simple board game request in Java\n\nUsing the library in Java is the same as in Kotlin, however it uses a `CompletableFuture` so the\nrequest and response can be used in Java.\n\n```java\nclass Example() {\n    public static void main(String... arguments) {\n        CompletableFuture\u003cResponse\u003cThings\u003e\u003e future =\n                BggClient.things(\n                                /* ids= */ new Integer[]{396790},\n                                /* types= */ new ThingType[]{},\n                                /* stats= */ false,\n                                /* versions= */ false,\n                                /* videos= */ false,\n                                /* marketplace= */ false,\n                                /* comments= */ true,\n                                /* ratingComments= */ false)\n                        .callAsync();\n\n        // Blocking get - for example purposes only.\n        Response\u003cThings\u003e response = future.get(2_000, MILLISECONDS);\n    }\n}\n```\n\nThe same as the Kotlin example above; this returns all information about a `Thing` - in this case a\nboard game including any comments\nusers have left on the thing. Comments are paginated and would only return the last 100. See\n[BggClient#things](/Bram--/bggclient/blob/main/src/main/kotlin/org/audux/bgg/BggClient.kt#:~:text=fun%20things)\nfor the full API. The actual response is `Response\u003cThing\u003e` which is a wrapper that holds the\nresponse data or holds an\nerror instead. Depending on what is requested (e.g. are comments included in the request?) the\nobject is (partially) filled:\n[Thing object](/Bram--/bggclient/blob/main/src/main/kotlin/org/audux/bgg/response/Things.kt)\n\n### Async request\n\nInstead of using a suspend function you can also do a request inline by giving a callback. The\nrequest and response parsing will then be handled using `Dispatchers.IO` and `Dispatchers.DEFAULT`.\nThe same as the `things` request above but using callAsync() it looks as follows:\n\n```kotlin\nBggClient.things(ids = arrayOf(396790), comments = true).callAsync { response -\u003e\n    print(response.data?.things!![0].name) // Prints \"Nucleum\"\n}\n```\n\n### Pagination\n\nPagination is completely taken care off by the library, a more in-depth example can be found in the\nexamples folder. Pagination starts with the initial request i.e. when a `page` parameter is given\nthat's the start page and the end page can be configured using the `toPage` param. If no `page` and\nno `toPage` params are given the library will attempt to paginate all pages.\n\n```kotlin\nvar response = BggClient.things(ids = arrayOf(396790), comments = true).paginate().call()\n\n// Prints \"Loads of comments 524\"\nprintln(\"Loads of comments! ${response.data?.things!![0].comments?.comments}\") \n```\n\nThe above codes results in 6 requests to BGG, first, the initial request and then 5 parallel\nrequests to retrieve the resulting pages/comments.\n\n##### Paginated requests:\n\nNot all requests can be paginates (as most of them are not actually paginated in the API nor\nneed they be). However the following requests can be paginated:\n\n* `forum` - Aggregate/paginates over the `threads` in a forum. Only 50 per request can be\n  retrieved which means that large forums could result in a lot of requests.\n* `guilds` - Aggregate/paginates over the `guildMembers`. Only 25 members can be returned\n  per request.\n* `plays` - Aggregates/paginates over the list of `plays` for the given user (id). Only 100 plays\n  per request are retrieved.\n* `things` - Aggregates/paginates over the list of `comments` or `ratingcomments`. The pageSize can\n  be set but has a default and maximum size of 100 comments per request.\n* `user` - Aggregates/paginates over the list of `buddies` and `guilds`. The default page size is\n  1000 so it's unlikely pagination actually happens when called.\n\n### Sitemaps\n\nSitemaps are a quick to get IDs of Board games, RPGs, etc. The `sitemapIndex` endpoint contains all\nsitemaps for the given domain e.g. `boardgamegeek.com/sitemapindex` has a list of several sitemaps (\nUrlSets) that contains links to ALL board game pages.\nYou can request the index by calling `BggClient#sitemapIndex`, but using the `diffuse` function will\nactually for off requests to the contained sitemaps and collect the URLs by 'type'.\n\n```kotlin\nval response =\n    BggClient.sitemapIndex(Domain.BOARD_GAME_GEEK)\n        .diffuse(SitemapLocationType.BOARD_GAMES, SitemapLocationType.BOARD_GAME_EXPANSIONS)\n        .call()\n\nprintln(response.data) \n```\n\nData contains a (multi) map of types and URLs (`Map\u003cSitemapLocationType, List\u003cSiteMapUrl\u003e\u003e`):\n\n* [BOARD_GAMES] =\u003e [\"https://boardgamegeek.com/boardgame/2/dragonmaster\", ...]\n* [BOARD_GAME_EXPANSIONS] =\u003e [\"https://boardgamegeek.com/boardgameexpansion/1573/banzai\", ...)\n\n### Custom configuration\n\n`BggClientConfiguration` allows the client to be configured differently. This allows the user to\nincrease the maximum number of retries, the maximum number of concurrent requests and how the\nexponential delay is calculated. The below example also configured (The already default) request \nlimit to 60 request per minute - this appears to be the BGG limit.\n\n```kotlin\nBggClient.configure {\n    maxConcurrentRequests = 5\n    maxRetries = 100\n    requestsPerWindowLimit = 60\n    requestWindowSize = 60.seconds\n}\n```\n\n### Logging\n\nRunning into errors/faulty responses? Turn on the internal logging for the library to see the\ninternal workings.\n\n```kotlin\nBggClient.setLoggerSeverity(Severity.Verbose)\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbram--%2Fbggclient","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbram--%2Fbggclient","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbram--%2Fbggclient/lists"}