Brickset web services API v2 documentation

The API provides a robust means of interfacing with Brickset.

Notes

  • The API is implemented as an XML SOAP web service. Please read the the WSDL. There are no plans at present to make it available via JSON.

  • An API Key is required for all methods. You can get one here. They are currently free and unrestricted but that may change in future.
  • We are unable to provide an API for minifigs (data and images belong to BrickLink) or parts (data and images belong to LEGO). Parts information can be obtained using Rebrickable.com's API.

Methods

General methods

Method Parameters Output

checkKey

Check if an API key is valid.

apiKey
API key
Data type
String
Valid key
OK
Invalid API key
INVALIDKEY

login

Log in as a user and retrieve a token that can be used in subsequent API calls.

apiKey
API key
username
A Brickset username
password
A Brickset password
Data type
String
Valid credentials
userHash token
Invalid credentials
ERROR: {details}
Invalid API key
INVALIDKEY

checkUserHash

Check if a userHash key is valid.

userHash
User hash retreived by the login method
Data type
String
Valid userHash
Name of user
Invalid userHash
INVALID

Sets

Method Parameters Output

getSets

Retrieve a list of sets. All parameters except apiKey are optional but must be passed as blanks if not used.

apiKey
API key
userHash
User hash retreived by the login method. Use to get collection information, in conjunction with owned/wanted.
query
Search term, searches set number, name, theme, subtheme.
theme
Theme
subtheme
Subtheme
setNumber
Set number, in the format {number}-{variant}, e.g. 6876-1
year
Integer, year
owned
Set to 1 to retrieve a user's owned sets, otherwise leave blank
wanted
Set to 1 to retrieve a user's wanted sets, otherwise leave blank
orderBy
Specify sort order. Valid values are Number, YearFrom, Pieces, Minifigs, Rating, UKRetailPrice, USRetailPrice, CARetailPrice, EURetailPrice, Theme, Subtheme, Name, Random. Add 'DESC' to the end to sort descending, e.g. NameDESC. (default: number, values are case-insensitive).
pageSize
Integer, specify how many records to retrieve (default: 20)
pageNumber
Integer, specify which page of records to retrieve, use in conjunction with pageSize (default: 1)
userName
Use this to retrieve a user's collection (in conjunction with owned/wanted) without logging in as the user. This will only return records if the user has made his/her collection public.
Success
Array of sets
No matches
Nothing
Invalid API key
Nothing

getSet

Retrive full information about one set.

apiKey
API key
userHash
User hash retreived by the login method. If present, output will contain owned/wanted information.
setID
Set ID, obtained from sets() retrieved by getSet. This is NOT the set number, it's the internal unique database ID that remains constant, whereas set numbers may not.
Success
Array of sets, with one entry
No matches
Nothing
Invalid API key
Nothing

getRecentlyUpdatedSets

Get a list of sets that have changed in the last {minutesAgo} minutes.

apiKey
API key
minutesAgo
Integer
Success
Array of sets
No matches
Nothing
Invalid API key
Nothing

getAdditionalImages

Get a list of URLs of additional set images for the specified set.

apiKey
API key
setID
Set ID
Success
Array of additionalImages
No images
Nothing
Invalid set ID
Nothing
Invalid API key
Nothing

getReviews

Get the reviews for the specified set.

apiKey
API key
setID
Set ID
Success
Array of reviews
No reviews
Nothing
Invalid set ID
Nothing
Invalid API key
Nothing

getInstructions

Get a list of instructions for the specified set.

apiKey
API key
setID
Set ID
Success
Array of instructions
No instructions
Nothing
Invalid set ID
Nothing
Invalid API key
Nothing

getThemes

Get a list of themes, with the total number of sets in each.

apiKey
API key
Success
Array of themes
Invalid API key
Nothing

getSubthemes

Get a list of subthemes for a given theme, with the total number of sets in each.

apiKey
API key
Theme
Theme
Success
Array of subthemes
No subthemes
Nothing
Invalid theme
Nothing
Invalid API key
Nothing

getYears

Get a list of years for a given theme, with the total number of sets in each.

apiKey
API key
Theme
Theme
Success
Array of years
No years
Nothing
Invalid theme
Nothing
Invalid API key
Nothing

getThemesForUser

Get a list of themes in a user's owned or wanted list, with the total number of sets in each.

apiKey
API key
userHash
User hash retreived by the login method.
owned
Set to 1 to retrieve a list of themes in a users's owned sets list.
wanted
Set to 1 to retrieve a list of themes in a users's wanted sets list. Note that if owned=1 then wanted is ignored.
Success
Array of themes. Note that subthemeCount, yearFrom and yearTo will not be populated.
Invalid API key
Nothing
Invalid userHash
Nothing

getSubthemesForUser

