Catalog APIs
Catalog APIs
Roblox offers formatted catalog item data for use in custom desktop and browser applications.
Avatar Catalog API
Only catalog items from the Avatar Shop can be queried through the following API. Searching for library catalog items (meshes, models, audio, etc.) can be done through the Library Catalog API.
Query Parameters
Search parameters can be specified by appending a series of parameters and values to the URL, each separated by a &. For example:
Parameter | Type | Options and Values |
---|---|---|
Category | byte | Featured (=0), All (=1), Collectibles (=2), Clothing (=3), BodyParts (=4), Gear (=5), Accessories (=11), AvatarAnimations (=12), and CommunityCreations (=13). |
CreatorName | string | Search by creator name. If CreatorType is not provided, search is for users only. |
CreatorTargetId | long | The user or group ID depending on the CreatorType provided. |
CreatorType | byte | User (=1) or Group (=2). |
Cursor | string | Each search response will contain a nextPageCursor if there is a next page and previousPageCursor if there is a previous page. Pass either of these values in the Cursor parameter of your next query to get the next or previous page of results. The cursor will only be valid if the other query parameters remain the same. |
Genres | byte | Specifies the genre for the search. The options are TownAndCity (=1), Medieval (=2), SciFi (=3), Fighting (=4), Horror (=5), Naval (=6), Adventure (=7), Sports (=8), Comedy (=9), Western (=10), Military (=11), Building (=13), FPS (=14), and RPG (=15). The recommended approach to filtering on genres is to match the URL of a catalog page. |
Keyword | string | Standard keyword search. |
Limit | int | Number of results to return. Values are currently limited to 10, 28, and 30. |
MaxPrice | int | The maximum amount of Robux that an item can be priced in the query. |
MinPrice | int | The minimum amount of Robux that an item can be priced in the query. |
SortAggregation | byte | PastDay (=1), PastWeek (=3), PastMonth (=4), and AllTime (=5). |
SortType | byte | Relevance (=0), Favorited (=1), Sales (=2), Updated (=3), PriceAsc (=4), and PriceDesc (=5). Default is Relevance. |
Subcategory | byte | Featured (=0), All (=1), Collectibles (=2), Clothing (=3), BodyParts (=4), Gear (=5), Hats (=9), Faces (=10), Shirts (=12), TShirts (=13), Pants (=14), Heads (=15), Accessories (=19), HairAccessories (=20), FaceAccessories (=21), NeckAccessories (=22), ShoulderAccessories (=23), FrontAccessories (=24), BackAccessories (=25), WaistAccessories (=26), AvatarAnimations (=27), Bundles (=37), AnimationBundles (=38), and EmoteAnimations (=39), CommunityCreations (=40), Melee (=41), Ranged (=42), Explosive (=43), PowerUp (=44), Navigation (=45), Musical (=46), Social (=47), Building (=48), and Transport (=49). |
Example Search
The following URL will search for the first 10 “Gear” items sorted by all-time (“SortAggregation”) and relevance (“SortType”).
Response Format
Here’s an example of an item returned in articles/JSON Storage Format|JSON
format:
Field | Description |
---|---|
assetType | One of the following asset type values (only returned if the item is an asset).
|
bundleType | The bundle type ID (only returned if the item is a bundle). Possible values are BodyParts and AvatarAnimations. |
creatorName | The creator's name. |
creatorTargetId | The creator's ID. |
creatorType | The item's creator type. |
description | The item description. |
favoriteCount | The favorite count of an item. |
genres | List of the item's genres. Possible values include All, Tutorial, Scary, TownAndCity, War, Funny, Fantasy, Adventure, SciFi, Pirate, FPS, RPG, Sports, Ninja, and WildWest. |
id | The ID of the item. |
itemRestrictions | List of the item's restrictions. Possible values include ThirteenPlus, LimitedUnique, Limited, and Rthro. |
itemStatus | List of the item's status flags. Possible values include New, Sale, XboxExclusive, AmazonExclusive, GooglePlayExclusive, IosExclusive, and SaleTimer. |
itemType | The item type. Possible values are Asset or Bundle. |
lowestPrice | The lowest reseller price of the item (only returned if the item is resellable). |
name | The item name. |
price | The listing price of the item (current price may differ if the item is resellable). |
priceStatus | The price status of an item that is not on sale. Possible values are Free, OffSale, or NoResellers. |
purchaseCount | The purchase count of an item. |
unitsAvailableForConsumption | The unit available for consumption of a limited unique item. |
Library Catalog API
Library catalog items (non-avatar items) can be queried through the following API by including “CatalogContext=2” in the search query. Searching for Avatar Shop items should be done with the Avatar Catalog API.
Query Parameters
Search parameters can be specified by appending a series of parameters and values to the URL, each separated by a &. For example:
Parameter | Type | Options and Values |
---|---|---|
CatalogContext | byte | Either omit this parameter or only use the DevelopOnly (=2) option to search for library catalog items. The AvatarOnly (=1) option has been deprecated and will result in an error. Use the Avatar Catalog API for avatar catalog item searches. |
Category | byte | Models (=6), Plugins (=7), Decals (=8), Audio (=9), and Meshes (=10). |
CreatorID | long | Specifies the Player/UserId|UserID to filter in the search, for example 1 for Roblox. If you'd like to find group-created items, enter the group agent's ID, not the group ID. |
CurrencyType | byte | All (=0), CustomRobux (=3), and Free (=5). Default is All. Use CustomRobux with custom PxMax and PxMin values. Specify Free for free items. |
Genres | byte | Specifies the genre for the search. The options are TownAndCity (=1), Medieval (=2), SciFi (=3), Fighting (=4), Horror (=5), Naval (=6), Adventure (=7), Sports (=8), Comedy (=9), Western (=10), Military (=11), Building (=13), FPS (=14), and RPG (=15). The recommended approach to filtering on genres is to match the URL of a catalog page. |
Keyword | string | Standard keyword search. |
PageNumber | int | Specifies a page number in conjunction with ResultsPerPage to page through results. |
PxMax | int | The maximum amount of Robux that an item can be priced in the query. |
PxMin | int | The minimum amount of Robux that an item can be priced in the query. |
ResultsPerPage | int | By default this is the same as what's currently shown on each catalog browse page. You can't specify a value larger than this maximum amount. |
SortAggregation | byte | PastDay (=0), PastWeek (=1), PastMonth (=2), and AllTime (=3). |
SortType | byte | Relevance (=0), MostFavorited (=1), Bestselling (=2), RecentlyUpdated (=3), PriceLowToHigh (=4), and PriceHighToLow (=5). Default is Relevance. |
Example Search
This URL will search for 10 items in the “Models” subcategory, sorted by most recently updated.
Response Format
Here’s an example of an item returned in articles/JSON Storage Format|JSON
format:
Among the returned fields, note the following:
Field | Notes |
---|---|
AssetTypeID | One of the following asset type values:
|
BestPrice | This will be empty except for limited edition items, in which case it will return the best price for the item. |
ContentRatingTypeID |
|
CreatedDate | Date the item was created in UTC format. |
MinimumMembershipLevel |
|
Name | Item name in UTF-8 format. |
PriceView | This is mostly used by the website to display prices. The options are:
|
PrivateSales | This will be empty except for limited edition items, in which case it will return the number of private sellers. |
UpdatedDate | Date the item was last updated in UTC format. |