Lego API: setgegevens, winkelprijzen en MCP voor ChatGPT

Lego biedt geen openbare API aan voor zijn catalogus of de prijzen in zijn eigen winkel. Wil je Lego-gegevens in een app, een spreadsheet of een AI-assistent, dan werk je met externe bronnen, en elk daarvan beantwoordt een andere vraag. Voor onderdelen en inventarissen is Rebrickable de aangewezen bron, voor setgegevens en verzamelingen Brickset, voor marktprijzen BrickLink en voor actuele winkelaanbiedingen met verzendkosten in negen landen Brickfact. De API en de MCP-server van Brickfact werken zonder sleutel.

Deze handleiding laat zien welke bron bij welke taak past, toont geteste verzoeken aan de openbare JSON-API van Brickfact en legt uit hoe je ChatGPT of een andere assistent koppelt via het Model Context Protocol (MCP). De voorbeelden gaan uit van Nederland en rekenen in euro. Brickfact beheert deze dienst zelf, dus we beschrijven de beperkingen even eerlijk als de functies.

Welke Lego API past bij je project?

Een onderdelenlijst, een adviesprijs, een verkoop op een marktplaats en een winkelaanbieding zijn vier verschillende getallen. Bepaal eerst welk getal je project nodig heeft en kies daarna pas een endpoint.

Dit is geen ranglijst, maar een overzicht van gereedschap per taak. Veel projecten combineren uiteindelijk twee bronnen: één voor onderdelen en catalogus, één voor prijzen bij het kopen. Lees vooraf de voorwaarden van elke aanbieder, want alle drie de diensten hanteren eigen regels.

Rebrickable: onderdelen, inventarissen en de volledige catalogus

De API van Rebrickable dekt officiële sets, onderdelen en minifiguren, plus kleuren, thema's en setinventarissen. Ingelogde gebruikers kunnen ook hun eigen Rebrickable-verzameling lezen en aanpassen. Elk verzoek heeft een API-sleutel nodig, die je in je profielinstellingen aanmaakt en meestuurt in de header Authorization: key … of als parameter key.

De documentatie zegt uitdrukkelijk dat er geen prijzen voor sets of onderdelen zijn. Voor een volledige kopie van de catalogus wil Rebrickable dat je de CSV-downloads gebruikt in plaats van de API pagina voor pagina af te lopen. Een account mag gemiddeld ongeveer één verzoek per seconde sturen; wie sneller gaat, krijgt HTTP 429 terug.

Rebrickable past bij de vraag welke onderdelen in een set zitten, of in welke sets een bepaald onderdeel voorkomt. Wat een set ergens kost, vind je er niet.

Brickset: setgegevens, verzamelingen en adviesprijzen

De Brickset API, versie 3, levert setgegevens, thema's en subthema's, jaartallen, bouwinstructies, reviews en extra afbeeldingen. Met de inloggegevens van een gebruiker leest en wijzigt ze ook diens Brickset-verzameling. Een sleutel is verplicht; je vraagt die aan bij Brickset nadat je bent ingelogd.

Een nieuwe sleutel mag 100 keer per dag getSets aanroepen, genoeg om te testen. Voor gebruik in productie verwacht Brickset dat je een hogere limiet aanvraagt, en de pagina over de webservices verbiedt sites die Brickset nabouwen. In de setgegevens staat de adviesprijs van Lego voor de Verenigde Staten, het Verenigd Koninkrijk, Canada en Duitsland, niet voor Nederland. Het is een adviesprijs, niet wat winkels vandaag vragen.

BrickLink: marktprijzen voor nieuw en gebruikt

De BrickLink API is vooral gemaakt voor verkopers en geeft ook toegang tot de prijsgids van BrickLink. Verzoeken worden ondertekend in de stijl van OAuth 1.0, met een consumer key en secret, en de toegangstokens gelden alleen voor vaste IP-adressen die je registreert. Vanaf andere adressen werkt de toegang niet, wat de meeste oplossingen in de browser of in serverless-omgevingen uitsluit.

De prijsgids onderscheidt verkopen van de afgelopen zes maanden (guide_type=sold) en huidige aanbiedingen (stock), nieuw of gebruikt, regio en valuta, en de prijzen zijn exclusief btw. Wil je weten wat gebruikte exemplaren van een set opbrengen, dan is dit de juiste bron. Waar je de set vandaag nieuw en thuisbezorgd koopt, is een andere vraag.