Get a list of subthemes for a given theme in a user's owned or wanted list, with the total number of sets in each.

apiKey
API key
Theme
Theme
userHash
User hash retreived by the login method.
owned
Set to 1 to retrieve a list of subthemes for a specific theme in a users's owned sets list.
wanted
Set to 1 to retrieve a list of subthemes for a specific theme in a users's wanted sets list. Note that if owned=1 then wanted is ignored.
Success
Array of subthemes. Note that yearFrom and yearTo will not be populated.
No subthemes
Nothing
Invalid theme
Nothing
Invalid API key
Nothing
Invalid userHash
Nothing

getYearsForUser

Get a list of years for a given theme in a user's owned or wanted list, with the total number of sets in each.

apiKey
API key
Theme
Theme
userHash
User hash retreived by the login method.
owned
Set to 1 to retrieve a list of years for a specific theme in a users's owned sets list.
wanted
Set to 1 to retrieve a list of years for a specific theme in a users's owned sets list. Note that if owned=1 then wanted is ignored.
Success
Array of years
No years
Nothing
Invalid theme
Nothing
Invalid API key
Nothing
Invalid userHash
Nothing

Set collection management

Method Parameters Output

getCollectionTotals

Get a user's collection totals.

apiKey
API key
userHash
userHash token
Success
collectionTotals class
Invalid API key
Nothing
Invalid userHash
Nothing

setCollection

Set a user's collection details.

apiKey
API key
userHash
userHash token
setID
Set ID
qtyOwned
Integer, 0-999
wanted
0 or 1
Data type
String
Success
OK
Error in parameters
ERROR: {details}
Invalid userHash
ERROR: {details}
Invalid API key
INVALIDKEY

setCollection_owns

Set a user's owned flag for the specified set. This will also set the qtyOwned to 0 or 1, as appropriate.

apiKey
API key
userHash
userHash token
setID
Set ID
owned
0 or 1.
Data type
String
Success
OK
Error in parameters
ERROR: {details}
Invalid userHash
ERROR: {details}
Invalid API key
INVALIDKEY

setCollection_wants

Set a user's wanted flag for a set.

apiKey
API key
userHash
userHash token
setID
Set ID
wanted
0 or 1
Data type
String
Success
OK
Error in parameters
ERROR: {details}
Invalid userHash
ERROR: {details}
Invalid API key
INVALIDKEY

setCollection_qtyOwned

Set a user's quantity owned of a set. This will also set the owned flag, as appropriate.

apiKey
API key
userHash
userHash token
setID
Set ID
qtyOwned
Integer, 0-999.
Data type
String
Success
OK
Error in parameters
ERROR: {details}
Invalid userHash
ERROR: {details}
Invalid API key
INVALIDKEY

setCollection_userNotes

Set a user's notes about a set.

apiKey
API key
userHash
userHash token
setID
Set ID
notes
String, up to 200 chars
Data type
String
Success
OK
Error in parameters
ERROR: {details}
Invalid userHash
ERROR: {details}
Invalid API key
INVALIDKEY

getUserNotes

Get all a user's set notes.

apiKey
API key
userHash
User hash retreived by the login method.
Success
Array of userNotes
Invalid API key
Nothing
Invalid userHash
Nothing

Minifig collection management

Method Parameters Output

getMinifigCollection

Get a list of meinifigs owned/wanted by a user.

apiKey
API key
userHash
userHash token
query
Filter the results: searches minifig number and name (e.g. SW will return all Star Wars minifigs)
owned
Set to 1 to retrieve minifigs owned
wanted
Set to 1 to retrieve minifigs wanted
Success
Array of minifigCollection
Error in parameters
Nothing
Invalid userHash
Nothing
Invalid API key
Nothing

setMinifigCollection

Add/change a user's 'loose' minifig collection. Wanted and qtyOwned are mandatory and if missing will result in an untrapped error.

apiKey
API key
userHash
userHash token
minifigNumber
BrickLink minifig number to change
qtyOwned
Integer, 0-999
wanted
0 or 1
Data type
String
Success
OK
Error in parameters
ERROR: {details}
Invalid userHash
ERROR: {details}
Invalid API key
INVALIDKEY

Advanced Collection Manager

Method Parameters Output

getCollectionDetail

Get a user's ACM data for a specific set.

apiKey
API key
userHash
userHash token
SetID
Set ID
Success
Array of collectionDetails
No records
Nothing
Invalid userHash
Nothing
Invalid API key
Nothing

setCollectionDetail

Get a user's ACM data for a specific ACM record.

apiKey
API key
userHash
userHash token
detail
single collectionDetails record, as returned from getCollectionDetail. Currency, modified and deleted fields are ignored.
Data type
String
Success
OK
Error in parameters
ERROR: {details}
Invalid userHash
ERROR: {details}
Invalid API key
INVALIDKEY

