Want to build a Facebook application for Brickset? Or an Android phone app? Brickset Web Services provide you with the means to do so. This page documents the service operations available.
Accessing the web services
Anybody can test the web service using the URL in the menu on the one below. However to make use of it in an application you will need an API key. Without one the search operation will return a maximum of 20 records.
The URL of the web service is http://brickset.com/webservices/brickset.asmx.
The login service method provides a means of authenticating a user by passing a user name and password. If these match a valid user, a userHash string is returned which can be passed to other operations that require it. If they are invalid, an empty string will be returned.
Your application will typically ask the user to log in once, then store this hash value locally to avoid the need to keep logging in. The userHash will remain the same for a given user until the user changes their password.
If your application does not require information relating to the user, you do not need to log in and instead can supply an empty userHash to operations that use it.
The search service method returns records from the Brickset set database. You can pass as many or as few input parameters as you like (query, theme, subtheme, setNumber, year) in order to get the recordset you require.
If you provide a valid userHash the recordset will contain flags indicating whether the user owns and/or wants the set. Furthermore, you can also pass a '1' in the owned or wanted input parameter to get a list of sets the user owns or wants. These work in conjunction with other parameters allowing you to filter a user's owned list by, for example, theme.
This method requires an API key to work fully. Please contact us using the link in the menu to obtain one. To test this method without one, leave it blank. A maximum of 20 records will be returned.
A Search by SetID service method provides a means to get details of one record matching the database's internal unique SetID.
Listing themes, subthemes and years
- listThemes will return as list of themes and the number of sets in each.
- listSubthemes will return a list of subthemes for a given theme and the number of sets in each.
- listYears will return a list of years a given theme was available in and the number of sets released that year.
- popularSearches will return the list of most searched for terms, as shown on the home page, together with their relative weightings.
Setting owned and wanted information
- updateOwn takes a setID (from the recordset returned by the search operation), a userHash, and a 1 or 0 to specify whether the user owns the set or not. If successful a 1 is returned.
- updateWant takes a setID (from the recordset returned by the search operation), a userHash, and a 1 or 0 to specify whether the user wants the set or not. If successful a 1 is returned.
- updateQtyOwned takes a setID (from the recordset returned by the search operation), a userHash, and a integer value to specify how many of the set the user owns. If successful a 1 is returned.
- updateUserNotes takes a setID (from the recordset returned by the search operation), a userHash, and a string, which will replace the user's notes for the set. If successful a 1 is returned.
- listInstructions takes a setID (from the recordset returned by the search operation), and returns the URLs of instructions available at LEGO customer services.
Finding out what's new
- updatedSince lists all set records changed since the date you specify (in mm/dd/yy format). This is useful if you are planning on caching the database for offline use. The data set returned will contain user ownership fields, but they will not be populated (since userHash is not passed as a parameter)
Managing a user's minifig collection
- searchMinifigCollection will retrieve a list of all minifigs owned or wanted by a user that optionally match a query. Leave owned and wanted blank to retrieve those owned and wanted, or set one of them to '1' to get just owned or just wanted. query can be a complete minifig number (e.g. 'hp001'), or just a prefix (e.g. 'hp'). Leave blank to retrieve all.
- updateMinifigQtyOwned can be used to set the quantity of loose minifigs a user has. If successful a 1 is returned.
- updateMinifigWanted can be used to set whether the user wants a minifig. Currently users can't simultaneously own and want the same minifig, so setting a fig as wanted will clear the quantity owned. If successful a 1 is returned.
Questions or suggestions?
If you have any questions about using the web service, or suggestions for its improvement, get in touch.
Here's a list of changes we've made to the web services since they were launched.
22nd October 2012
- a new search method, searchBySetID as been provided to accept a SetID and search on the internal database key and return exactly one record.
- Multiple terms can now be specified in the setNumber field, separated by a comma e.g SetNumber=6876-1,8880-1,9492-1.
1st October 2012
- Range searches are now supported, e.g. query=6000-6999 to retrieve 6xxx sets.
- Multiple terms can now be specified in the theme, subtheme and year fields, separated by a comma, e.g Theme=Aquazone,Aqua Raiders to retrieve all sets from both themes.
11th June 2012
- Searching by EAN and UPC numbers now works correctly.
- EAN and UPC numbers added to SetData.
20th April 2012
- listInstructions and updateUserNotes methods added.
- New fields added to SetData: image, imageFilename, userNotes, minifigs, instructionsAvailable, USRetailPrice, UKRetailPrice and CARetailPrice.
- Maximum number of records returned by methods increased to 1000. When retrieving a user's collection, the maximum is 6000.
12th October 2011
- Methods for managing a user's minifig collection added.
1st September 2010
- Search method returns an additional field lastUpdated to show when the database record was last updated.
- New method updatedSince provided to get list of sets updated since a date you specify.