Brickfact: actuele winkelaanbiedingen in negen landen

De openbare API van Brickfact geeft de aanbiedingen die Brickfact bij winkels volgt: artikelprijs, opgegeven verzendkosten en totaal in de valuta van het gekozen bestemmingsland. Ze dekt zoeken naar sets, specificaties, aanbiedingen, vergelijkingen, de vastgelegde prijsgeschiedenis bij winkels, een beoordeling van een aanbieding en vergelijkbare sets. De JSON-API en de MCP-server gebruiken dezelfde afhandeling, dus je eigen code en een assistent zien dezelfde gegevens.

Voor deze alleen-lezen routes heb je geen Brickfact-account en geen API-sleutel nodig. Dat betekent niet dat het gebruik onbeperkt is of dat de dienst altijd gratis blijft. Het is een gedeelde dienst met een algemene limiet op het aantal verzoeken; bij drukte antwoordt hij met HTTP 429 en een Retry-After-header. Roep hem aan vanaf een server, een script of een notebook: browserverzoeken vanaf andere websites worden geweigerd met invalid_origin.

De markt is in elk verzoek verplicht en bepaalt welke winkels meetellen en in welke valuta je prijzen krijgt. Andere landen, België bijvoorbeeld, worden geweigerd en niet stilletjes vervangen door een buurland. De optionele parameter language verandert alleen namen en labels. Een verzoek voor de Nederlandse markt met "language": "en" geeft nog steeds euro's, Nederlandse winkels en een link naar de Nederlandse vergelijkingspagina.

Je eerste verzoek: Lego sets tot € 50 inclusief verzending

Dit verzoek zoekt op de Nederlandse markt naar orchideesets met een bekend totaalbedrag inclusief verzending van maximaal € 50:

curl --fail --silent --show-error \
  'https://mcp.brickfact.com/api/v1/search' \
  --header 'Content-Type: application/json' \
  --data '{"market":"NL","query":"orchidee","price_basis":"delivered","max_price":50,"limit":3}'

Ingekort antwoord uit een test op 30 oktober 2026. Prijzen veranderen, dus jouw waarden wijken af:

{
  "market": "NL",
  "currency": "EUR",
  "price_basis": "delivered",
  "sets": [
    {
      "set_id": 10311,
      "name": "Orchidee",
      "theme": "Icons",
      "pieces": 608,
      "comparison_url": "https://brickfact.com/nl-nl/sets/lego-icons-orchidee-10311",
      "item_price": null,
      "total_price": 36.99,
      "rrp": 49.99
    }
  ],
  "page": 1,
  "total": 3
}

Let op bij namen: in onze tests vond de tekstzoekfunctie Engelse en Duitse setnamen, maar niet altijd Nederlandse. "orchidee" werkt omdat de Duitse naam zo luidt, "Miniorchidee" gaf geen resultaat. Het setnummer is de betrouwbaarste zoekterm.

Zoeken kan ook met theme_ids, een bereik voor het aantal onderdelen, leeftijdslabels zoals "18+", filters voor sets die binnenkort of al uit het assortiment zijn, sorteren op prijs, korting of nieuwste en pagina's van maximaal 20 resultaten. Thema-ID's haal je op met GET /api/v1/themes?market=NL&query=Star. Onbekende velden geven HTTP 400 in plaats van genegeerd te worden, zodat een typfout je zoekopdracht niet ongemerkt breder maakt.

Dezelfde zoekopdracht in Python, met een budget van € 40, heeft alleen de standaardbibliotheek nodig:

import json
import urllib.request

payload = {
    "market": "NL",
    "query": "orchidee",
    "price_basis": "delivered",
    "max_price": 40,
    "limit": 5,
}
request = urllib.request.Request(
    "https://mcp.brickfact.com/api/v1/search",
    data=json.dumps(payload).encode(),
    headers={"Content-Type": "application/json"},
)
with urllib.request.urlopen(request, timeout=30) as response:
    result = json.load(response)

for item in result["sets"]:
    print(item["set_id"], item["name"], item["total_price"], result["currency"])

Aanbiedingen voor één set, met verzendkosten

De aanbiedingen voor één set vraag je op via de offers-route met het setnummer:

curl --fail --silent --show-error \
  'https://mcp.brickfact.com/api/v1/sets/10311/offers?market=NL&price_basis=delivered'

