# BoardGameGeek Scraper — games, rankings, ratings & reviews (`istmobot/boardgamegeek-scraper`) Actor

Scrape BoardGameGeek (BGG) board game data without an API key: rank, Geek rating, average rating, number of ratings, weight, player counts, play time, designers, publishers, mechanics and user reviews. Get the Hotness list, top-ranked games and games by designer or mechanic.

- **URL**: https://apify.com/istmobot/boardgamegeek-scraper.md
- **Developed by:** [Istmobot](https://apify.com/istmobot) (community)
- **Categories:** Other
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

Pay per event

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## BoardGameGeek Scraper — games, rankings, ratings & reviews

**BoardGameGeek Scraper** extracts board game data from **BoardGameGeek (BGG)**: overall rank, Geek rating, average rating, number of ratings, complexity weight, player counts, play time, designers, publishers, mechanics, categories, images and user reviews. Scrape any list of games, the BGG **Hotness** list, the **top-ranked** games, or every game of a designer, publisher or mechanic, with no BGG account or XML API token. Export the data to JSON, CSV, Excel or HTML, or pull it through the Apify API.

### What is BoardGameGeek Scraper?

BoardGameGeek Scraper is an unofficial **BoardGameGeek API alternative**. BGG's XML API now requires registration and returns 403 to anonymous requests. This Actor reads the same public JSON endpoints the BGG website uses, so you don't need an **API key**, an XML API token or a login.

It can scrape:

- **Game details** for any list of BGG game IDs or URLs (expansions too).
- **Hotness**: the games currently trending on BGG (up to 50).
- **Top ranked**: the overall BGG Board Game Rank from #1 down (top 100, 500, 1,000…).
- **Games by designer, artist, publisher, mechanic, category or family**, best-ranked first (e.g. all cooperative games, all Stonemaier games, all Uwe Rosenberg designs).
- **Reviews** (optional): the newest written user comments with username, rating, text and date.

Results land in an Apify dataset you can download as **JSON, CSV, Excel, HTML** or XML, or read through the API.

#### What data can I extract with BoardGameGeek Scraper?

| Field | Description |
|---|---|
| `name`, `id`, `url` | Game name, BGG ID and page URL |
| `yearPublished` | Year the game was published |
| `rank` | Overall BGG Board Game Rank (`null` if unranked) |
| `bayesAverage` | BGG "Geek Rating", the score used for the ranking |
| `average` | Plain average user rating |
| `usersRated` | Number of user ratings |
| `weight` | Complexity, 1 (light) to 5 (heavy) |
| `owned`, `wishing`, `trading` | Users who own it, wishlist it, or offer it for trade |
| `minPlayers`, `maxPlayers` | Player count range |
| `bestPlayers` | Best player count from the community poll, e.g. `"3-4"` |
| `minPlaytime`, `maxPlaytime` | Play time in minutes |
| `minAge` | Minimum age |
| `designers`, `artists`, `publishers` | People and companies behind the game |
| `mechanics`, `categories`, `families` | BGG classification tags |
| `image`, `thumbnail` | Box art image URLs |
| `shortDescription` | One-line game description |
| `reviews` | Newest written reviews: `username`, `rating`, `text`, `date` (optional) |
| `scrapedAt` | Time the record was scraped |

### How can I use BoardGameGeek data?

- **Board game publishers and designers**: benchmark competitors' ratings, weight and ownership, and track rank movement.
- **Retailers and e-commerce**: enrich product catalogs with ratings, player counts, play time and images.
- **Content creators and bloggers**: build "top cooperative games" or "best 2-player games" lists from real data.
- **Data analysts and hobbyists**: study trends in mechanics, categories and complexity over time.
- **Crowdfunding researchers**: see what's hot right now and what reviewers say.
- **Recommendation apps**: feed game metadata and ratings into a recommender or search index.

### How to scrape BoardGameGeek data

1. Click **Try for free** on this page to open the Actor in Apify Console (a free Apify account is enough).
2. Pick a **Mode**: specific games, Hotness, Top ranked, or games by designer / publisher / mechanic / category / family.
3. Fill the matching input: game IDs or URLs, or a link type and ID, and **Max games**. Turn on **Include reviews** if you want user comments.
4. Click **Start** and wait for the run to finish.
5. Open the **Output** tab and download the dataset as JSON, CSV, Excel or HTML, or fetch it through the API.

### How much does it cost to scrape BoardGameGeek?

The Actor uses **pay-per-event** pricing, so you pay only for the games you get:

| Event | Price |
|---|---|
| Actor start | $0.005 per run |
| `game-result` | $0.002 per game ($2.00 per 1,000 games) |

**Reviews are included at no extra charge.** Error items (games not found, invalid IDs, failed requests) are **never charged**.

Example: one run that scrapes 1,000 games costs $0.005 + $2.00 = **$2.005**.

The Apify free plan gives you **$5 of credit every month**, which covers roughly **2,500 games** per month. You can set a **maximum cost per run**: when it is reached, the Actor stops cleanly and keeps the results already scraped.

### ⬇️ Input

| Field | Type | Default | Description |
|---|---|---|---|
| `mode` | `games` | `hotness` | `topRanked` | `linkedItems` | `games` | What to scrape |
| `gameIds` | list of strings | — | `games` mode: IDs (`174430`) or URLs (`https://boardgamegeek.com/boardgame/13/catan`) |
| `linkType` | `designer` | `artist` | `publisher` | `mechanic` | `category` | `family` | `designer` | `linkedItems` mode |
| `linkId` | string | — | `linkedItems` mode: numeric ID, or a BGG URL (then `linkType` is detected from it) |
| `maxItems` | integer | `50` | Max games in listing modes (Hotness has at most 50). Ignored in `games` mode |
| `includeReviews` | boolean | `false` | Add the newest written reviews |
| `maxReviewsPerGame` | integer | `20` | Reviews per game when `includeReviews` is on |

```json
{
  "mode": "games",
  "gameIds": ["174430", "https://boardgamegeek.com/boardgame/224517/brass-birmingham", "13"],
  "includeReviews": true,
  "maxReviewsPerGame": 20
}
```

More examples:

- Top 100 games: `{ "mode": "topRanked", "maxItems": 100 }`
- All cooperative games, best first: `{ "mode": "linkedItems", "linkType": "mechanic", "linkId": "2023", "maxItems": 500 }`
- One designer's games: `{ "mode": "linkedItems", "linkId": "https://boardgamegeek.com/boardgamedesigner/69802/isaac-childres" }`

Find an ID in any BGG URL: `boardgamegeek.com/boardgamemechanic/`**`2023`**`/cooperative-game`.

### ⬆️ Output

One dataset item per game. The **Overview** table view in the Output tab shows image, name, year, rank, ratings, weight, players, play time, owners, designers and URL.

```json
{
  "id": 224517,
  "name": "Brass: Birmingham",
  "url": "https://boardgamegeek.com/boardgame/224517/brass-birmingham",
  "yearPublished": 2018,
  "rank": 1,
  "bayesAverage": 8.39,
  "average": 8.559,
  "usersRated": 60386,
  "weight": 3.86,
  "owned": 86682,
  "wishing": 22503,
  "trading": 388,
  "minPlayers": 2,
  "maxPlayers": 4,
  "bestPlayers": "3-4",
  "minPlaytime": 60,
  "maxPlaytime": 120,
  "minAge": 14,
  "designers": ["Gavan Brown", "Matt Tolman", "Martin Wallace"],
  "artists": ["Gavan Brown", "Lina Cossette", "David Forest"],
  "publishers": ["Roxley", "Arclight Games", "Funforge"],
  "mechanics": ["Hand Management", "Loans", "Market", "Network and Route Building"],
  "categories": ["Economic", "Industry / Manufacturing", "Trains"],
  "families": ["Country: England", "Crowdfunding: Kickstarter"],
  "image": "https://cf.geekdo-images.com/x3zxjr-Vw5iU4yDPg70Jgw__original/img/FpyxH41Y6_ROoePAilPNEhXnzO8=/0x0/filters:format(jpeg)/pic3490053.jpg",
  "thumbnail": "https://cf.geekdo-images.com/x3zxjr-Vw5iU4yDPg70Jgw__small/img/o18rjEemoWaVru9Y2TyPwuIaRfE=/fit-in/200x150/filters:strip_icc()/pic3490053.jpg",
  "shortDescription": "Build networks, grow industries, and navigate the world of the Industrial Revolution.",
  "reviews": [
    { "username": "powersland", "rating": 8, "text": "I actually think this is one of my favorite games...", "date": "2026-09-30 19:29:45" }
  ],
  "scrapedAt": "2026-10-01T01:39:59.406Z"
}
```

Notes on fields:

- `reviews` is present only with `includeReviews: true`. `rating` is `null` when the user commented without rating. `date` is when the comment was written (BGG server time).
- `bestPlayers` can list several values, e.g. `"3, 5"`, and is `null` when the poll has no result.

#### Error items

If a game can't be scraped, the dataset gets an error item instead (free of charge):

```json
{ "id": 999999999, "url": "https://boardgamegeek.com/boardgame/999999999", "errorType": "NOT_FOUND", "error": "No BGG item with id 999999999", "scrapedAt": "2026-10-01T01:40:02.112Z" }
```

`errorType` is `NOT_FOUND`, `INVALID_GAME_ID`, `FETCH_FAILED` or `LISTING_FAILED`.

### Integrations and API

Run BoardGameGeek Scraper programmatically with the [Apify API](https://docs.apify.com/api/v2). Actor ID: `istmobot/boardgamegeek-scraper`.

**Python** (`pip install apify-client`):

```python
from apify_client import ApifyClient

client = ApifyClient("<YOUR_API_TOKEN>")
run = client.actor("istmobot/boardgamegeek-scraper").call(run_input={
    "mode": "topRanked",
    "maxItems": 100,
})
for game in client.dataset(run["defaultDatasetId"]).iterate_items():
    print(game.get("rank"), game.get("name"), game.get("bayesAverage"))
```

**Node.js** (`npm install apify-client`):

```javascript
import { ApifyClient } from 'apify-client';

const client = new ApifyClient({ token: '<YOUR_API_TOKEN>' });
const run = await client.actor('istmobot/boardgamegeek-scraper').call({
    mode: 'hotness',
    maxItems: 50,
});
const { items } = await client.dataset(run.defaultDatasetId).listItems();
console.log(items);
```

**HTTP**: start a run and get the dataset items in one call:

```bash
curl -X POST "https://api.apify.com/v2/acts/istmobot~boardgamegeek-scraper/run-sync-get-dataset-items?token=<YOUR_API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"mode": "games", "gameIds": ["174430", "13"]}'
```

You can also:

- **Schedule** runs (e.g. a daily `topRanked` or `hotness` snapshot) with [Apify Schedules](https://docs.apify.com/platform/schedules).
- Trigger **webhooks** when a run finishes.
- Connect the data to **Make, Zapier, n8n**, Google Sheets, Slack and other tools through Apify integrations.
- Use it from **AI agents** (Claude, ChatGPT, Cursor and others) via the [Apify MCP server](https://mcp.apify.com).

### FAQ

**Do I need a BGG account or API token?**
No. The Actor reads public data without logging in and without an XML API token.

**How does "top ranked" work?**
BGG's browse pages are behind Cloudflare, so the Actor rebuilds the overall ranking from the ranked lists of BGG's eight game subdomains (Strategy, Thematic, Family, Party, Abstract, Children's, Customizable, Wargames). Every row carries the real overall rank. A ranked game that belongs to no subdomain would be missing; the log warns if any rank position is not found (none in the top 200 at the time of writing).

**Does it support expansions?**
Yes, in `games` mode: pass the expansion's ID or URL. Listing modes return what BGG lists.

**How fast is it? Are there limits?**
About 2 requests per game (plus review pages, 50 reviews per page), with 3 games processed in parallel. Rate limits and server errors are retried automatically with backoff. The Hotness list has at most 50 games; other listing modes go as deep as `maxItems`.

**Can I track rank history?**
Yes. Schedule the Actor (e.g. a daily `topRanked` run) and compare the datasets between runs.

**Can I schedule it?**
Yes. Use [Apify Schedules](https://docs.apify.com/platform/schedules) to run it hourly, daily or weekly, and a webhook or integration to send each new dataset where you need it.

**Is it legal to scrape BoardGameGeek?**
This Actor only collects publicly available data from public endpoints. It does not log in and does not bypass access controls. Reviews include public usernames, which can count as personal data under the GDPR and similar laws, so only collect and store it if you have a legitimate reason. You are responsible for using the data in line with applicable laws and BoardGameGeek's terms of service. If you're unsure, consult a lawyer.

This is an **unofficial** tool. It is not affiliated with, endorsed by or sponsored by BoardGameGeek, LLC.

### Other Actors you might like

- [Metacritic Scraper](https://apify.com/istmobot/metacritic-scraper)
- [Steam Game Intelligence](https://apify.com/istmobot/steam-game-intelligence)
- [Earnings Call Transcripts Scraper](https://apify.com/istmobot/earnings-call-transcripts-scraper)
- [Zacks Rank Scraper](https://apify.com/istmobot/zacks-rank-scraper)

### Your feedback

Found a bug or missing a field? Open an issue in the **Issues** tab and we'll take a look.

# Actor input Schema

## `mode` (type: `string`):

"games": the game IDs / URLs you list. "hotness": BGG's current Hotness list (max 50). "topRanked": the overall BGG ranking from #1. "linkedItems": all games of a designer, artist, publisher, mechanic, category or family, best-ranked first.

## `gameIds` (type: `array`):

Used in "games" mode. Numeric IDs (174430) or URLs like https://boardgamegeek.com/boardgame/13/catan.

## `linkType` (type: `string`):

Used in "linkedItems" mode together with Link ID. Not needed if Link ID is a full BGG URL.

## `linkId` (type: `string`):

Used in "linkedItems" mode. Numeric ID (2023 = Cooperative Game mechanic) or a BGG URL like https://boardgamegeek.com/boardgamedesigner/69802/isaac-childres.

## `maxItems` (type: `integer`):

How many games to return in hotness / topRanked / linkedItems mode. Ignored in "games" mode.

## `includeReviews` (type: `boolean`):

Add the newest written user comments (username, rating, text, date) to each game.

## `maxReviewsPerGame` (type: `integer`):

Number of reviews per game when reviews are included.

## Actor input object example

```json
{
  "mode": "games",
  "gameIds": [
    "174430",
    "https://boardgamegeek.com/boardgame/224517/brass-birmingham",
    "13"
  ],
  "linkType": "mechanic",
  "linkId": "2023",
  "maxItems": 20,
  "includeReviews": false,
  "maxReviewsPerGame": 20
}
```

# Actor output Schema

## `results` (type: `string`):

No description

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "mode": "games",
    "gameIds": [
        "174430",
        "https://boardgamegeek.com/boardgame/224517/brass-birmingham",
        "13"
    ],
    "linkType": "mechanic",
    "linkId": "2023",
    "maxItems": 20
};

// Run the Actor and wait for it to finish
const run = await client.actor("istmobot/boardgamegeek-scraper").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "mode": "games",
    "gameIds": [
        "174430",
        "https://boardgamegeek.com/boardgame/224517/brass-birmingham",
        "13",
    ],
    "linkType": "mechanic",
    "linkId": "2023",
    "maxItems": 20,
}

# Run the Actor and wait for it to finish
run = client.actor("istmobot/boardgamegeek-scraper").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "mode": "games",
  "gameIds": [
    "174430",
    "https://boardgamegeek.com/boardgame/224517/brass-birmingham",
    "13"
  ],
  "linkType": "mechanic",
  "linkId": "2023",
  "maxItems": 20
}' |
apify call istmobot/boardgamegeek-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,istmobot/boardgamegeek-scraper"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/mJolbPimX0FS7nmXe/builds/4QHTRmjeEu7meSkVn/openapi.json