Planszeo APIplanszeo.pl ↗
Search the planszeo.pl board game database and fetch full game details — ratings, authors, shop offers, tags, and more — via 2 JSON endpoints.
What is the Planszeo API?
The Planszeo.pl API gives developers access to Poland's board game database through 2 endpoints: search_games and get_game. search_games returns up to 35 game summaries per page with filters for mechanic, theme, difficulty, price, age, and badge lists. get_game returns a full game record including community rating, author list, shop offers with prices in PLN, gallery images, and mechanic/theme tags.
curl -X GET 'https://api.parse.bot/scraper/3ee27cd7-972b-4888-8923-89032cdbeb6d/search_games?query=Vlaada+Chv%C3%A1til&mechanic=Draft+element%C3%B3w&difficulty=3' \ -H 'X-API-Key: $PARSE_API_KEY'
Typed, relational, agent-ready
A generated client with real types, enums, and the links between objects — the structure a flat JSON response can't carry. Autocompletes in your editor and reads cleanly to coding agents.
- Fully typed · autocompletes
- Objects link to objects
- Typed errors & pagination
Typed Python client. Set up the SDK in your uv project, then pull this API’s typed client:
uv add parse-sdk uv run parse init uv run parse add --marketplace planszeo-pl-api
uv run parse add --marketplace pulls a pinned snapshot of this canonical API — it won’t change underneath you. To customize it, subscribe and swap to your own copy.
"""Walkthrough: search Polish board-game database, drill into full details."""
from parse_apis.planszeo_pl_api import Planszeo, Difficulty, GameNotFound
client = Planszeo()
# Browse hard strategy games currently in stock, capped to 5 results.
for summary in client.game_summaries.search(
difficulty=Difficulty.HARD,
only_available=True,
limit=5,
):
print(summary.title, summary.rating, summary.lowest_price_pln)
# Drill into the first matching game's full record via summary→detail nav.
hit = client.game_summaries.search(
query="Cywilizacja",
only_base_games=True,
limit=1,
).first()
if hit is not None:
game = hit.details()
print(game.title, game.rating, f"{game.players_min}-{game.players_max} players")
print("Authors:", ", ".join(game.authors))
if game.polish_publisher is not None:
print("Polish publisher:", game.polish_publisher.name)
# Show cheapest available shop offer.
for offer in game.offers:
if offer.available:
print(f" {offer.shop}: {offer.price_pln} PLN ({offer.city})")
break
# Direct point-lookup when the slug is already known.
try:
detail = client.games.get(slug="brass-birmingham")
print(detail.title, detail.tags)
except GameNotFound:
print("Game not found.")
print("exercised: game_summaries.search / details / games.get")
Searches the planszeo.pl board game database and returns one page of 35 game summaries (title, slug, image, rating, rating count, lowest shop price in PLN, availability, player count range, playtime range in minutes, minimum age, difficulty 1-3, mechanic/theme tags). With no filters the whole database is listed (about 1010 pages). All filters combine (AND). Pagination: one round trip per call; pass `page` (1-based, default 1) and use `total_pages` / `has_more` to continue; a page beyond `total_pages` returns an empty `games` array. Text search on the title/author also matches fuzzily, so an unknown term may still return loosely related games rather than an empty result. Fields that a game lacks on the site (rating, price, difficulty, age) are null.
| Param | Type | Description |
|---|---|---|
| list | string | Badge/list filter, exactly as labelled in the site's 'Odznaki/listy' dropdown (e.g. Essen Spiel '23). Unknown values return no results. |
| page | integer | 1-based result page; each page holds up to 35 games. |
| query | string | Free-text search on game title or author name (e.g. an author's full name). |
| theme | string | Theme filter, exactly as labelled in the site's 'Tematyka' dropdown; values are the same strings that appear in `tags` (e.g. Fantasy). |
| min_age | integer | Minimum recommended age filter (years). |
| mechanic | string | Mechanic filter, exactly as labelled in the site's 'Mechanika' dropdown; values are the same strings that appear in `tags` (e.g. Draft elementów, Budowanie talii). |
| price_to | integer | Upper bound of the lowest shop price in PLN. |
| difficulty | string | Difficulty level filter. Omitted = any difficulty. |
| players_to | integer | Upper bound of the supported player count. |
| price_from | integer | Lower bound of the lowest shop price in PLN. |
| playtime_to | integer | Upper bound of playtime in minutes. |
| players_from | integer | Lower bound of the supported player count. |
| playtime_from | integer | Lower bound of playtime in minutes. |
| only_available | boolean | Only games currently available in at least one shop. |
| only_base_games | boolean | Only base games (exclude expansions). |
| only_expansions | boolean | Only expansions. |
| polish_editions | boolean | Only Polish editions. |
| ukrainian_rules | boolean | Only games with a Ukrainian rulebook. |
| language_independent | boolean | Only language-independent games. |
{
"type": "object",
"fields": {
"page": "integer, the page returned",
"games": "array of game summaries; each has slug (input for get_game), title, url, image_url, kind (Gra podstawowa = base game, Dodatek = expansion), rating (0-10, null if unrated), rating_count, lowest_price_pln (null when no shop offer), available, players_min, players_max, playtime_min, playtime_max (minutes), min_age, difficulty (1-3 or null), tags (mechanic/theme labels)",
"has_more": "boolean, true when page < total_pages",
"total_pages": "integer, number of result pages for these filters (0 when nothing matched)"
},
"sample": {
"data": {
"page": 1,
"games": [
{
"url": "https://planszeo.pl/gry-planszowe/mage-knight-ultimate-edition",
"kind": "Gra podstawowa",
"slug": "mage-knight-ultimate-edition",
"tags": [
"Budowanie talii",
"Draft elementów",
"Eksploracja",
"Fantasy",
"Gra kooperacyjna",
"Gra przygodowa",
"Tryb solo",
"Walka",
"Zarządzanie ręką kart"
],
"title": "Mage Knight: Ultimate Edition",
"rating": 8.8,
"min_age": 14,
"available": true,
"image_url": "https://planszeo.fsn1.your-objectstorage.com/avw3drc28pzwalfuihk1w7kj8xh1",
"difficulty": 3,
"players_max": 4,
"players_min": 1,
"playtime_max": 240,
"playtime_min": 60,
"rating_count": 388,
"lowest_price_pln": 342.79
}
],
"has_more": false,
"total_pages": 1
},
"status": "success"
}
}About the Planszeo API
Search and Filter the Board Game Catalog
search_games accepts a free-text query (title or author name) alongside structured filters: mechanic and theme match the exact labels shown in the site's dropdowns, difficulty accepts one of three levels, min_age filters by recommended player age, and price_to sets an upper bound on the lowest shop price in PLN. Results are paginated at 35 games per page; the response includes total_pages and has_more so you can walk every page. Each summary in the games array contains slug, title, image_url, rating, rating_count, kind (base game or expansion), player count range, playtime range, and availability.
Full Game Records
get_game takes a slug from the search results and returns the complete database entry. The offers array lists individual shop listings with shop, price_pln, available, shipping_from_pln, free_shipping_from_pln, and city — useful for price comparison across Polish retailers. The authors array contains contributor names, and tags combines mechanic and theme labels into a single list. images provides up to 12 gallery URLs. rating is a community score from 0–10 (null if no ratings exist), and min_age, premiere, and reprint dates are included when the source lists them.
Coverage and Data Shape
All monetary values are in PLN. Dates follow DD.MM.YYYY format. The kind field distinguishes base games (Gra podstawowa) from expansions (Dodatek). Filter strings for mechanic, theme, and list must match the site's labels exactly — there is no endpoint to enumerate valid filter values, so inspect the site's dropdowns or the tags fields in existing results to discover them.
The Planszeo API is a managed, monitored endpoint for planszeo.pl — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when planszeo.pl changes and a check fails, the API is automatically queued for repair and re-verified. It is built to keep working as the site underneath it changes.
This isn't an official planszeo.pl API — it's an independent, maintained REST wrapper over public data. Where the source has no official API (or only a limited one), Parse gives you a stable contract over a source that never promised one, and keeps it current. Need a new endpoint or field? You can revise it yourself in plain English and the agent rebuilds it against the live site in minutes — contributing the change back to the shared API is free.
Will this API break when the source site changes?+
Is this an official API from the source site?+
Can I fix or extend this API myself if I need a new endpoint or field?+
What happens if I call an endpoint that has an issue?+
- Build a price-comparison tool for board games across Polish online shops using the
offersarray fromget_game. - Display community ratings and player-count ranges for game recommendations in a hobby app.
- Filter new releases by mechanic (e.g. 'deck building') and difficulty to power a game discovery feature.
- Track availability and price changes for specific game slugs by polling
get_gameperiodically. - Compile a dataset of expansions by filtering
search_gamesresults wherekindequals 'Dodatek'. - Populate a board game shelf app with cover images, author names, and playtime data from
get_game. - Search by author name using the
queryparameter to list all titles attributed to a specific designer.
| Tier | Price | Credits/month | Rate limit |
|---|---|---|---|
| Free | $0/mo | 200 | 5 req/min |
| Hobby | $30/mo | 1,000 | 20 req/min |
| Developer | $100/mo | 5,000 | 100 req/min |
| Team | $300/mo | 20,000 | 300 req/min |
| Company | $1,000/mo | 100,000 | 500 req/min |
Each endpoint has a fixed posted price per successful call — most fall between 1 and 10 credits — shown on this API's page before you run it. Exceeding the rate limit returns a 429 response. Authenticate with the X-API-Key header.
Does planszeo.pl have an official developer API?+
What does `search_games` return and how does pagination work?+
total_pages (total result pages for the current filters) and has_more (true when more pages exist). Increment the page parameter starting from 1 to walk through all results. When nothing matches, total_pages returns 0.What shop data is available in `get_game`?+
offers array lists each retailer offer with shop name, price_pln, available (boolean), shipping_from_pln, free_shipping_from_pln, and city. Offers reflect what the site currently lists; availability and prices may change between requests. The API does not expose historical pricing data.Are user reviews or individual user collections covered?+
Is there an endpoint to list all valid `mechanic` or `theme` filter values?+
search_games and get_game but no dedicated endpoint for enumerating filter options. You can inspect the tags field in get_game responses to discover label strings, or fork the API on Parse and revise it to add a filter-values lookup endpoint.