The LEGO dataset behind BrickVault,
as two CSV files.
Every set. Every minifigure. Current market values, retail prices, used values, themes, piece counts, seller guide pricing and minifigure contents. Rebuilt every day, and one HTTPS request away. No SDK, no scraping.
Two files
Plain CSV that opens straight in Excel, Numbers and Google Sheets, and loads
with pandas.read_csv() without a single argument.
Sets
Every LEGO set in the catalogue, from grails to polybags.
GET /api/v1/sets.csv
Minifigures
Every minifigure, and the sets each one appears in.
GET /api/v1/minifigs.csv
Ready to pull the data?
Generate a key on your account and start pulling the catalogue. Included with BrickVault Pro.
Downloading it
One key, one request, any language. Send it as a bearer token, an
X-API-Key header, or a ?key= parameter if you just want a
URL that works in a browser. Every snippet below is complete and runnable.
import requests
API_KEY = "bv_live_your_key_here"
r = requests.get(
"https://brickvault.app/api/v1/sets.csv",
headers={"Authorization": f"Bearer {API_KEY}"},
timeout=180,
)
r.raise_for_status() # 401 bad key, 402 not Pro, 429 daily limit
with open("brickvault-sets.csv", "wb") as fh:
fh.write(r.content)
print("rows: ", r.headers["X-BrickVault-Rows"])
print("generated: ", r.headers["X-BrickVault-Generated"])
print("left today:", r.headers["X-BrickVault-Downloads-Remaining"])
import pandas as pd
API_KEY = "bv_live_your_key_here"
AUTH = {"Authorization": f"Bearer {API_KEY}"}
sets = pd.read_csv("https://brickvault.app/api/v1/sets.csv", storage_options=AUTH)
figs = pd.read_csv("https://brickvault.app/api/v1/minifigs.csv", storage_options=AUTH)
print(f"{len(sets):,} sets, {sets.current_price_usd.notna().sum():,} priced")
print(sets.head())
# Bearer token, the normal way
curl -H "Authorization: Bearer bv_live_your_key_here" \
-o brickvault-sets.csv \
https://brickvault.app/api/v1/sets.csv
# Minifigures
curl -H "Authorization: Bearer bv_live_your_key_here" \
-o brickvault-minifigs.csv \
https://brickvault.app/api/v1/minifigs.csv
# As a plain URL, for anywhere that cannot set a header
curl -o brickvault-sets.csv \
"https://brickvault.app/api/v1/sets.csv?key=bv_live_your_key_here"
# Check freshness without spending one of the day's five
curl -I -H "Authorization: Bearer bv_live_your_key_here" \
https://brickvault.app/api/v1/sets.csv
import { writeFile } from "node:fs/promises";
const API_KEY = "bv_live_your_key_here";
const res = await fetch("https://brickvault.app/api/v1/sets.csv", {
headers: { Authorization: `Bearer ${API_KEY}` },
});
if (!res.ok) {
// 401 bad key . 402 account is not on Pro . 429 daily limit reached
const { message } = await res.json();
throw new Error(`${res.status}: ${message}`);
}
console.log("rows:", res.headers.get("X-BrickVault-Rows"));
console.log("left today:", res.headers.get("X-BrickVault-Downloads-Remaining"));
await writeFile("brickvault-sets.csv", Buffer.from(await res.arrayBuffer()));
<?php
$key = 'bv_live_your_key_here';
$ch = curl_init('https://brickvault.app/api/v1/sets.csv');
curl_setopt_array($ch, [
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $key],
CURLOPT_RETURNTRANSFER => true,
CURLOPT_TIMEOUT => 300,
]);
$body = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
if ($status !== 200) {
throw new RuntimeException("BrickVault returned $status: $body");
}
file_put_contents('brickvault-sets.csv', $body);
// Then read it row by row without loading 5 MB into memory
$fh = fopen('brickvault-sets.csv', 'r');
$cols = fgetcsv($fh);
while (($row = fgetcsv($fh)) !== false) {
$set = array_combine($cols, $row);
// $set['set_number'], $set['name'], $set['current_price_usd'] ...
}
fclose($fh);
library(readr)
library(dplyr)
key <- "bv_live_your_key_here"
sets <- read_csv(
"https://brickvault.app/api/v1/sets.csv",
col_types = cols(set_number = col_character(),
set_number_base = col_character()),
# httr-style auth via the URL, so no extra package is needed
) # or: read_csv(paste0(url, "?key=", key))
sets %>%
filter(!is.na(current_price_usd), retail_price_usd > 0,
grepl("retired", badges)) %>%
mutate(multiple = current_price_usd / retail_price_usd) %>%
arrange(desc(multiple)) %>%
select(set_number, name, theme, retail_price_usd, current_price_usd, multiple) %>%
head(20)
// Extensions > Apps Script, then run refreshBrickVault() or put it on a
// daily trigger. Writes the whole catalogue to a "Market" sheet you can
// VLOOKUP against from your own list of sets.
const API_KEY = 'bv_live_your_key_here';
function refreshBrickVault() {
const res = UrlFetchApp.fetch('https://brickvault.app/api/v1/sets.csv', {
headers: { Authorization: 'Bearer ' + API_KEY },
muteHttpExceptions: true,
});
if (res.getResponseCode() !== 200) {
throw new Error('BrickVault: ' + res.getContentText());
}
const rows = Utilities.parseCsv(res.getContentText());
const ss = SpreadsheetApp.getActive();
const sh = ss.getSheetByName('Market') || ss.insertSheet('Market');
sh.clear();
sh.getRange(1, 1, rows.length, rows[0].length).setValues(rows);
ss.toast(rows.length - 1 + ' sets refreshed', 'BrickVault');
}
-- SQLite: straight in from the shell
sqlite3 lego.db <<'SQL'
.mode csv
.import --skip 1 brickvault-sets.csv sets
.import --skip 1 brickvault-minifigs.csv minifigs
SQL
-- PostgreSQL
psql -c "\copy sets FROM 'brickvault-sets.csv' WITH (FORMAT csv, HEADER true)"
-- DuckDB reads it in place, no import step at all
duckdb -c "
SELECT set_number, name, theme, current_price_usd
FROM read_csv_auto('brickvault-sets.csv')
WHERE current_price_usd IS NOT NULL
AND ',' || badges || ',' LIKE '%,retired,%'
ORDER BY current_price_usd DESC
LIMIT 20;
"
-- One rule for every database: empty cells are UNKNOWN, not zero.
-- Always exclude them rather than coalescing to 0.
SELECT AVG(current_price_usd) FROM sets WHERE current_price_usd IS NOT NULL;
Responses carry X-BrickVault-Generated, X-BrickVault-Rows
and X-BrickVault-Downloads-Remaining. A HEAD request
returns all of them without transferring the file or using up a download.
Recipes
Common tasks, ready to paste. The pandas ones assume
sets and figs from the pandas tab above.
The biggest gains over RRP
Retired sets trading furthest above what they originally cost.
priced = sets[sets.current_price_usd.notna() & (sets.retail_price_usd > 0)
& sets.badges.str.contains("retired", na=False)]
priced = priced.assign(multiple=priced.current_price_usd / priced.retail_price_usd)
print(priced.nlargest(20, "multiple")[
["set_number", "name", "theme", "retail_price_usd", "current_price_usd", "multiple"]])
Value your own collection
Join a list of set numbers you own against the catalogue.
mine = pd.DataFrame({
"set_number": ["10123-1", "75192-1", "10179-1"],
"qty": [1, 2, 1],
"paid": [99.99, 799.99, 499.99],
})
held = mine.merge(sets, on="set_number", how="left")
held["value"] = held.qty * held.current_price_usd
held["gain"] = held.value - held.qty * held.paid
print(held[["set_number", "name", "qty", "paid", "current_price_usd", "value", "gain"]])
print(f"total value ${held.value.sum():,.2f} on ${(held.qty * held.paid).sum():,.2f} spent")
Filter by badge, correctly
badges is a set, not a string. A bare substring match trips over may_be_available.
flags = sets.badges.fillna("").str.split(",")
retired = sets[flags.apply(lambda f: "retired" in f)]
grails = sets[flags.apply(lambda f: "jackpot" in f)]
top100 = sets[flags.apply(lambda f: "diamond" in f)]
exclusive= sets[flags.apply(lambda f: "exclusives" in f)]
print(len(retired), "retired,", len(grails), "trading over 5x RRP")
Which themes hold value
Median multiple over RRP, retired sets only so the comparison is fair.
r = sets[sets.badges.str.contains("retired", na=False)
& sets.current_price_usd.notna() & (sets.retail_price_usd > 0)]
print(r.assign(multiple=r.current_price_usd / r.retail_price_usd,
parent=r.theme.str.split(" > ").str[0])
.groupby("parent")
.agg(sets=("set_number", "count"), median_multiple=("multiple", "median"))
.query("sets >= 20")
.sort_values("median_multiple", ascending=False)
.head(15))
Join sets to minifigures
Explode the comma-separated ids into a real many-to-many.
link = (sets[["set_number", "set_number_base", "name", "minifig_ids"]]
.dropna(subset=["minifig_ids"])
.assign(minifig_id=lambda d: d.minifig_ids.str.split(","))
.explode("minifig_id")
.merge(figs, on="minifig_id", suffixes=("_set", "_fig")))
# Sets whose figures appear in no other set
exclusive = link[link.set_appearance_count == 1]
print(exclusive.groupby(["set_number", "name_set"]).size().nlargest(10))
Refresh only when it changed
HEAD returns the timestamp without transferring the file or using a download.
import requests
AUTH = {"Authorization": "Bearer bv_live_your_key_here"}
h = requests.head("https://brickvault.app/api/v1/sets.csv", headers=AUTH).headers
if h["X-BrickVault-Generated"] != load_stored_stamp():
download_and_import()
save_stored_stamp(h["X-BrickVault-Generated"])
else:
print("already current, nothing to do")
Cost per piece
The honest way to compare value across sets of different sizes.
big = sets[(sets.pieces > 500) & sets.current_price_usd.notna()].copy()
big["cost_per_piece"] = big.current_price_usd / big.pieces
print(big.nsmallest(20, "cost_per_piece")[
["set_number", "name", "pieces", "current_price_usd", "cost_per_piece"]])
Handle a rate limit properly
429 tells you exactly when the window reopens. Wait for it rather than retrying.
import time, requests
def download(url, key):
r = requests.get(url, headers={"Authorization": f"Bearer {key}"}, timeout=300)
if r.status_code == 429:
wait = int(r.headers.get("Retry-After", 3600))
print(f"daily limit reached, resets in {wait // 60} min")
return None
if r.status_code == 402:
raise RuntimeError("this account is not on BrickVault Pro")
r.raise_for_status()
return r.content
Columns
Column names and order are part of the contract. New columns may be appended over time; existing ones will not be renamed or reordered.
brickvault-sets.csv
| Column | Type | Meaning |
|---|---|---|
| set_number | text | Set number including the variant suffix, e.g. 10123-1. |
| set_number_base | text | The same number without the suffix, e.g. 10123. This is the key that joins to appears_in_sets in the minifigure file. |
| name | text | Official set name. |
| theme | text | Theme, as Parent > Child where a parent theme exists, e.g. Star Wars > Ultimate Collector Series. |
| year_released | integer | Year of release. |
| pieces | integer | Piece count. |
| age_min | integer | Recommended minimum age printed on the box, e.g. 18 for 18+. Blank where unknown. From Brickset (brickset.com) and BrickVault's own reading of the box art. |
| age_max | integer | Upper age for ranged ratings such as 7-12 (older sets). Blank for "N+" ratings and where unknown. |
| retail_price_usd | decimal | Original RRP in USD. Blank or 0 for promotional sets that were never sold. |
| current_price_usd | decimal | Latest recorded market value in USD at the time the file was generated. Blank where we have no price. |
| used_price_usd | decimal | Estimated value opened and complete with box, derived from the market value and the theme's condition curve. |
| quick_sale_usd | decimal | Seller guide: the price to move it quickly. Blank for sets still available at retail. |
| long_listing_12m_usd | decimal | Seller guide: the price achievable on a 12+ month listing. Blank for sets still available at retail. |
| badges | text | Comma-separated status flags in one field, e.g. retired,jackpot,exclusives,diamond,vintage. Full list below. |
| minifig_ids | text | Comma-separated minifigure ids contained in the set, joining to minifig_id in the minifigure file. |
| contains_easter_eggs | yes/no | Whether the set contains a documented easter egg. |
| description | text | Plain-text overview of the set. Present for a subset of the catalogue. |
brickvault-minifigs.csv
| Column | Type | Meaning |
|---|---|---|
| minifig_id | text | Minifigure id, e.g. fig-003515. |
| name | text | Minifigure name. |
| appears_in_sets | text | Comma-separated set numbers the figure appears in, matching set_number_base in the sets file. |
| set_appearance_count | integer | How many sets the figure appears in. A value of 1 means it is exclusive to a single set. |
Every row of both files also carries source and
source_url, always BrickVault and
https://brickvault.app.
Badge values
The badges column holds zero or more of these, comma separated. Exactly
one availability value is always present, and the ranking badges are mutually
exclusive.
available: Currently on sale at retail.retired: No longer produced.coming_soon: Announced but not yet released.may_be_available: Flagged as retiring soon and may still be findable at retail.retiring_soon: Expected to leave production shortly.brand_new: Recently added to the catalogue.free_promo: Given away rather than sold, so it has no retail price.jackpot: Market value is more than 5Γ the original RRP.exclusives: Contains at least one minifigure found in no other set.titan: 3,000 pieces or more.diamond: Top 100 highest value.gold: Top 500 highest value.silver: Top 1,000 highest value.bronze: Top 5,000 highest value.vintage: Released 20 or more years ago.surge: Showing unusual recent price growth.easter_eggs: Contains a documented easter egg.Building something with it
Walkthroughs, from a spreadsheet to a full tracker.