findItemsByKeywords

findItemsByKeywords lets you to search for items on Bonanza by a keyword query (keywords).

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. findItemsByKeywords lets you refine your search results using item filters (itemFilter). Use paginationInput and outputSelector to control the amount of data returned from each request. Results are sorted by Best Match by default, with the most relevant items listed first. Use sortOrder to specify a different sort order, such as sorting by current price or the listing end time.

Take a look at some examples in C#, Java, PHP, Python, and Ruby.

The following sections detail how to control the information returned in the response sets:

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.

The default sort order is by best match (BestMatch), which sorts items by relevancy to your search. Relevancy is based upon community buying activity and other relevance-based factors.

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

By default, the response returns the first page of data up to a maximum of 100 items. The following example shows how to return the second page of results, with each page containing a maximum of 50 items:

...&paginationInput.pageNumber=2&paginationInput.entriesPerPage=50...

In this example, the response will contain the matching items 51 to 100, assuming there are at least 100 matching items.

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.

findItemsByKeywords Input

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

my_json_hash['findItemsByKeywordsResponse']

Here are all the possible output parameters:

Argument Type Occurrence Meaning
Standard Input Fields
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.

findItemsByKeywords Output

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

my_json_hash['findItemsByKeywordsResponse']

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.
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.
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.sku string Conditionally SKU of the item, for inventory tracking purposes.
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.

findItemsByKeywords Examples