findItemsByCategory

findItemsByCategory retrieves a list of all Bonanza items in a specified category

The response contains details about items matching the search criteria. By default, Bonanza returns a specific set of data in the response to your call. findItemsByCategory lets you refine your search results using item filters (itemFilter). Use paginationInput to control the amount of data returned from each request. Results are sorted by listing date. Use sortOrder to specify a different sort order, such as sorting by current price or the listing end time.

Controlling Results with Item Filters

Filters provide you with control over search results by narrowing the range of items returned. The itemFilter container uses name/value pairs to describe specific filters. You can specify filters for variety of properties, including the item condition, price range, listing type, and so on. All item filters are optional input parameters.

Sorting the Output

Use the sortOrder element to specify the order in which the returned items are sorted. For example, specify a value of PricePlusShippingAsc to sort results by the combined cost of item price plus shipping cost, with the lowest priced items listed first. Sorting has no affect upon the quantity of returned results.

See sortOrder for more information.

Paginating the Results

Use paginationInput and its child elements to control which set of items matching the search criteria are returned in the result set. Use paginationInput to divide the returned items into subsets, or "pages," of data:

paginationInput.entriesPerPage specifies the maximum number of items to return for any given request
paginationInput.pageNumber specifies which "page" of data to return in the current call

In the response, paginationOutput contains corresponding fields for paginating data:

paginationOutput.totalEntries indicates the total number of items matching the input search criteria that could be returned (with one or multiple calls). If the value specified in paginationInput.entriesPerPage is less than that returned in paginationOutput.totalEntries, then it will take more than one call to retrieve all of the matching items.
paginationInput.pageNumber indicates where in the sequence of multiple calls the application is.
paginationOutput.entriesPerPage field indicates the maximum number of items that can be returned in a response. The count attribute for the searchResult field indicates the actual number of items returned in the response. The value of entriesPerPage divided by the total number of matching items determines how many pages of output can be returned for a given query.

See paginationInput and paginationOutput for more information.

findItemsByCategory Input

The name for the output returned from this request is findItemsByCategoryResponse. So, after parsing the serialized response into JSON, you can access the data with something like:

my_json_hash['findItemsByCategoryResponse']

Here are all the possible output parameters:

Argument	Type	Occurrence	Meaning
Standard Input Fields
categoryId	integer	Required	The Bonanza category ID. getCategories
paginationInput	Container	Optional	Controls the pagination of the result set. Child elements specify the maximum number of item listings to return per call and the page of data to return. Controls the number of listings returned in the response, but does not specify the details to return for each listing. Note: No more than 10,000 items can be retrieved for a given search, regardless of how many matches are found. This limit is enforced by the maximum page number allowed (100) and the maximum entries per page allowed (100).
paginationInput.entriesPerPage	int	Optional	Specifies the maximum number of entries to return in a single call. If the number of entries found on the specified pageNumber is less than the value specified here, the number of items returned will be less than the value of entriesPerPage. This indicates the end of the result set. If entriesPerPage is set to a number greater than 100, the default value, 100, will be used. Max: 100. Default: 100.
paginationInput.pageNumber	int	Optional	Specifies which subset of data (or "page") to return in the call response. The number of data pages is determined by the total number of items matching the request search criteria (returned in paginationOutput.totalEntries) divided by the number of entries to display in each response (entriesPerPage). You can return up to the first 100 pages of the result set by issuing multiple requests and specifying, in sequence, the pages to return. Max: 100. Default: 1.
sortOrder	SortOrderType	Optional	Sort the returned items according to a single specified sort order. Default: BestMatch. Applicable values: BestMatch (in) Sorts items by Best Match, which is based on community buying activity and other relevance-based factors. CurrentPriceHighest (in) Sorts items by their current price, with the highest price first. CurrentPriceLowest (in) Sorts items by their current price, with the lowest price first. StartTimeNewest (in) Sorts items by the start time, the most recently listed (newest) items appear first.
Call-specific Input Fields
itemFilter	Container	Optional, repeatable: [0..*]	Reduces the number of items returned in the response according to the filters you specify. See list of all possible filters in ItemFilters
itemFilter.name	ItemFilterType	Optional	Specify the name of the item filter you want to use. The itemFilter name must have a corresponding value. You can apply multiple itemFilter Name/Value pairs in a single request. See the ItemFilterType type documentation for more information about the allowed values, usage rules, and dependencies. Refer to the following samples to see itemFilters in action: Using itemFilters to define a price range Using itemFilters to search for used Buy It Now items.
itemFilter.value	string	Optional, repeatable: [1..*]	The value associated with the respective itemFilter Name.
keywords	string	Required	Specify one or more words to use in a search query for finding items on Bonanza. By default, queries search item titles only. When running queries, it is best to include complete keywords values--Bonanza checks words in context with each other.

