API Lego : données de sets, prix des marchands et MCP pour ChatGPT

Lego ne propose pas d’API publique pour son catalogue ni pour les prix de sa boutique. Pour intégrer des données Lego à une application, un tableur ou un assistant d’IA, il faut passer par des services tiers, et chacun répond à une question différente. Rebrickable est la référence pour les pièces et les inventaires, Brickset pour les fiches de sets et les collections, BrickLink pour les prix de sa place de marché, neuf ou d’occasion et Brickfact pour les offres actuelles des marchands, frais de port compris, dans neuf pays. L’API et le serveur MCP de Brickfact ne demandent aucune clé.

Ce guide indique quelle source convient à quel usage, montre des requêtes testées sur l’API JSON publique de Brickfact et explique comment connecter ChatGPT ou un autre assistant via le Model Context Protocol (MCP). Les exemples portent sur la France et sont exprimés en euros. Brickfact exploite ce service lui-même : nous en décrivons les limites aussi franchement que les fonctions.

Quelle API Lego pour quel projet ?

Un inventaire de pièces, un prix de vente conseillé, une vente sur une place de marché et une offre de marchand sont quatre chiffres différents. Déterminez d’abord celui dont votre projet a besoin, puis choisissez le point d’accès.

Il ne s’agit pas d’un classement, mais d’outils pour des tâches distinctes. Beaucoup de projets finissent par en combiner deux : une source de catalogue pour les pièces et une source de prix pour l’achat. Lisez les conditions de chaque service avant de vous lancer, car les trois services fixent leurs propres règles.

Rebrickable : pièces, inventaires et catalogue complet

L’API de Rebrickable couvre les sets officiels, les pièces et les minifigurines, ainsi que les couleurs, les thèmes et les inventaires de sets. Les utilisateurs connectés peuvent aussi lire et modifier leur propre collection Rebrickable. Chaque appel exige une clé d’API, générée dans les paramètres du profil et transmise dans l’en-tête Authorization: key … ou dans un paramètre key.

La documentation précise qu’aucun prix de set ou de pièce n’est disponible. Pour récupérer le catalogue entier, Rebrickable renvoie vers ses fichiers CSV téléchargeables plutôt que vers une lecture page par page de l’API. Un compte peut envoyer environ une requête par seconde en moyenne ; au-delà, l’API répond par une erreur HTTP 429.

Rebrickable est le bon choix pour savoir quelles pièces contient un set, ou dans quels sets se trouve une pièce donnée. Il ne vous dira pas combien coûte un set.

Brickset : fiches de sets, collections et prix conseillés

L’API Brickset, version 3, renvoie des fiches de sets, des thèmes et sous-thèmes, des années de sortie, des notices, des avis et des images supplémentaires. Avec la connexion d’un utilisateur, elle lit et met à jour sa collection Brickset. La clé est obligatoire ; on la demande sur Brickset après s’être connecté.

Une nouvelle clé autorise 100 appels à getSets par jour, de quoi faire des essais. Pour un projet en production, Brickset invite à demander une limite plus élevée, et sa page consacrée aux services web interdit les sites qui copieraient Brickset. Les fiches contiennent le prix conseillé par Lego pour les États-Unis, le Royaume-Uni, le Canada et l’Allemagne, mais pas pour la France. C’est un prix de vente conseillé, pas le prix pratiqué aujourd’hui par les marchands.

BrickLink : prix du marché, neuf ou d’occasion

L’API BrickLink s’adresse surtout aux vendeurs, et elle donne aussi accès au guide des prix de BrickLink. Les requêtes sont signées sur le modèle d’OAuth 1.0, avec une clé et un secret de consommateur, et les jetons d’accès ne valent que pour des adresses IP fixes déclarées. Depuis une autre adresse, l’accès échoue, ce qui exclut la plupart des montages dans le navigateur ou en serverless.