Elke aanbieding bevat item_price, shipping, total, currency, feed_updated_at en stock_status. Aanbiedingen met een bekend totaalbedrag staan vooraan, en het antwoord geeft daarnaast lowest_known_total en lowest_item_price. Kent Brickfact de verzendkosten van een winkel niet, dan zijn shipping en total null. Lees dat als onbekend, nooit als gratis.

stock_status staat altijd op not_verified. Een prijs in een feed bewijst niet dat de set op voorraad is, en de opgegeven verzendkosten gelden voor één set. Drempels voor gratis verzending, kortingscodes en regels bij het afrekenen kunnen het eindbedrag veranderen; alleen de kassa van de winkel is bindend.

De setdetails (GET /api/v1/sets/10311?market=NL) voegen de adviesprijs, leeftijd, het aantal minifiguren, de afmetingen en een geschatte einddatum (uit productie) toe. Twee tot vier sets vergelijk je met POST /api/v1/compare en een lijst in set_ids.

Artikelprijs of prijs inclusief verzending?

Standaard staat price_basis op "item". Dan rekenen budget en sortering met de kale setprijs, is item_price gevuld en blijft total_price null. Een set van € 45 met € 6,99 verzendkosten past zo binnen een budget van € 50, terwijl hij je thuisbezorgd meer kost.

Met "delivered" gebruikt Brickfact het totaal inclusief opgegeven verzending naar de gekozen markt. Aanbiedingen met onbekende verzendkosten vallen vóór het prijsfilter, de telling en de paginering af. total en elke pagina bevatten dus alleen sets met een bekend totaalbedrag, zonder gaten tussen de pagina's. De keerzijde: een winkel die geen verzendkosten opgeeft, verdwijnt helemaal uit deze resultaten.

Voor het kopen is de prijs inclusief verzending meestal de eerlijkste keuze. Een lage artikelprijs bij een buitenlandse webshop is vaak geen koopje meer zodra de verzending naar Nederland erbij komt, en verzamelaars vergelijken daarom meestal inclusief verzending. Gebruik de artikelmodus voor catalogusweergaven waarin verzending niet uitmaakt.

Twee soorten prijsgeschiedenis

Brickfact houdt twee prijsreeksen bij, en wie ze verwart, krijgt verkeerde antwoorden.

De prijsgeschiedenis bij winkels (POST /api/v1/retail-history, MCP-tool get_retail_price_history) legt per dag de laagste bekende prijs inclusief verzending vast bij de gevolgde winkels van één markt, in de valuta van die markt. Amazon telt niet mee, en dagen met onbekende of geschatte verzendkosten ook niet. Eerdere dagen worden berekend met de huidige verzendregels voor het land. Het antwoord vermeldt observation_days en first_observed_day. Deze reeks begon pas op 12 oktober 2026: een lange gevraagde periode betekent dus geen lange reeks. Controleer de dekking voordat je conclusies trekt.

De marktwaarde-geschiedenis (GET /api/v1/sets/75192/history?market=NL&range=1Y, MCP-tool get_price_history) is een aparte reeks waarderingen van verzegelde sets in euro. Ze laat zien wat een verzegelde set in de loop van de tijd waard is, het soort waarde dat ons onderzoek naar de ontwikkeling van Lego-prijzen analyseert. Het is geen overzicht van winkelprijzen.

De dealbeoordeling (POST /api/v1/assess-deal, MCP-tool assess_deal) vergelijkt de goedkoopste actuele aanbieding inclusief verzending, uit een feed van hoogstens 48 uur oud, met de laagste vastgelegde winkelprijs. Ze antwoordt met at_or_below_recorded_low of above_recorded_low en het verschil in procenten. Zonder minstens twee vastgelegde dagen of met een geschiedenis ouder dan 48 uur is het antwoord insufficient_history, zonder bruikbare aanbieding no_delivered_offer. De huidige aanbieding kan van Amazon komen, ook al sluit de geschiedenis Amazon uit. Een uitkomst op het vastgelegde laagste punt is geen laagste prijs ooit en zegt niets over de prijs van volgende maand.

ChatGPT of een andere assistent koppelen via MCP

Het Model Context Protocol is een open standaard om AI-toepassingen aan externe systemen te koppelen. In plaats van zelf verzoeken te schrijven, laat je de assistent de tools van Brickfact vinden en aanroepen zodra je vraag actuele gegevens nodig heeft.