findItemsByCategory Output

The name for the output returned from this request is findItemsByCategoryResponse. So, after parsing the serialized response into JSON, you can access the data with something like:

my_json_hash['findItemsByCategoryResponse']

Here are all the possible output parameters:

Return Value	Type	Occurrence	Meaning
Standard Output Fields
ack	AckValue	Always	Indicates whether or not errors or warnings were generated during the processing of the request. Applicable values: Failure (out) Bonanza encountered a fatal error during the processing of the request, causing the request to fail. When a serious application-level error occurs, the error is returned instead of the business data. Success (out) Bonanza successfully processed the request and the business data is returned in the response. Note that it is possible for a response to return Success, but still not contain the expected data in the result. Warning (out) The request was successfully processed, but Bonanza encountered a non-fatal error during the processing. For best results, requests should return without warnings. Inspect the warning details and resolve the problem before resubmitting the request.
errorMessage	Container	Conditionally	Description of an error or warning that occurred when Bonanza processed the request. Not returned if the ack value is Success.
errorMessage.error	Container	Conditionally, repeatable: [0..*]
errorMessage.error.category	ErrorCategory	Conditionally	Currently unused.
errorMessage.error.message	string	Conditionally	A description of the error
errorMessage.error.type	ErrorType	Conditionally	A unique descriptive name for the error.
paginationOutput	Container	Conditionally	Indicates the pagination of the result set. Child elements indicate the page number that is returned, the maximum number of item listings to return per page, total number of pages that can be returned, and the total number of listings that match the search criteria.
paginationOutput .entriesPerPage	int	Conditionally	The maximum number of items that can be returned in the response. This number is always equal to the value input for paginationInput.entriesPerPage. The end of the result set has been reached if the number specified for entriesPerPage is greater than the number of items found on the specified pageNumber. In this case, there will be fewer items returned than the number specified in entriesPerPage. This can be determined by comparing the entriesPerPage value with the value returned in the count attribute for the searchResult field.
paginationOutput.pageNumber	int	Conditionally	The subset of item data returned in the current response. Search results are divided into sets, or "pages," of item data. The number of pages is equal to the total number of items matching the search criteria divided by the value specified for entriesPerPage in the request. The response for a request contains one "page" of item data. This returned value indicates the page number of item data returned (a subset of the complete result set). If this field contains 1, the response contains the first page of item data (the default). If the value returned in totalEntries is less than the value for entriesPerPage, pageNumber returns 1 and the response contains the entire result set. The value of pageNumber is normally equal to the value input for paginationInput.pageNumber. However, if the number input for pageNumber is greater than the total possible pages of output, Bonanza returns the last page of item data in the result set, and the value for pageNumber is set to the respective (last) page number.
paginationOutput.totalEntries	int	Conditionally	The total number of items found that match the search criteria in your request. Depending on the input value for entriesPerPage, the response might include only a portion (a page) of the entire result set. A value of "0" is returned if Bonanza does not find any items that match the search criteria.
searchResult	Container	Always	Container for the item listings that matched the search criteria. The data for each item is returned in individual containers, if any matches were found.
searchResult.item	Container	Always, repeatable: [1..*]	Container for the data of a single item that matches the search criteria.
searchResult.item.country	string	Conditionally	Two-letter ISO 3166 country code to indicate the country where the item is located. For English names that correspond to each code (e.g., KY="Cayman Islands"), see the ISO site: http://www.iso.ch/iso/en/prods-services/iso3166ma/02iso-3166-code-lists/list-en1.html.
searchResult.item.galleryURL	anyURI	Conditionally	URL for the Gallery thumbnail image. The image must be provided in one of the following graphics formats: JPEG, BMP, TIF, or GIF. Returned only if the seller chose to show a gallery image.
searchResult.item.globalId	string	Always	Currently always returns "Bonanza".
searchResult.item.itemId	string	Always	The ID that uniquely identifies the item listing. Bonanza generates this ID when an item is listed. ID values are unique across all Bonanza sites. Max length:19.
searchResult.item.listingInfo	Container	Conditionally	None (just a container)
searchResult.item.listingInfo .bestOfferEnabled	boolean	Conditionally	Shows whether or not the seller will accept a best offer for the associated item. Best Offer allows a buyer to make a lower-priced binding offer on a fixed price item. Buyers cannot see how many offers have been made (only the seller can see this information). To make a best offer on a listing, use the Bonanza Web site.
searchResult.item.listingInfo .buyItNowPrice	Amount (double)	Conditionally	The Buy It Now Price of the item
searchResult.item.listingInfo .convertedBuyItNowPrice	Amount (double)	Conditionally	Pseudonym for "buyItNowPrice"
searchResult.item.listingInfo .lastChangeTime	datetime	Conditionally	The last date that this item was modified in any way.
searchResult.item.listingInfo .listingType	string	Conditionally	The format of the listing, such as online auction, fixed price, or advertisement. * listingType values: FixedPrice: A fixed-price listing. Currently the only possibility.
searchResult.item.listingInfo .startTime	dateTime	Conditionally	Time stamp that Bonanza recorded as the moment the listing was made available. This value is returned in GMT, the ISO 8601 date and time format (YYYY-MM- DDTHH:MM:SS.SSSZ). See the "dateTime" type for information about the time format, and for details on converting to and from the GMT time zone. Note that it is possible for startTime to be different from the value returned by GetSingleItem.
searchResult.item.location	string	Conditionally	Physical location of the item, as specified by the seller. This gives a general indication from where the item will be shipped (or delivered).
searchResult.item .paymentMethod	string	Conditionally, repeatable: [0..*]	Lists the payment type(s) accepted as payment for this item. Possible values include: Paypal Amazon Credit Card
searchResult.item.postalCode	string	Conditionally	The postal code where the listed item is located, returned only if a postal code has been specified by the seller.
searchResult.item .primaryCategory	Container	Always	Details about the first (or only) category in which the item is listed. Note that items can be listed in more than a single category.
searchResult.item .primaryCategory.categoryId	string	Always	The unique ID of a category on the specified Bonanza site.
searchResult.item .primaryCategory.categoryName	string	Always	Display name of a category as it appears on the Bonanza Web site.
searchResult.item.sellerInfo	Container	Always	Information about the item's seller.
searchResult.item.sellerInfo . availableForChat	boolean	Always	True if the seller is currently available to chat about their items.