Le guide des prix distingue les ventes des six derniers mois (guide_type=sold) des annonces en cours (stock), ainsi que l’état neuf ou d’occasion, la région et la devise, et ses prix s’entendent hors TVA. C’est la bonne source pour savoir à combien se vendent les exemplaires d’occasion. Savoir où acheter le set neuf aujourd’hui, livré chez vous, est une autre question.

Brickfact : les offres actuelles des marchands dans neuf pays

L’API publique de Brickfact renvoie les offres que Brickfact suit chez les marchands : prix de l’article, frais de port déclarés et total dans la devise du pays de livraison choisi. Elle couvre la recherche de sets, les caractéristiques, les offres, les comparaisons, l’historique des prix relevés chez les marchands, l’évaluation d’une offre et les sets similaires. L’API JSON et le serveur MCP utilisent les mêmes traitements : votre code et un assistant voient donc les mêmes données.

Ces routes en lecture seule ne demandent ni compte Brickfact ni clé d’API. Cela ne signifie pas un usage illimité ni la promesse d’un service gratuit pour toujours. Le service est partagé et soumis à une limite globale de requêtes ; en cas de forte charge, il répond par HTTP 429 avec un en-tête Retry-After. Appelez-le depuis un serveur, un script ou un notebook : les requêtes de navigateur venant d’autres sites sont refusées avec invalid_origin.

Le marché est obligatoire dans chaque requête : il détermine les marchands pris en compte et la devise des prix. Les autres pays, la Belgique par exemple, sont refusés au lieu d’être remplacés par un voisin. Le paramètre facultatif language ne change que les noms et les libellés. Une requête sur le marché français avec "language": "en" renvoie toujours des euros, des marchands français et un lien vers la page de comparaison française.

Première requête : des sets Lego à moins de 50 € livrés

Cette requête cherche sur le marché français des sets d’orchidée dont le total connu, port compris, ne dépasse pas 50 € :

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

Réponse raccourcie d’un test du 30 octobre 2026. Les prix évoluent, vos valeurs seront différentes :

{
  "market": "FR",
  "currency": "EUR",
  "price_basis": "delivered",
  "sets": [
    {
      "set_id": 10311,
      "name": "L’orchidée",
      "theme": "Icons",
      "pieces": 608,
      "comparison_url": "https://brickfact.com/fr-fr/sets/lego-icons-lorchidée-10311",
      "item_price": null,
      "total_price": 36.99,
      "rrp": 49.99
    }
  ],
  "page": 1,
  "total": 3
}

Pourquoi « orchid » et pas « orchidée » ? Lors de nos tests, la recherche textuelle trouvait les noms anglais et allemands, mais pas toujours les noms français : « orchidée » ne donnait aucun résultat. Le numéro de set reste la recherche la plus fiable, les noms français s’affichent ensuite dans la réponse.

La recherche accepte aussi theme_ids, des fourchettes de nombre de pièces, des âges comme "18+", des filtres sur les sets bientôt retirés ou retirés, un tri par prix, remise ou nouveauté, et des pages de 20 résultats au plus. Les identifiants de thème s’obtiennent avec GET /api/v1/themes?market=FR&query=Star. Un champ inconnu provoque une erreur HTTP 400 au lieu d’être ignoré : une faute de frappe n’élargit donc pas votre recherche en silence.

La même recherche en Python, avec un budget de 40 €, n’a besoin que de la bibliothèque standard :

import json
import urllib.request

payload = {
    "market": "FR",
    "query": "orchid",
    "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"])

Les offres d’un set, frais de port compris

Pour les offres d’un seul set, utilisez la route des offres avec le numéro du set :

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

Chaque offre contient item_price, shipping, total, currency, feed_updated_at et stock_status. Les offres dont le total livré est connu passent en tête, et la réponse ajoute lowest_known_total et lowest_item_price. Quand Brickfact ne connaît pas les frais de port d’une boutique, shipping et total valent null. Lisez-le comme « inconnu », jamais comme « gratuit ».

