getSingleItem
getSingleItem gets publicly visible details about one listing on Bonanza. This gives you most of the data that Bonanza shows to the general public on the View Item page (title, description, basic price information, and other details).
You just need to know the Bonanza item ID (a value like 123456789012) in order to retrieve the listing.
Note: What if you need to see item data that is normally only visible to the seller (where Bonanza would require them to login)? For this, you would need to use the authenticated version of this call (getUnlistedItem) instead.
getSingleItem Input
getSingleItemis a non-secure request with the following URL and HTTP header requirements:
Submit to URL: | https://api.bonanza.com/api_requests/standard_request |
Required in HTTP header: | X-BONANZLE-API-DEV-NAME set to your dev_id |
The name for your request should be getSingleItemRequest.
So, for example, here is the Ruby code to submit your request:
require "json" require "net/http" # Open connection to api.bonanza.com over port 443 http = Net::HTTP.new("api.bonanza.com", 443) http.use_ssl = true http.post( "/api_requests/standard_request", # The path we're posting to "getSingleItemRequest=your_serialized_JSON_data", # The data being posted { 'X-BONANZLE-API-DEV-NAME' => 'abcdef123456' } # The HTTP header, which gives your dev_id )
Here are the available input parameters that can be serialized into JSON:
Argument | Type | Occurrence | Meaning |
---|---|---|---|
Call-specific Input Fields | |||
itemId | string | Required | The item ID that uniquely identifies the item listing for which to retrieve the data. You can determine an item's ID by calling FindItems or from the Bonanza Web site. Max length: 19 (Note: The Bonanza database specifies 38. Currently, Item IDs are usually 9 to 12 digits). |
getSingleItem Output
The name for the output returned from this request is getSingleItemResponse. So, after parsing the serialized response into JSON, you can access the data with something like:
my_json_hash['getSingleItemResponse']
Here are all the possible output parameters:
Argument | Type | Occurrence | Meaning |
---|---|---|---|
Standard Output Fields | |||
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. |
timestamp | dateTime | Always | This value represents the date and time when Bonanza processed the request. The time zone of this value is GMT and the format is the ISO 8601 date and time format (YYYY-MM-DDTHH:MM:SS.SSSZ). See the "dateTime" type for information about this time format and converting to and from the GMT time zone. |
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. |
Call-specific Output Fields | |||
item | Container | Always | Container for more detailed item information. |
item.bestOfferEnabled | boolean | Always | Whether the seller will accept a best offer for this item. This feature enables a buyer to make a lower-priced binding offer on a fixed price item. Buyers can't 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. |
item.buyItNowPrice | AmountType (double) | Conditionally | Pseudonym for currentPrice. |
item.convertedBuyItNowPrice | AmountType (double) | Conditionally | Pseudonym for currentPrice. |
item.convertedCurrentPrice | AmountType (double) | Always | Pseudonym for currentPrice. |
item.country | CountryCodeType | Always | Two-letter ISO 3166 country code to indicate the country where the item is located. |
item.currentPrice | AmountType (double) | Always | The listing's current price in USD. |
item.description | string | Always | The seller's description of the item, if any. This can include HTML markup. Max length:60000. |
item.ebayId | int | Optional | The unique ebay ID for this item. |
item.galleryURL | anyURI | Conditionally | URL for a picture used as the Gallery thumbnail, if any. The image uses one of the following graphics formats: JPEG, BMP, TIF, or GIF. Only returned if the seller chose to show a gallery image. |
item.itemID | string | Always | The ID that uniquely identifies the item listing. Bonanza generates this ID when an item is listed. This ID is unique across all Bonanza sites. |
item.itemSpecifics | Container | Conditionally | Category-specific fields that the seller added to describe the listing. The names of these fields are different for items in different categories, so they're returned in a generic Name/Value structure. The field names are usually very well known within the category. For example, a book's item specifics might include a field like Publication Year=2007 (where Publication Year is returned in Name, and 2007 is returned in Value), and a field like Format=Hardcover. But a car's item specifics would be different from a book's, with fields like Make= Toyota and Model=Prius. And a ticket's item specifics would be different from those of books and cars, with fields like EventType=Concerts and Venue=The Fillmore. One of the most common uses for item specifics is the item condition. Only returned if the seller included Item Specifics in the listing. |
item.itemSpecifics .nameValueList |
Container | Conditionally, repeatable: [0..*] |
This list is an array of Item Specifics, which are category-specific fields that the seller added to describe the listing. The names of these fields are different for items in different categories, so they're returned in a generic name/value structure. For example, Item Specifics for a car might include a field like Make=Toyota (where Make is returned in Name, and Toyota is returned in Value) and Model=Prius (where Model is returned in Name, and Prius is returned in Value). In multi-variation listings, the same name cannot appear in both the VariationSpecifics node and in the ItemSpecifics node. |
item.itemSpecifics .nameValueList.name |
string | Conditionally | The name of the item specific. This field is returned only in responses if the seller included an item specific Name in the listing. However, if the seller didn't also include a corresponding value for the item specific, it is best to not display the name to name to avoid confusing users. |
item.itemSpecifics .nameValueList.value |
string | Conditionally, repeatable: [0..*] |
A value for the item specific. This field is only returned in responses if the seller included a value for an item specific. In the GetSingleItem response, this field is always returned for each item specific that is returned (if any). However, if the seller didn't select a value for the item specific, this field may return empty, or it may return a value like "-", "Not Selected", or "Unspecified" (or the equivalent in the language of the site). |
item.listingStatus | string | Always | 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:
|
item.location | string | Always | Physical location of the item, as specified by the seller. (This gives a general indication of where the item will be shipped or delivered from.) |
item.paymentMethods | string | Conditionally, repeatable: [0..*] |
Lists the payment type(s) accepted as payment for this item. Possible values include:
|
item.pictureURL | anyURI | Conditionally, repeatable: [0..24] |
Contains the URL for an image associated with the item, if any. Returned only if the seller included at least one picture in their listing. Note that this element does not return the URLs of pictures that the seller included in the Description via HTML IMG tags. |
item.viewItemURL | anyURI | Always | The canonical listing URL for the item. |
item.postalCode | string | Always | Postal code indicating the physical location of the item, as specified by the seller. (This gives a general indication of where the item will be shipped or delivered from.) |
item.primaryCategory | Container | Always | |
item.primaryCategory.categoryId | Integer | Always | Numeric ID of the first (or only) category in which the item is listed. (Listings can appear in more than one category.) |
item.primaryCategory.categoryName | string | Always | Display name of the first (or only) category in which the item is listed. This is a fully qualified category breadcrumb (e.g., Computers & Networking:Laptops, Notebooks). |
item.primaryCategory.categoryHierarchy | Array | Always | An array of category IDs from the parent category downward. |
item.quantity | int | Always | The number of items the seller currently has available for sale. |
item.returnPolicy | Container | Optional | Holds details about the return policy for this item. |
item.returnPolicy. description |
string | Optional | Details of the seller's return policy. |
item.returnPolicy. returnsAccepted |
string | Optional | Whether the seller will accept returns on this item. Possible options:
|
item.returnPolicy. returnsWithin |
integer | Optional | The buyer can return the item within this period of time from the day they receive the item. |
item.returnPolicy. shippingCostPaidBy |
string | Optional | Value should be "seller" if the seller will pay return shipping, or "buyer" if not. |
item.seller | Container | Always | Container for information about this listing's seller. |
item.seller.feedbackRatingStar | string | Always |
Visual indicator of user's feedback score. feedbackRatingStar values:
|
item.seller.feedbackScore | int | Always |
The aggregate feedback score of a user. A user's feedback score is the net positive feedback minus the net negative feedback left for the user. |
item.seller.positiveFeedbackPercent | float | Always | A seller's positive feedback score. The percentage value of a seller's positive feedback is calculated by dividing the seller's positive feedback score by their negative feedback score. The last 12 months of feedback scores are taken into consideration for this calculation. |
item.seller.userId | string | Always | The user's unique Bonanza user ID. |
item.shippingCostSummary | Container | Always | Container for shipping information. |
item.shippingCostSummary .carrier |
String | Conditionally | The shipping carrier, if the shipping type is "calculated." Possible values include "usps", "ups", and "fedex". |
item.shippingCostSummary .insuranceCost |
AmountType (double) | Conditionally | The cost of insurance. For flat rate shipping, this is the value set by the seller, if any. |
item.shippingCostSummary .insuranceType |
String | Conditionally | The type of shipping insurance. Applicable values: None, Optional, Required, Included. |
item.shippingCostSummary .packageSize |
String | Conditionally | A text description of the size specified for the package, if the shipping type is "calculated." |
item.shippingCostSummary .shippingServiceCost |
AmountType (double) | Conditionally | The basic shipping cost of the item. |
item.shippingCostSummary .shippingType |
ShippingTypeCodeType | Always | 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:
|
item.shippingCostSummary .shippingLbs |
Integer | Conditionally | The number of pounds specified for the package. Returned only if shipping type is "calculated." |
item.shippingCostSummary .shippingOz |
Integer | Conditionally | The number of ounces for the package, in excess of its pounds (i.e., if the package is 5 lbs, 2 oz, this will return "2"). Returned only if shipping type is "calculated." |
item.shippingCostSummary .shippingServices |
Container | Conditionally, 1..* | Array of details about shipping services |
item.shippingCostSummary .shippingServices .name |
String | Always | Name of shipping service (e.g., "USPS Priority") |
item.shippingCostSummary .shippingServices .carrier |
String | Always | Name of shipping service carrier (e.g., "USPS") |
item.shippingCostSummary .shippingServices .shippingServiceCost |
AmountType (double) | Conditionally | Cost of this shipping service, if flat rate. Absent if not |
item.shipToLocations | Container | Always, repeatable: [1..*] |
International locations to which the seller is willing to ship this item. Returned only for items that have ShipToLocations specified. |
item.shipToLocations .region |
string | Conditionally | The region for this data. Applicable values:
|
item.shipToLocations .shippingServiceCost |
AmountType (double) | Conditionally | The basic shipping cost of the item to the region specified. |
item.shipToLocations .shippingType |
ShippingTypeCodeType | Always | 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:
|
item.startTime | dateTime | Always | Time stamp (in GMT) that Bonanza recorded as the moment that the listing was made available. The start time returned by a search call may vary from the value returned by GetSingleItem. |
item.sku | string | Optional | SKU of the item, for inventory tracking purposes. |
item.title | string | Always | Name of the item as it appears in the listing or in search and browse results. |
item.variations | Container | Optional | Details about potential variations for this item. Variations are multiple similar (but not identical) items in a single fixed-price listing. For example, a T-shirt listing could contain multiple items of the same brand that vary by color and size (like "Blue, Large" and "Black, Medium"). Each variation specifies a combination of one of these colors and sizes. Each variation can have a different quantity. You can buy multiple items from one variation at the same time. (That is, one order line item can contain multiple items from a single variation.) |
item.variations.variation | ItemVariation, optionally [0..*] | Conditionally | Details about one or more item variations |
item.variations. variation. price |
integer | Conditionally | The quantity of this particular item variation |
item.variations. variation. quantity |
integer | Conditionally | The quantity of this particular item variation |
item.variations. variation. pictureURL |
string | Optional | Contains the URL for an image associated with the variation, if any. |
item.variations. variation. sku |
string | Optional | The SKU specific to this varation. An item may have one SKU that covers all variations, or different SKUs for each variation. |
item.variations. variation. nameValueList |
NameValueList container, optionally [0..*] | Conditionally | A container for the one or more name/value pairs of the item variations |
item.variations. variation. nameValueList. name |
string | Conditionally | The name of the attribute being specified, i.e., "Size". Gathered from GetCategoryTraits. |
item.variations. variation. nameValueList. value |
string | Conditionally | The value of the attribute referred to by "name." For example, if name was "Size" value may be "L". Potential values can be gleaned from from GetCategoryTraits. |