getCollectionDetailConditions

Get a list of valid set conditions for use with conditionWhenAcquired and conditionNow fields.

apiKey
API key
which
String, either 'Acquired' or 'Now' (case-insensitive)
Success
Array of conditions
Invalid Which
Nothing
Invalid API key
Nothing

Class definitions

Sets

Member Type Notes
setIDIntegerUnique database primary key
numberStringe.g. 6876
numberVariantIntegere.g. 1
nameString
yearString
themeString
themeGroupStringAs used on /browse/sets
subthemeString
piecesStringInteger, or null if pieces not known.
minifigsStringInteger, or null if no minifigs or not known.
imageBoolean
imageFilenameStringReturned only if an image is available (image=true)
thumbnailURLStringReturned only if an image is available (image=true). Max dimensions 96x72.
largeThumbnailURLStringReturned only if an image is available (image=true). Max dimensions 240x180.
imageURLStringReturned only if an image is available (image=true). Max dimensions 690x690.
bricksetURLStringURL of set details page at Brickset.com
releasedBoolean
ownedBooleanReturned only if userHash or userName is passed to method
wantedBooleanReturned only if userHash or userName is passed to method
qtyOwnedIntegerReturned only if userHash or userName is passed to method
ACMDataCountIntegerNumber of ACM records user has modified for this set
userNotesStringReturned only if userHash or userName is passed to method
ownedByTotalIntegerNumber of people who own this set
wantedByTotalIntegerNumber of people who want this set
UKRetailPriceString
USRetailPriceString
CARetailPriceString
EURetailPriceString
USDateAddedToSAHStringThe date the set was first sold as shop.LEGO.com in the USA
USDateRemovedFromSAHStringThe date the set was last sold as shop.LEGO.com in the USA. If USDateAddedToSAH is not blank but this is, it's still available.
ratingDecimal
reviewCountInteger
packagingTypeString
availabilityString
instructionsCountInteger
additionalImageCountInteger
EANString
UPCString
descriptionStringReturned only with call to getSet
lastUpdatedDate

minifigCollection

Member Type Notes
minifigNumberString
ownedInSetsInteger
ownedLooseInteger
ownedTotalInteger
wantedBoolean

themes

Member Type Notes
themeString
setCountInteger
subthemeCountIntegerPopulated by getThemes method only
yearFromIntegerPopulated by getThemes method only
yearToIntegerPopulated by getThemes method only

subthemes

Member Type Notes
themeString
subthemeString
setCountInteger
yearFromIntegerPopulated by getSubthemes method only
yearToIntegerPopulated by getSubthemes method only

year

Member Type Notes
themeString
yearString
setCountInteger

instructions

Member Type Notes
URLString
descriptionString

additionalImages

Member Type Notes
thumbnailURLStringMax dimensions 240x180
largeThumbnailURLStringNot used
imageURLString

reviews

Member Type Notes
authorString
datePostedDate
overallRatingInteger
partsInteger
buildingExperienceInteger
playabilityInteger
valueForMoneyInteger
titleString
reviewString
HTMLBoolean True is review contains HTML tags. Most written in the last few years do.

collectionDetails

Member Type Notes
collectionIDInteger
dateAcquiredStringThis can be a date, or general text to allow the user to enter non-specific dates e.g. 'May 2012', 'The 90's'
currencyStringThree character code for the currency the user has chosen to use, e.g. GBP, USD, EUR. Read-only.
pricePaidDecimal
additionalPricePaidDecimal
currentEstimatedValueDecimal
conditionWhenAcquiredStringNull, or one of the conditions returned by getConditions('acquired')
acquiredFromString
conditionNowStringNull, or one of the conditions returned by getConditions('now')
locationString
notesString
partsBoolean1 if the user has the parts, 0 if not
minifigsBoolean
instructionsBoolean
boxBoolean
modifiedBooleanRead-only.
willTradeBooleanTrue if user has indicated the set is for sale.trade. Not currently exposed to other users at Brickset.
deletedBooleanRead-only.

conditions

Member Type Notes
conditionString

collectionTotals

Member Type Notes
totalSetsOwnedInteger
totalDistinctSetsOwnedInteger
totalSetsWantedInteger
totalMinifigsOwnedInteger
totalMinifigsWantedInteger

userNotes

Member Type Notes
setIDInteger
userNotesString

Change log

Date Change
20th May 2016 USDateAddedToSAH and USDateRemovedFromSAH added to sets class
29th January 2016 released added to sets class
getCollectionTotals method and collectionTotals class added
getUserNotes method and userNotes class added
4th June 2014 getThemesForUser, getSubthemesForUser and getYearsForUser methods added
22nd April 2014 subthemeCount, yearFrom, yearTo added to themes class