stock_status vaut toujours not_verified. Un prix dans un flux ne prouve pas que le set est en stock, et les frais de port indiqués valent pour un seul set. Seuils de livraison gratuite, codes promo et règles du panier peuvent modifier le montant final ; seul le récapitulatif de commande du marchand fait foi.

Le détail d’un set (GET /api/v1/sets/10311?market=FR) ajoute le prix conseillé, l’âge indiqué, le nombre de minifigurines, les dimensions et une date de retrait estimée. Pour comparer deux à quatre sets, envoyez POST /api/v1/compare avec une liste set_ids.

Prix de l’article ou prix livré ?

Par défaut, price_basis vaut "item". Dans ce mode, le budget et le tri portent sur le seul prix du set, item_price est renseigné et total_price reste à null. Un set à 45 € avec 6,99 € de port entre ainsi dans un budget de 50 €, alors qu’il vous coûtera plus de 50 € une fois livré.

Avec "delivered", Brickfact utilise le total frais de port compris vers le marché choisi. Les offres dont le port est inconnu sont écartées avant le filtre de prix, le comptage et la pagination : total et chaque page ne comptent donc que des sets au total livré connu, sans trou entre les pages. La contrepartie : une boutique qui n’indique pas ses frais de port disparaît totalement de ces résultats.

Pour acheter, le prix livré est généralement le plus honnête. Un prix d’article bas dans une boutique étrangère cesse souvent d’être une affaire une fois ajoutés les frais d’envoi vers la France, et les collectionneurs raisonnent d’ailleurs le plus souvent port compris. Gardez le mode article pour les vues de catalogue où la livraison ne compte pas.

Deux sortes d’historique de prix

Brickfact tient deux historiques distincts, et les confondre mène à de mauvaises réponses.

L’historique des prix marchands (POST /api/v1/retail-history, outil MCP get_retail_price_history) enregistre chaque jour le prix livré le plus bas connu chez les marchands suivis d’un marché, dans sa devise. Amazon en est exclu, tout comme les jours où le port est inconnu ou estimé. Les jours passés sont calculés avec les règles de livraison actuelles pour le pays. La réponse indique observation_days et first_observed_day. Cette série n’a commencé que le 12 octobre 2026 : demander une longue période ne garantit pas un long historique. Vérifiez la couverture avant de conclure.

L’historique de valeur sur le marché (GET /api/v1/sets/75192/history?market=FR&range=1Y, outil MCP get_price_history) est une autre série : l’estimation des sets neufs scellés, en euros. Elle indique ce que vaut un set scellé au fil du temps, le type de valeur qu’analyse notre étude sur l’évolution des prix Lego. Ce n’est pas un historique des prix pratiqués par les boutiques.

L’évaluation d’offre (POST /api/v1/assess-deal, outil MCP assess_deal) compare l’offre livrée actuelle la moins chère, issue d’un flux de moins de 48 heures, au plus bas relevé chez les marchands. Elle répond at_or_below_recorded_low ou above_recorded_low, avec l’écart en pourcentage. Sans au moins deux jours relevés ni historique de moins de 48 heures, la réponse est insufficient_history, et sans offre exploitable no_delivered_offer. L’offre actuelle peut venir d’Amazon, même si l’historique l’exclut. Un résultat au plus bas relevé n’est pas un plus bas historique absolu et ne dit rien du prix du mois prochain.

Connecter ChatGPT ou un autre assistant via MCP

Le Model Context Protocol est un standard ouvert qui relie des applications d’IA à des systèmes externes. Au lieu d’écrire vous-même les requêtes, vous laissez l’assistant découvrir les outils de Brickfact et les appeler quand votre question demande des données à jour.

