BrickVault for developers

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.

28,000+rows
19columns
dailyupdated
GET /api/v1/sets.csv

Minifigures

Every minifigure, and the sets each one appears in.

17,000+rows
6columns
dailyupdated
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.

Get an API key

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.

Python
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"])
pandas
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())
cURL
# 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
JavaScript
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
<?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);
R
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)
Google Sheets
// 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');
}
SQL
-- 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.

python
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.

python
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.

python
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.

python
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.

python
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.

python
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.

python
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.

python
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

ColumnTypeMeaning
set_numbertextSet number including the variant suffix, e.g. 10123-1.
set_number_basetextThe same number without the suffix, e.g. 10123. This is the key that joins to appears_in_sets in the minifigure file.
nametextOfficial set name.
themetextTheme, as Parent > Child where a parent theme exists, e.g. Star Wars > Ultimate Collector Series.
year_releasedintegerYear of release.
piecesintegerPiece count.
age_minintegerRecommended 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_maxintegerUpper age for ranged ratings such as 7-12 (older sets). Blank for "N+" ratings and where unknown.
retail_price_usddecimalOriginal RRP in USD. Blank or 0 for promotional sets that were never sold.
current_price_usddecimalLatest recorded market value in USD at the time the file was generated. Blank where we have no price.
used_price_usddecimalEstimated value opened and complete with box, derived from the market value and the theme's condition curve.
quick_sale_usddecimalSeller guide: the price to move it quickly. Blank for sets still available at retail.
long_listing_12m_usddecimalSeller guide: the price achievable on a 12+ month listing. Blank for sets still available at retail.
badgestextComma-separated status flags in one field, e.g. retired,jackpot,exclusives,diamond,vintage. Full list below.
minifig_idstextComma-separated minifigure ids contained in the set, joining to minifig_id in the minifigure file.
contains_easter_eggsyes/noWhether the set contains a documented easter egg.
descriptiontextPlain-text overview of the set. Present for a subset of the catalogue.

brickvault-minifigs.csv

ColumnTypeMeaning
minifig_idtextMinifigure id, e.g. fig-003515.
nametextMinifigure name.
appears_in_setstextComma-separated set numbers the figure appears in, matching set_number_base in the sets file.
set_appearance_countintegerHow 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.