RetroBase Collection — Public API
Read-only · hash-first · free · v1
A retro game database API for tools that identify ROMs and disc images. Look a file up by its CRC32 / MD5 / SHA-1 fingerprint and get normalized metadata and artwork back.
- No account required. Anonymous access at 60 req/min per IP.
- Self-service API keys. Create yours here — sign up and get a key in under a minute, 300 req/min. Supporter-tier keys get 1000 req/min (the data itself is free for everyone, forever — only infrastructure access is tiered).
- Transparent limits. Every response carries
X-RateLimit-Limit/X-RateLimit-Remaining; a 429 tells you when to retry viaRetry-After. - Open data. The entire catalog is served (open catalogs + community contributions), with provenance tracked field by field. Final license (ODbL expected) pending legal review — see licensing.
- Transparent coverage. Live per-platform statistics at /db/stats — no guessing what the database contains. API changes are announced on the changelog.
Quickstart
# Identify a ROM by CRC32
curl "https://retrobase-collection.com/api/public/v1/lookup?crc=50ABC90A"
# Disambiguate with size and platform
curl "https://retrobase-collection.com/api/public/v1/lookup?md5=abcd...&size=749652&platform=Mega%20Drive"
# Search by name (typo-tolerant)
curl "https://retrobase-collection.com/api/public/v1/games?search=sonic&platform=Mega%20Drive"
# With an API key (higher rate limit)
curl -H "X-Api-Key: rbk_..." "https://retrobase-collection.com/api/public/v1/lookup?crc=50ABC90A"
# Filter a platform's games: PAL releases that came out in France, with counts per filter value
curl "https://retrobase-collection.com/api/public/v1/games?platform=megadrive&standard=pal®ion[]=fr&sort=name&per_page=24&facets=1"
# Australian exclusives (released in Australia and nowhere else)
curl "https://retrobase-collection.com/api/public/v1/games?platform=megadrive®ion[]=au&exclusive=1"
# A platform's original logo (transparent SVG, or PNG capped to 256 px wide)
curl "https://retrobase-collection.com/api/public/v1/platforms/megadrive/logo?fmt=svg"
curl "https://retrobase-collection.com/api/public/v1/platforms/megadrive/logo?fmt=png&w=256"
# A game by its stable slug, with its releases per country
curl "https://retrobase-collection.com/api/public/v1/games/by-slug?platform=megadrive&slug=sonic-the-hedgehog"Endpoints
| Endpoint | Purpose |
|---|---|
| GET /lookup | Identify by fingerprint — at least one of crc, md5, sha1; optional size, platform. Returns the game and the matched dump entry. 404 if no match. |
| POST /lookup/batch | Identify up to 100 fingerprints in one request (one rate-limit hit) — built for library scanners. Results align with input order, null where nothing matches. |
| GET /games | Name search (search, platform, limit ≤ 100, offset) and filters — see Filtering games. |
| GET /games/{id} | Full record: metadata, free artwork, all known dumps, and releases[] (region, country, zone, video standard, date, regional title). |
| GET /games/by-slug | Same full record from a stable slug: ?platform=megadrive&slug=sonic-the-hedgehog. A retired slug (merged duplicate) answers with the surviving game and meta.redirect_from / meta.canonical_slug. |
| GET /games/{id}/related | Related games: same franchise first, then same genre on the same platform. |
| GET /marquee | Game artwork for a ROM: fmt=raw565&w=128&h=32&platform=megadrive&filename=…&name=…. Returns raw RGB565 little-endian bytes, exactly w × h × 2, with caching headers. fmt=anim565 returns an RBM1 animation container (looping, duration per frame); it is limited to 24 frames and 256 KiB total. |
| GET /platforms | Reference list of platforms, with manufacturer, generation, year_start/year_end, games_count, media and logo ({ png, svg }: absolute URLs of the original logo, null when it does not exist). Magazines are listed too (category is CONSOLE or MAGAZINE): add ?category=CONSOLE to keep only game platforms. |
| GET /platforms/{slug} | One platform (slug, alias, id or name). |
| GET /companies /genres /franchises | Paginated lists (search, sort=name|games, min_games, page, per_page) with each entity's public games count. Only entities with at least one public game exist. /{kind}/{slug} reads one (company aliases resolve to the canonical company). |
| GET /years /years/{year} | Years with games, and one year with its breakdown by platform. List the games with /games?year_from=1991&year_to=1991. |
| GET /home | Home feed: public counters, latest games with a cover, featured platforms (cached 10 minutes). |
| GET /stats | Detailed public counters (games, platforms, media items by family, dump fingerprints, companies, genres, franchises, years, alternative titles, synopses and their languages, releases by country, contributions), cached 6 hours. A metric that is not available is null. |
| GET /search | Multi-type search for as-you-type suggestions (q of 2 characters or more, limit ≤ 20, types=games,platforms,companies, group=title|none): games, platforms and companies in one call. See Searching. |
| GET /regions | The region reference behind the region and video-standard filters. |
| GET /platforms/{slug}/logo | The platform's original logo — transparent, never flattened: ?fmt=svg (sanitized SVG) or ?fmt=png. Without fmt: the SVG when it exists, else the PNG. w caps the width of a PNG in pixels (reduced only, transparency kept). SVGs are sent with Content-Security-Policy: default-src 'none'; style-src 'unsafe-inline' and nosniff; responses are cacheable for a long time (immutable on the versioned logo URLs of /platforms). Example: /platforms/megadrive/logo?fmt=svg. Use the marquee below only for DMD / RGB565 panels. |
| GET /platforms/{slug}/icon | Small monochrome SVG icon of the platform (distinct from its logo), meant to sit before its name in compact lists: use its shape as a mask to color it. Same sanitization, headers and caching as the SVG logo; the versioned URL is the icon field of /platforms (null when there is none). |
| GET /platform-icons | Every platform icon in one call ({slug: {v, svg}}), for a client that shows dozens of them at once instead of one request per icon. |
| GET /platforms/{system}/marquee | Console logo as fitted PNG or raw RGB565 little-endian for HUB75 panels. w and h are required and limited to 1–256. Logos are centred on black; their dark pixels are inverted so black logos stay visible on LED panels. Example: ?fmt=raw565&w=64&h=32; response is exactly 4096 bytes and supports ETag revalidation. |
| GET /status | Public counters, rate limits, service version. |
| GET /media-types | Media type taxonomy (box-2D, wheel, marquee…). |
| GET /dumps | Downloadable datasets, refreshed weekly: full json.gz dumps for offline scraping, plus Logiqx XML DATs per platform (full and community variants — the latter lists fingerprints not already in the main catalogs). Standard Logiqx format: DAT-based ROM managers ingest them as-is. |
| GET /changes | Delta feed: everything that changed since a cursor — upsert with the full record, or delete when it left the public perimeter. Keep a mirror in sync without re-downloading the weekly dump. Start with no since to get a cursor, then poll meta.next_cursor. |
| GET /games/{id}/editorial | Everything editorial about a game in one call: articles, tips, books, videos, news (limit per type, types= to pick), with meta.counts. See Editorial content. |
| GET /magazines /magazines/{slug} /magazines/{slug}/issues /magazines/{slug}/issues/{issue} | Press magazines, their issues (cover date, cover, link to the scan on a public archive) and the articles of an issue. |
| GET /articles /articles/{slug} | Press articles (reviews, previews, interviews, ads): magazine, issue, page, author, review score, a short quotation excerpt and the link to the source — never the full text. |
| GET /tips /tips/{slug} | Cheat codes (Game Genie, Action Replay, GameShark, passwords…), tips, walkthroughs, secrets and glitches of a game. |
| GET /books /books/{slug} | Books about games, platforms, franchises and companies (ISBN, authors, publisher, links). |
| GET /videos /videos/{slug} | Referenced videos (trailers, gameplay, reviews, documentaries…): provider + identifier, never a file. |
| GET /news /news/{slug} | RetroBase news, most recent first (the detail carries the full text). |
| GET /editorial /editorial/search | Counters per content type and the latest news; multi-type SQL search over every editorial title (q, limit ≤ 20, types). |
| GET /openapi.json | The complete OpenAPI 3 specification. |
Filtering games
GET /games accepts, on top of search, platform, limit and offset (unchanged):
| Parameter | Meaning |
|---|---|
region[] | Release region(s), OR between values (region[]=fr®ion[]=de or region=fr,de). A country matches only games with a release tied to it; the macro-regions eu, asi, ame, oce, mor also cover their countries. A pan-European release is not a French release. |
standard | pal | ntsc-u | ntsc-j — games with at least one release in that family. |
exclusive=1 | With region[] and/or standard: released only there (region[]=au&exclusive=1 = Australian exclusives; standard=pal&exclusive=1 = PAL only). |
genre, franchise, publisher, developer, company | Entity slug or name (company = published or developed). |
year_from, year_to, players, letter | Release year bounds, number of players supported, first letter (A–Z, or %23 for #). |
has_media[] | Required public media (AND): cover, box3d, back, support, screenshot, logo, marquee, fanart, video, manual. |
sort, order | name | year | rating | added, asc | desc. Ties are broken by name then id: pagination is stable. |
page, per_page | Page-style pagination (adds page, per_page, last_page to meta). |
fields=card | Compact cards (id, slug, name, platform, year, genre, cover…) instead of the full game. |
facets=1 | Counts per filter value in meta.facets (region, standard, genre, year, players, letter, publisher, developer). Each facet is computed without its own filter. Ask exclusive and has_media by name (or facets=all). |
Region codes, countries, geographic zones and video standards are in GET /regions. Ambiguities are settled there: Brazil counts as NTSC-U (its real PAL-M signal is exposed as video), "Asia" as NTSC-J, and wor (World) is a release only when a dump is explicitly tagged "(World)". Releases are derived from regional titles, regional box art, dump file names and imported dates; each release carries its source.
Searching
GET /search ranks results by tiers instead of raw substring matching, so son returns Sonic… and Songbird… before Super Sonic Racing, and never Crimson Tears unless nothing better fills the list. Case, accents, punctuation and spaces are ignored: mega man, megaman and mega-man are the same query.
| Tier | A game matches when… |
|---|---|
| 0 | its name equals the term. |
| 1 | its name starts with the term. |
| 2 | a word of its name starts with the term (son → Super Sonic Racing). |
| 3 | a regional title starts with the term, or has a word that does (biohazard → Resident Evil). |
| 4 | fuzzy match (trigram similarity ≥ 0.3): only used to fill the list when tiers 0–3 do not reach limit, and never for a term of 1–2 characters. |
Inside a tier: the title released on the most platforms first, then the shortest name, then alphabetical order, then id. GET /games?search= uses the same tiers 0–2 for its order — then regional and fuzzy matches by similarity — and keeps every substring match (the full search page), without the platform-count criterion.
group=title returns one entry per title (the same normalized name on any number of platforms) instead of one per game, and meta.totals.games counts titles. Each entry is the usual game card of the best version (with a cover, then on the platform with the most games) plus variants:
{ "name": "Sonic The Hedgehog", "platform": { "slug": "gg", … },
"variants": { "count": 5,
"platforms": [ { "slug": "megadrive", "name": "Sega Mega Drive" }, … ] } }variants.platforms lists up to 12 platforms, the most stocked first; variants.count is the total number of distinct platforms. Without group (or group=none) nothing changes: one entry per game, no variants. Platforms never include magazines; companies are ranked the same way (starts with, word, substring, alias) and appear once under their canonical slug.
Editorial content
Magazines, press articles, tips and cheat codes, books, videos and news live in the same database and the same public perimeter as the games. Same { data, meta } envelope, same quotas. Only published items are served, and an item never reveals a game, company or franchise that is outside the public catalog.
| Parameter | Meaning |
|---|---|
game, platform, company, franchise | Content linked to that game (uuid), platform, company or franchise slug. A platform, company or franchise also matches content linked to one of its public games. |
search, language, sort, order, page, per_page | Common to every list. Words contained in the title (and excerpt, author, effect…), ISO 639-1 language, page-style pagination (adds total, page, per_page, last_page to meta). |
/articles: magazine, issue, role, year, has_score | Role of the article for its game: review, preview, interview, ad, report, guide. |
/tips: kind, code_system, region, verified | kind: code | tip | walkthrough | secret | glitch; code_system: game_genie, action_replay, gameshark, password… |
/books: isbn, author, year, book_type | ISBN-10 or ISBN-13, hyphens ignored. |
/videos: type, provider | embed_url is the cookie-less player (youtube-nocookie.com), to load on click. |
/news: tag, year | Lists carry the lede; body is in the detail. |
# Everything editorial about a game
curl "https://retrobase-collection.com/api/public/v1/games/{id}/editorial"
# Cheat codes for a platform, Game Genie only
curl "https://retrobase-collection.com/api/public/v1/tips?platform=megadrive&kind=code&code_system=game_genie"
# Reviews of a magazine issue
curl "https://retrobase-collection.com/api/public/v1/magazines/joypad/issues/12"
# Press articles about a game, reviews only
curl "https://retrobase-collection.com/api/public/v1/articles?game={id}&role=review"Copyright: RetroBase publishes metadata, short quotation excerpts and links to public archives — never a protected article in full, never a video file. Every item carries a source block (name, url, license, attribution): display the attribution line when you show the item. Takedown requests: see /legal.
Response envelope
Game and platform marquees use binary responses (no JSON envelope). System ids such as snes and megadrive resolve through the platform slug or imported aliases. Platform marquee responses include source, license, attribution, and image-change headers.
To register a game animation, add public media entries with type marquee-animation-frame, a zero-based frame_index, a public pool url, and optional duration_ms (100–2000; default 250). Frames are sent in index order; loop count 0 means forever.
{
"data": { "game": { "id": "…", "name": "Sonic The Hedgehog 2", "platform": { "name": "Sega Mega Drive" },
"year": "1992", "media": [ { "type": "box-2D", "region": "eu", "url": "…" } ] },
"dump": { "crc": "50ABC90A", "region": "eu", "dump_source": "no-intro" } },
"meta": { "license": "…", "attribution": "RetroBase Collection — https://retrobase-collection.com",
"docs": "https://retrobase-collection.com/developers" }
}Errors: { "error": { "code": "missing_fingerprint", "message": "…" } } with proper HTTP statuses (400, 404, 429). Lookup/search responses are cacheable (Cache-Control: public, max-age=3600).
Attribution
If you use this API in your project, a visible mention of “Data: RetroBase Collection” with a link to retrobase-collection.com is appreciated (and will be required by the final data license).
Contact
Integrating a frontend or scraper? We are happy to help: contact@ixelia.fr. Content takedown requests: see /legal.