Pour ChatGPT, le guide de connexion d’OpenAI décrit la marche à suivre actuelle : ouvrez ChatGPT Plugins, cliquez sur le bouton + puis sur Add custom MCP server, donnez un nom et une description, saisissez l’URL avec /mcp, sélectionnez « aucune authentification », validez l’avertissement de risque et choisissez Create as a plugin. Les règles de votre compte et de votre espace de travail s’appliquent : en entreprise, l’administrateur décide si les serveurs MCP personnalisés sont autorisés. Figurer dans l’annuaire public des plugins de ChatGPT suppose un examen séparé par OpenAI : cherchez Brickfact dans l’annuaire avant de partir du principe qu’il s’y trouve.

Les autres clients compatibles avec les serveurs distants en Streamable HTTP se connectent avec la même URL. Les clients purement locaux qui ne parlent que stdio ont besoin d’une passerelle.

Les onze outils :

Que demander à l’assistant pour vos achats

Le serveur demande à l’assistant de reprendre le pays d’achat de la conversation et de le demander s’il manque : indiquez-le d’emblée. Ces demandes couvrent les principaux outils :

• « Trouve des sets Lego Star Wars à moins de 100 € livrés en France et affiche-les sous forme de fiches. »
• « Aide-moi à choisir un cadeau Lego à moins de 60 € livré en France pour un enfant de 10 ans qui aime les voitures. »
• « Compare les sets Lego 10311 et 10313 livrés en France, avec le nombre de pièces et le prix livré. »
• « Le prix actuel du set Lego 75192 en France est-il bon par rapport aux prix relevés chez les marchands ? Dis-moi sur combien de jours tu t’appuies. »
• « Trouve des alternatives moins chères au set Lego 75192 livrées en France. »

Les hôtes compatibles avec MCP Apps affichent des fiches de sets avec images, une vue comparative et des graphiques de l’historique des prix marchands. Ailleurs, l’assistant répond en texte avec les mêmes données. Si l’hôte permet aux apps de conserver un état, la fiche peut garder une sélection de six numéros de sets au plus. Cette sélection appartient à la fiche dans la conversation, pas à un compte Brickfact, et peut ne pas suivre dans une nouvelle conversation.

Ce que l’assistant ne peut pas faire

Le serveur MCP ne lit que des données publiques du catalogue. Il ne peut rien acheter, ne demande aucune donnée de paiement, ne voit pas votre collection Brickfact et ne modifie pas votre compte. Demandez-lui de vous prévenir quand le set Lego 10311 passe sous 30 €, et vous obtiendrez un relais vers l’app avec "created": false : un lien vers l’app Brickfact et les étapes pour y créer l’alerte. Rien n’est créé tant que vous ne l’avez pas confirmé dans l’app. Pour les alertes elles-mêmes, consultez notre guide pour créer des alertes de prix Lego.

Les prix d’une réponse ne sont jamais plus récents que le flux qui les fournit. Une bonne affaire peut être épuisée quelques minutes après une baisse : ouvrez le lien de comparaison renvoyé et vérifiez la boutique avant d’acheter.

Bonnes pratiques pour une intégration fiable

Quelques habitudes permettent de garder une intégration fiable quand les données changent :

• Commencez par un set et un marché, et vérifiez la devise et price_basis dans chaque réponse avant d’ajouter d’autres pays.
• Affichez un port à null comme inconnu, sans le remplacer par zéro.
• Indiquez feed_updated_at ou l’heure de votre requête à côté des prix.
• Traitez les résultats vides et les historiques courts comme des réponses normales, pas comme des erreurs.
• Mettez les réponses en cache quelques minutes, respectez Retry-After et ne parcourez pas tout le catalogue page par page.
• Utilisez le lien comparison_url renvoyé plutôt que de construire vous-même les adresses des pages de sets.

Les schémas d’entrée de toutes les routes sont publiés sur le point d’accès des schémas. Pour comparer les prix à la main, l’explorateur de sets Lego présente les mêmes offres avec des filtres, et la page comment nous comparons les prix détaille les marchands suivis.

Une API pour programmer des hubs et des moteurs Lego relève de la robotique, pas des données : notre guide pour programmer un robot Lego traite de SPIKE, de Mindstorms et de Python avec Pybricks. Brickfact est indépendant du groupe Lego.