{"id":45492474,"url":"https://github.com/tnaskali/bgg-api","last_synced_at":"2026-02-22T17:28:27.087Z","repository":{"id":39900086,"uuid":"253437612","full_name":"tnaskali/bgg-api","owner":"tnaskali","description":"proxy to BGG's XML and JSON API","archived":false,"fork":false,"pushed_at":"2026-02-19T18:36:05.000Z","size":1763,"stargazers_count":18,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"master","last_synced_at":"2026-02-19T18:54:33.298Z","etag":null,"topics":["bgg","bgg-api","bgg-library","boardgamegeek","boardgames","json-api","logging-games","spring-boot","spring-native","spring-webflux"],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"unlicense","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tnaskali.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,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2020-04-06T08:23:42.000Z","updated_at":"2026-02-19T18:36:09.000Z","dependencies_parsed_at":"2023-12-21T19:08:48.433Z","dependency_job_id":"63b56367-abbe-4f3f-b690-d68dd96277e2","html_url":"https://github.com/tnaskali/bgg-api","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/tnaskali/bgg-api","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tnaskali%2Fbgg-api","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tnaskali%2Fbgg-api/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tnaskali%2Fbgg-api/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tnaskali%2Fbgg-api/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tnaskali","download_url":"https://codeload.github.com/tnaskali/bgg-api/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tnaskali%2Fbgg-api/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29720563,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-22T15:10:41.462Z","status":"ssl_error","status_checked_at":"2026-02-22T15:10:04.636Z","response_time":110,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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":["bgg","bgg-api","bgg-library","boardgamegeek","boardgames","json-api","logging-games","spring-boot","spring-native","spring-webflux"],"created_at":"2026-02-22T17:28:26.508Z","updated_at":"2026-02-22T17:28:27.073Z","avatar_url":"https://github.com/tnaskali.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# BGG-API\n\n![build status](https://github.com/tnaskali/bgg-api/actions/workflows/build-image.yml/badge.svg)\n![build status](https://github.com/tnaskali/bgg-api/actions/workflows/build-native-image.yml/badge.svg)\n[![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=tnaskali_bgg-api\u0026metric=alert_status)](https://sonarcloud.io/summary/new_code?id=tnaskali_bgg-api)\n\n[![BGG-API Logo](https://cf.geekdo-images.com/HZy35cmzmmyV9BarSuk6ug__small/img/gbE7sulIurZE_Tx8EQJXnZSKI6w=/fit-in/200x150/filters:strip_icc()/pic7779581.png)](https://boardgamegeek.com/using_the_xml_api#toc13)\n\nSpring Boot application acting as a proxy to\nBoardGameGeek's [XML API](https://boardgamegeek.com/wiki/page/BGG_XML_API), [XML API 2](https://boardgamegeek.com/wiki/page/BGG_XML_API2)\nand [JSON API](https://boardgamegeek.com/wiki/page/BGG_JSON_API). Its purpose is to expose the same functionalities,\nmainly retrieving but also\npersisting data, in a more user-friendly and developer-friendly way.\n\n# Features\n\n- Static BGG XML API schemas in XSD format (located under [src/main/xsd](src/main/xsd))\n- Proxied XML and Json API for querying data based on their public API (no authentication required)\n- Proxied Json API for mutating data (e.g. logging games) based on their public API (basic authentication required)\n- (in progress) custom GraphQL API unifying these different API endpoints (schema\n  under [src/main/resources/graphql](src/main/resources/graphql)) and GraphiQL UI (/bgg-api/graphiql) web interface\n- OpenAPI definition and Swagger UI (/bgg-api/swagger-ui.html) web interface\n- Support for building both Java and native artifacts and images\n\n# Setup\n\n## Getting a BGG application token\n\nTo use this application, you need to request and obtain an application token from BoardGameGeek. The steps are described\nin [this page](https://boardgamegeek.com/using_the_xml_api).\n\n## build and run a java application locally\n\nPrerequisites : have Java 17+ and maven installed on your machine\n\nSteps :\n\n1. clone this repository on your local machine\n2. set your BGG application token through the `BGG_APPLICATION_TOKEN` environment variable\n3. run `mvn spring-boot:run`\n\n## build and run a native application locally\n\nPrerequisites : have GraalVM JDK 17+ and maven installed on your machine\n\nSteps :\n\n1. clone this repository on your local machine\n2. run `mvn native:compile -Pnative` to build the native image (takes about 10 minutes)\n3. set your BGG application token through the `BGG_APPLICATION_TOKEN` environment variable\n4. run `./target/bgg-api`\n\n## pull and run a docker java image (Linux / MacOS only)\n\nPrerequisites : have docker installed on your machine\n\nSteps :\n\n1. run `docker pull ghcr.io/tnaskali/bgg-api:master` (or any other tag)\n2. set your BGG application token through the `BGG_APPLICATION_TOKEN` environment variable\n3. run `docker run --rm -p 8080:80 -e BGG_APPLICATION_TOKEN=${BGG_APPLICATION_TOKEN} ghcr.io/tnaskali/bgg-api:master`\n\n## pull and run a docker native image (Linux / MacOS only)\n\nPrerequisites : have docker installed on your machine\n\nSteps :\n\n1. run `docker pull ghcr.io/tnaskali/bgg-api-native:master` (or any other tag)\n2. set your BGG application token through the `BGG_APPLICATION_TOKEN` environment variable\n3. run\n   `docker run --rm -p 8080:80 -e BGG_APPLICATION_TOKEN=${BGG_APPLICATION_TOKEN} ghcr.io/tnaskali/bgg-api-native:master`\n\n# Usage\n\n## Web interfaces\n\n### Swagger UI\n\nThe Swagger UI is available at http://localhost:8080/bgg-api/swagger-ui.html once the application is running.\n\n### GraphiQL UI\n\nThe GraphiQL UI is available at http://localhost:8080/bgg-api/graphiql once the application is running.\n\n## Authentication\n\nSome JSON API endpoints require authentication. Only basic authentication using your BGG username and password is\nsupported. Under the hood, these will be exchanged for a session cookie used to authenticate requests to BGG.\n\n### A word about security\n\nCredentials will be transmitted in clear using unsecured HTTP protocol from your browser to the locally running Spring\nBoot application and will only be kept in memory for the duration of the session. The API itself will use a secure HTTPS\nconnection to perform authentication to BGG.\n\n## Sample request body for logging a play\n\nendpoint: /bgg-api/api/v3/geekplay (POST, basic auth)\n\n```json\n{\n  \"ajax\": 1,\n  \"action\": \"save\",\n  \"objectid\": 1000,\n  \"objecttype\": \"thing\",\n  \"playdate\": \"2023-08-03\",\n  \"comments\": \"comments go here\",\n  \"length\": 60,\n  \"location\": \"Home\",\n  \"quantity\": 3,\n  \"players\": [\n    {\n      \"name\": \"Non-BGG Friend\",\n      \"position\": \"1\",\n      \"color\": \"blue\",\n      \"score\": \"18\",\n      \"rating\": 7,\n      \"win\": true,\n      \"new\": false\n    },\n    {\n      \"username\": \"tnaskali\",\n      \"new\": true\n    }\n  ]\n}\n```\n\n## Sample graphQL user query\n\nendpoint: /bgg-api/graphql (POST, no auth)\n\n```graphql\n{\n    userByUsername(username: \"tnaskali\") {\n        id,\n        firstname,\n        lastname,\n        username,\n        dateregistered,\n        supportyears,\n        designerid,\n        publisherid,\n        address {\n            city,\n            isocountry\n        },\n        guilds{\n            id,\n            name,\n            manager{\n                id,\n                username\n            },\n            members {\n                user {\n                    id,\n                    username\n                },\n                joined\n            }},\n        microbadges {\n            id,\n            name,\n            imagesrc\n        },\n        top{\n            boardgame{\n                rank,\n                id,\n                type,\n                name\n            }\n        }\n    }\n}\n```\n\n# Terms of use\n\nThis is just a proxy to BoardGameGeek's API, so\n[their terms of use](https://boardgamegeek.com/wiki/page/XML_API_Terms_of_Use#) still apply. Be sure to read them\nbefore deciding to use this API.\n\n# Credits and inspirations\n\n- BGG's XML API 2 : https://boardgamegeek.com/wiki/page/BGG_XML_API2\n- BGG's database structure : https://boardgamegeek.com/wiki/page/Database_Structure\n- Fisico's thread on BGG forum : https://boardgamegeek.com/thread/1010057/xml-schema-for-bgg-xml-api2\n- Reddit Thread on how to log plays\n  programmatically : https://www.reddit.com/r/boardgames/comments/ez86me/uploading_games_plays_to_bgg_programmatically/\n- Baeldung's tutorial on Spring Security Custom Authentication\n  Provider : https://www.baeldung.com/spring-security-authentication-provider\n\n# Extras\n\n## BGG Data model\n\n```mermaid\nclassDiagram\n\n%% Relationships\n    Guild \"many\" --\u003e \"many\" User: members\n    Guild \"many\" --\u003e \"1\" User: manager\n    User \"1\" --* \"1\" Collection\n    Collection \"1\" --* \"many\" Collectionitem\n    Collectionitem \"many\" --\u003e \"1\" Thing\n    Collectionitem \"many\" --\u003e \"0..1\" Version\n    User \"many\" --* \"many\" Play\n    Play \"many\" --\u003e \"1\" Thing\n    Play \"many\" --\u003e \"many\" User: players\n    User \"1\" --* \"many\" Geeklist\n    Geeklist \"1\" --* \"many\" Geeklistitem\n    Geeklist \"1\" --* \"many\" Tip\n    Geeklist \"1\" --* \"many\" Reaction\n    Geeklistitem \"many\" --\u003e \"1\" Thing\n    Geeklistitem \"1\" --* \"many\" Comment\n    Geeklistitem \"1\" --* \"many\" Tip\n    Geeklistitem \"1\" --* \"many\" Reaction\n    Blog \"1\" --* \"many\" Blogpost\n    Blogpost \"many\" --\u003e \"1\" User: author\n    Blogpost \"1\" --* \"many\" Comment\n    Blogpost \"1\" --* \"many\" Tip\n    Blogpost \"1\" --* \"many\" Reaction\n    Forum \"1\" --* \"many\" Thread\n    Thread \"many\" --\u003e \"1\" User: author\n    Thread \"many\" --\u003e \"0..1\" Geekitem\n    Thread \"1\" --* \"many\" Article\n    Thread \"1\" --* \"many\" Reaction\n    User \"1\" --* \"many\" Article\n    Article \"1\" --* \"many\" Tip\n    Article \"1\" --* \"many\" Reaction\n    Geekitem \"many\" --\u003e \"many\" Geekitem: linked items\n    Geekitem \"many\" --* \"many\" Weblink\n    Geekitem \"many\" --\u003e \"many\" User: fans\n    Comment \"many\" --\u003e \"1\" User: author\n    Comment \"1\" --* \"many\" Tip\n    Comment \"1\" --* \"many\" Reaction\n    Reaction \"many\" --\u003e \"1\" User: given by\n    Tip \"many\" --\u003e \"1\" User: given by\n%% Inheritance from Object\n    Geekitem \u003c|-- Company\n    Geekitem \u003c|-- Component\n    Geekitem \u003c|-- Event\n    Geekitem \u003c|-- Family\n    Geekitem \u003c|-- Media\n    Geekitem \u003c|-- Person\n    Geekitem \u003c|-- Property\n    Geekitem \u003c|-- Thing\n    Geekitem \u003c|-- Version\n    Geekitem \u003c|-- Weblink\n\n```","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftnaskali%2Fbgg-api","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftnaskali%2Fbgg-api","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftnaskali%2Fbgg-api/lists"}