Voor ChatGPT beschrijft de koppelingshandleiding van OpenAI de huidige route: open ChatGPT Plugins, klik op de plusknop en daarna op Add custom MCP server, geef een naam en beschrijving op, vul de URL inclusief /mcp in, kies geen authenticatie, bevestig de risicowaarschuwing en kies Create as a plugin. Het beleid van je account en werkruimte geldt; in een bedrijfswerkruimte bepaalt de beheerder of eigen MCP-servers zijn toegestaan. Een vermelding in de openbare plugin-directory van ChatGPT vereist een aparte beoordeling door OpenAI; zoek daar dus eerst naar Brickfact voordat je ervan uitgaat dat je het vindt.

Andere clients die externe servers via Streamable HTTP ondersteunen, maken verbinding met dezelfde URL. Puur lokale clients die alleen stdio spreken, hebben een brug nodig.

De elf tools:

Prompts die helpen bij het kopen

De server vraagt de assistent het winkelland uit het gesprek over te nemen en ernaar te vragen als het ontbreekt. Noem het dus meteen. Deze prompts dekken de belangrijkste tools:

• "Zoek Lego Star Wars sets onder € 100 inclusief verzending naar Nederland en toon ze als kaarten."
• "Help me een Lego-cadeau te kiezen tot € 60 inclusief verzending in Nederland, voor een kind van 10 dat van auto's houdt."
• "Vergelijk Lego 10311 en 10313 met levering in Nederland, met aantal onderdelen en totaalprijs."
• "Is de huidige prijs van Lego 75192 in Nederland goed vergeleken met de vastgelegde winkelprijzen? Vertel me over hoeveel dagen je gegevens hebt."
• "Zoek goedkopere alternatieven voor Lego 75192 met levering in Nederland."

Hosts met ondersteuning voor MCP Apps tonen setkaarten met afbeeldingen, een vergelijking naast elkaar en grafieken van de prijsgeschiedenis bij winkels. Elders antwoordt de assistent met dezelfde gegevens in tekst. Als de host apps een status laat bewaren, onthoudt de kaart een shortlist van maximaal zes setnummers. Die lijst hoort bij de kaart in het gesprek, niet bij een Brickfact-account, en is in een nieuw gesprek mogelijk weg.

Wat de assistent niet kan

De MCP-server leest alleen openbare catalogusgegevens. Hij kan niets kopen, vraagt geen betaalgegevens, ziet je Brickfact-verzameling niet en verandert niets aan je account. Vraag je hem om een melding als Lego 10311 onder € 30 zakt, dan krijg je een overdracht naar de app met "created": false: een link naar de Brickfact-app en de stappen om het alarm daar in te stellen. Er is pas iets aangemaakt als je het in de app bevestigt. Hoe prijsalarmen werken, lees je in onze handleiding om Lego prijswaarschuwingen aan te maken.

Prijzen in een antwoord zijn nooit actueler dan de feed erachter. Een goede aanbieding kan minuten na een prijsdaling uitverkocht zijn; open dus de meegeleverde vergelijkingslink en controleer de winkel voordat je koopt.

Zo blijft je integratie kloppen

Met een paar vaste gewoontes blijft je integratie correct als de gegevens veranderen:

• Begin met één set en één markt en controleer in elk antwoord de valuta en price_basis voordat je meer landen toevoegt.
• Toon null bij verzending als onbekend en vervang het niet door nul.
• Zet feed_updated_at of het tijdstip van je verzoek naast prijzen.
• Behandel lege resultaten en korte reeksen als normale antwoorden, niet als fouten.
• Cache antwoorden een paar minuten, respecteer Retry-After en loop niet de hele catalogus door via zoekpagina's.
• Link naar de meegeleverde comparison_url in plaats van zelf URL's van setpagina's samen te stellen.

De invoerschema's van alle routes staan op het openbare schema-endpoint. Vergelijk je prijzen liever zelf, dan vind je dezelfde aanbiedingen met filters in de Lego databank, en zo vergelijken wij prijzen legt uit welke winkels we volgen.

Een API om Lego-hubs en motoren te programmeren is een roboticavraag, geen datavraag: onze handleiding Lego robot programmeren behandelt SPIKE, Mindstorms en Python met Pybricks. Brickfact is onafhankelijk van de Lego Groep.