searchResult.item.sellerInfo .feedbackRatingStar	string	Always	Visual indicator of user's feedback score. feedbackRatingStar values: None: No graphic displayed, feedback score 0-9. Yellow: Yellow Star, feedback score 10-49. Blue: Blue Star, feedback score 50-99. Turquoise: Turquoise Star, feedback score 100-499. Purple: Purple Star, feedback score 500-999. Red: Red Star, feedback score 1,000-4,999. Green: Green Star, feedback score 5,000-9,999. YellowShooting: Yellow Shooting Star, feedback score 10,000-24,999.
searchResult.item.sellerInfo .membershipLevel	int	Always	The seller's subscription level: Not a subscriber, just standard member Plus member Premiere member
searchResult.item.sellerInfo .positiveFeedbackPercent	double	Always	The percentage value of a user's positive feedback (their positive feedbackScore divided by their total positive plus negative feedback).
searchResult.item.sellerInfo .sellerUserName	string	Always	The seller's Bonanza user name; a unique value.
searchResult.item.sellerInfo . userPicture	anyURI	Conditional	The URL of the seller's full size picture, if they have uploaded one.
searchResult.item .sellingStatus	SellingStatus	Conditionally	Specifies the item's selling status with regards to Bonanza's processing workflow.
searchResult.item .sellingStatus .convertedCurrentPrice	Amount (double)	Conditionally	Pseudonym for "currentPrice."
searchResult.item .sellingStatus.currentPrice	Amount (double)	Conditionally	The current price of the item given in the currency of the site on which the item is listed. That is, currentPrice is returned in the original listing currency.
searchResult.item .sellingStatus.sellingState	string	Conditionally	Specifies the listing's status in Bonanza's processing workflow. If an item's EndTime is in the past, but there are no details about the buyer or high bidder (and the user is not anonymous), you can use sellingState information to determine whether Bonanza has finished processing the listing. sellingState values: Active: The listing is still live. It is also possible that the auction has recently ended, but Bonanza has not completed the final processing (e.g., the high bidder is still being determined). Canceled: The listing has been canceled by either the seller or Bonanza. Missing required fields: The listing needs one or more fields populated before it can be put up for sale (required fields are currently title, category, and price) Ready for sale: The has all the needed fields populated, and will be put up for sale next time the booth is updated/activated Reserved: The seller has marked the item as "reserved"; it will remain in our system, not available for sale, until the seller reactivates it Sold: The item has been sold Unknown: Typically seen when an item has been purged from existence and is awaiting deletion Another number: This indicates the native item status ID on Bonanza. If you see a number being reported as the item status and you aren't sure why, please report it to api@bonanza.com
searchResult.item.shippingInfo	Container	Conditionally	Container for data about a listing's shipping details.
searchResult.item.shippingInfo .shippingServiceCost	Amount (double)	Conditionally	The basic shipping cost of the item.
searchResult.item.shippingInfo .shippingType	string	Conditionally	The shipping method that was used for determining the cost of shipping. For example: flat rate, calculated, or free. The seller specifies the available shipping services when they list the item. shippingType values: Calculated: The calculated shipping model: The posted cost of shipping is based on the buyer-selected shipping service, chosen by the buyer from the different shipping services offered by the seller. The shipping costs are calculated by Bonanza and the shipping carrier, based on the buyer's address. Any packaging and handling costs established by the seller are automatically rolled into the total. Flat: The flat-rate shipping model: The seller establishes the cost of shipping and any shipping insurance, regardless of what any buyer-selected shipping service might charge the seller. Free: Free is used when the seller has declared that shipping is free for the buyer. NotSpecified: The seller did not specify the shipping type.
searchResult.item.shippingInfo .shipToLocations	string	Conditionally, repeatable: [0..*]	An international location or region to which the seller is willing to ship the item. Returned only for items that have shipToLocations specified. For a complete list of shipping locations, see shipToLocations.
searchResult.item.storeInfo	Container	Always	Information about the Bonanza store in which the item is listed.
searchResult.item.storeInfo .storeDiscount	Container	Conditionally	Present if the store has setup a pricing discount.
searchResult.item.storeInfo .storeDiscount.priceThreshold	double	Conditionally	Dollar amount to spend to get a booth discount.
searchResult.item.storeInfo .storeDiscount.discountPercent	int	Conditionally	Percentage discount applied to all items in order, if buyer reaches the price threshold specified in "priceThreshold". For example, if priceThreshold is "100" and discountPercent is "10", then the buyer would receive no discount if their order totaled $95. But if their order totaled $100, they would receive a $10 discount and pay only $90 total.
searchResult.item.storeInfo .storeItemCount	int	Always	Number of items currently for sale in this booth. Note that if a particular item has a quantity of more than one, it is still counted as only one item for the sake of storeItemCount. This is the number of unique items in the store.
searchResult.item.storeInfo .storeName	string	Conditionally	The name of the seller's Bonanza Store.
searchResult.item.storeInfo .storeURL	anyURI	Conditionally	The URL of the seller's Bonanza Store page.
searchResult.item.title	string	Conditionally	Name of the item as it appears in the listing title, or in search and browse results.
searchResult.item.viewItemURL	anyURI	Conditionally	The URL to view this specific listing on Bonanza.
timestamp	dateTime	Always	This value represents the date and time when Bonanza processed the request. This value is returned in GMT, the ISO 8601 date and time format (YYYY- MM- DDTHH:MM:SS.SSSZ). See the "dateTime" type for information about the time format, and for details on converting to and from the GMT time zone.
version	string	Always	The release version that Bonanza used to process the request. Developer Technical Support may ask you for the version value if you work with them to troubleshoot issues. Note: The version in use is normally the latest release version, as specified in the release notes. Note that Bonanza releases the API to international sites about a week after the API version is released to the US site.
warnings	Container	Conditionally	Description of a warning that occurred when Bonanza processed the request.
warnings.unrecognized_parameters	Container	Conditionally, repeatable: [0..*]	An array of unrecognized parameters.