eBay Finding API Call Reference Version 1.2.0 Support     Knowledge Base     Forums     All Tutorials     All Code Samples Users Guide Call Reference Making an API Call Tutorials Release Notes

List of All Calls Field Index Enumeration Index Type Index Errors by Number Input Output Detail Controls Samples Change History User Notes

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

The response contains details about items matching the search criteria. By default, eBay returns a specific set of data in the response to your call. findItemsByKeywords lets you refine your search results using item filters (itemFilter) and aspect filters (aspectFilter). 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.

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

• Specifying the eBay Site
• Controlling Results with Item Filters
• Refining Results with Aspect and Domain Filters
• Finding Local Items
• Expanding Output Data with outputSelector Fields
• Sorting the Output
• Paginating the Results
• Specifying Affiliate Details

Specifying the eBay Site

The GLOBAL-ID URL parameter (or X-EBAY-SOA-GLOBAL-ID HTTP header) specifies the eBay site to use for searches. When specifying a global ID (e.g., EBAY-DE for the eBay Germany site), the search response contains only items available on the site specified. If you do not specify a global ID, eBay uses the US site (EBAY-US) by default.

For more information about URL parameters and HTTP headers, see Making a Finding API Call.

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, number of bids, price range, listing type, and so on. All item filters are optional input parameters.

For example, the following URL-formatted filter specifies that items returned in the result must have free shipping:

...&itemFilter.name=FreeShippingOnly&itemFilter.value=true...

Some filters take additional parameters. For example, when using the MaxPrice or MinPrice filters, you can specify the currency value with itemFilter.paramName and itemFilter.paramValue. When you use MaxPrice and MinPrice item filters, itemFilter.paramName defaults to Currency and itemFilter.paramValue defaults to USD.

If you specify multiple item filter name/value pairs in a URL message format, you must specify the multiple filters using array notation, as shown in the following example:

...&itemFilter(0).name=FreeShippingOnly&itemFilter(0).value=true&itemFilter(1).name=ListingType&itemFilter(1).value=FixedPrice...

For more details on how to use item filters, see Refining a Search with Item Filters in the User Guide. See the ItemFilterType type documentation for more information about the allowed values, usage rules, and dependencies.

Refining Results with Aspect and Domain Filters

Aspects are well-known, standardized characteristics of an item. For example, "Style," "Color," and "Shoe Size" could be aspects of Men's Shoes. Aspects can vary for different kinds of items—the aspects of Men's Shoes are different from those of Digital Cameras (aspects for Digital Cameras might include "Optical Zoom" and "Megapixels"). Domains are a buy-side grouping of items, such as shoes or digital cameras. A domain can span many eBay categories.

Aspect and domain information can be used to create filters to refine your search results. To see aspects in action, a search request on the eBay site often displays aspects and their respective aspect values on the left-hand side of a search result page Aspect values are the details of the aspect. For instance, Optical Zoom might have an associated aspect value of "10x." eBay determines aspect values from listing properties such as item specifics, titles, and subtitles.

When searching for items with one of the Finding API calls, you can request that an aspect histogram to be returned in the result. In a URL request, specify outputSelector=AspectHistogram. The resulting aspect histogram provides information you can use to refine your search. The histogram lists the aspects for the domain that are most pertinent to your search. In addition, for each aspect, all the associated aspect values are listed with the number of active listings that match that given aspect value. For example, "Athletic" or "Dress Shoes" could be aspect values associated with the "Style" aspect of Men's Shoes.

Aspect filters consist of an aspectName, and one or more aspectValueName values. Find the values for each of these fields in the aspect containers returned in a query response that has aspect histogram values. For example, the following shows a URL-formatted aspect filter using values taken from a previous search response:

...&aspectFilter.aspectName=Sub Style&aspectFilter.aspectValueName=Running Shoes...

Domain filters consist of one or more domainName values. The domainName value is in the aspectHistogramContainer returned in a query response that has aspect histogram values. For example, the following shows a URL-formatted domain filter using values taken from a previous search response:

...&domainFilter.domainName=Digital_Cameras...

See aspectFilter and domainFilter for more information.

Finding Local Items

You can specify buyerPostalCode for distance-based searching. Find items located close to you by specifying buyerPostalCode and setting sortOrder to Distance. The following sample will sort matching items in the results with items closest to the buyer's postal code listed first:

...&buyerPostalCode=95125&sortOrder=Distance...

You can locate items that have been listed for local-markets only by specifying a buyerPostalCode and item filters for LocalSearch and MaxDistance. The following sample returns only the items listed for both for local markets and are located within a 100-mile radius of the buyer's postal code (wrapped for readability):

...&buyerPostalCode=95125&itemFilter(0).name=LocalSearchOnly&itemFilter(0).value=true
&itemFilter(1).name=MaxDistance&itemFilter(1).value=100...

Note that depending on the specified global ID, the value returned for the distance can be in either kilometers or miles. For example, if the global ID is EBAY-DE (Germany), the distance is returned as kilometers.

Expanding Output Data with outputSelector Fields

Each searchResult.item container returns with a default set of data for the items matching your request. If you want more data than the default set of data, use one or more outputSelector fields to expand the results:

• SellerInfo—Include information about the seller in the response.
• StoreInfo—Include information about the seller's eBay store in the response.
• AspectHistogram—Include an AspectHistogram container with information about aspects from the domain that is most relevant to your search.
• CategoryHistogram—Include a CategoryHistogram container with information about categories that match your search.

If you are using a URL-formatted request, specify multiple outputSelector fields using array notation, as shown in the following example:

...&outputSelector(0)=SellerInfo&outputSelector(1)=StoreInfo...

See outputSelector for more information.

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.
• paginationOutput.totalPages indicates the total number of calls that would be required to retrieve all of the matching items.
• paginationInput.pageNumber indicates where in the sequence of multiple calls the application is, relative to the number returned in paginationInput.totalPages.
• 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.

Specifying Affiliate Details

Affiliates can earn money from eBay by driving traffic to eBay. As an affiliate, you promote eBay on your site. If eBay captures a sale or a new member registration through your promotion, eBay will pay you money. eBay tracks the traffic generated from your application by your affiliate ID, which you need to embed in your code. Commissions are generated when users perform qualifying actions, such as bidding, buying, or registering on the site.

The affiliate container has the following fields: networkId, trackingId, and customId. If you are registered with eBay Partner Network, the networkId is 9 and the trackingId is your Campaign ID.

The following example shows how to specify your affiliate tracking details in a URL:

...&affiliate.trackingId=1234567899&affiliate.networkId=9&affiliate.customId=234...

Related Information

See also the reference documentation for these calls:

• findItemsAdvanced - Finds items by a keyword query and/or category and allows searching within item descriptions.
• getSearchKeywordsRecommendation - Checks specified keywords and returns correctly spelled keywords for best search results.

Back to top

The box below lists all fields that could be included in the call request. To learn more about an individual field or its type, click its name in the box (or scroll down to find it in the table below the box).

See also Samples.

<?xml version="1.0" encoding="utf-8"?>
<findItemsByKeywordsRequest xmlns="http://www.ebay.com/marketplace/search/v1/services">
  <!-- Standard Input Fields -->
  <affiliate> Affiliate 
    <customId> string </customId>
    <networkId> string </networkId>
    <trackingId> string </trackingId>
  </affiliate>
  <buyerPostalCode> string </buyerPostalCode>
  <paginationInput> PaginationInput 
    <entriesPerPage> int </entriesPerPage>
    <pageNumber> int </pageNumber>
  </paginationInput>
  <sortOrder> SortOrderType </sortOrder>
  <!-- Call-specific Input Fields -->
  <aspectFilter> AspectFilter 
    <aspectName> string </aspectName>
    <aspectValueName> string </aspectValueName>
    <!-- ... more aspectValueName nodes here ... -->
  </aspectFilter>
  <!-- ... more aspectFilter nodes here ... -->
  <domainFilter> DomainFilter 
    <domainName> string </domainName>
    <!-- ... more domainName nodes here ... -->
  </domainFilter>
  <!-- ... more domainFilter nodes here ... -->
  <itemFilter> ItemFilter 
    <name> ItemFilterType </name>
    <paramName> token </paramName>
    <paramValue> string </paramValue>
    <value> string </value>
    <!-- ... more value nodes here ... -->
  </itemFilter>
  <!-- ... more itemFilter nodes here ... -->
  <keywords> string </keywords>
  <outputSelector> OutputSelectorType </outputSelector>
  <!-- ... more outputSelector nodes here ... -->
</findItemsByKeywordsRequest>

Back to top

The box below lists all fields that might be returned in the response. To learn more about an individual field or its type, click its name in the box (or scroll down to find it in the table below the box).

See also Samples.

<?xml version="1.0" encoding="utf-8"?>
<findItemsByKeywordsResponse xmlns="http://www.ebay.com/marketplace/search/v1/services">
  <!-- Standard Output Fields -->
  <ack> AckValue </ack>
  <errorMessage> ErrorMessage 
    <error> ErrorData 
      <category> ErrorCategory </category>
      <domain> string </domain>
      <errorId> long </errorId>
      <exceptionId> token </exceptionId>
      <message> string </message>
      <parameter name="string"> ErrorParameter (string) </parameter>
      <!-- ... more parameter nodes here ... -->
      <severity> ErrorSeverity </severity>
      <subdomain> string </subdomain>
    </error>
    <!-- ... more error nodes here ... -->
  </errorMessage>
  <paginationOutput> PaginationOutput 
    <entriesPerPage> int </entriesPerPage>
    <pageNumber> int </pageNumber>
    <totalEntries> int </totalEntries>
    <totalPages> int </totalPages>
  </paginationOutput>
  <searchResult count="int"> SearchResult 
    <item> SearchItem 
      <autoPay> boolean </autoPay>
      <charityId> string </charityId>
      <compatibility> string </compatibility>
      <country> token </country>
      <distance unit="string"> Distance (double) </distance>
      <galleryPlusPictureURL> anyURI </galleryPlusPictureURL>
      <!-- ... more galleryPlusPictureURL nodes here ... -->
      <galleryURL> anyURI </galleryURL>
      <globalId> token </globalId>
      <itemId> string </itemId>
      <listingInfo> ListingInfo 
        <bestOfferEnabled> boolean </bestOfferEnabled>
        <buyItNowAvailable> boolean </buyItNowAvailable>
        <buyItNowPrice currencyId="string"> Amount (double) </buyItNowPrice>
        <convertedBuyItNowPrice currencyId="string"> Amount (double) </convertedBuyItNowPrice>
        <endTime> dateTime </endTime>
        <gift> boolean </gift>
        <listingType> token </listingType>
        <startTime> dateTime </startTime>
      </listingInfo>
      <location> string </location>
      <paymentMethod> token </paymentMethod>
      <!-- ... more paymentMethod nodes here ... -->
      <postalCode> string </postalCode>
      <primaryCategory> Category 
        <categoryId> string </categoryId>
        <categoryName> string </categoryName>
      </primaryCategory>
      <productId> ProductId (string) </productId>
      <secondaryCategory> Category 
        <categoryId> string </categoryId>
        <categoryName> string </categoryName>
      </secondaryCategory>
      <sellerInfo> SellerInfo 
        <feedbackRatingStar> token </feedbackRatingStar>
        <feedbackScore> long </feedbackScore>
        <positiveFeedbackPercent> double </positiveFeedbackPercent>
        <sellerUserName> string </sellerUserName>
        <topRatedSeller> boolean </topRatedSeller>
      </sellerInfo>
      <sellingStatus> SellingStatus 
        <bidCount> int </bidCount>
        <convertedCurrentPrice currencyId="string"> Amount (double) </convertedCurrentPrice>
        <currentPrice currencyId="string"> Amount (double) </currentPrice>
        <sellingState> token </sellingState>
        <timeLeft> duration </timeLeft>
      </sellingStatus>
      <shippingInfo> ShippingInfo 
        <shippingServiceCost currencyId="string"> Amount (double) </shippingServiceCost>
        <shippingType> token </shippingType>
        <shipToLocations> string </shipToLocations>
        <!-- ... more shipToLocations nodes here ... -->
      </shippingInfo>
      <storeInfo> Storefront 
        <storeName> string </storeName>
        <storeURL> anyURI </storeURL>
      </storeInfo>
      <subtitle> string </subtitle>
      <title> string </title>
      <viewItemURL> anyURI </viewItemURL>
    </item>
    <!-- ... more item nodes here ... -->
  </searchResult>
  <timestamp> dateTime </timestamp>
  <version> string </version>
  <!-- Call-specific Output Fields -->
  <aspectHistogramContainer> AspectHistogramContainer 
    <aspect name="string"> Aspect 
      <valueHistogram valueName="string"> AspectValueHistogram 
        <count> long </count>
      </valueHistogram>
      <!-- ... more valueHistogram nodes here ... -->
    </aspect>
    <!-- ... more aspect nodes here ... -->
    <domainDisplayName> token </domainDisplayName>
    <domainName> string </domainName>
  </aspectHistogramContainer>
  <categoryHistogramContainer> CategoryHistogramContainer 
    <categoryHistogram> CategoryHistogram 
      <categoryId> string </categoryId>
      <categoryName> string </categoryName>
      <childCategoryHistogram> CategoryHistogram 
        <categoryId> string </categoryId>
        <categoryName> string </categoryName>
        <count> long </count>
      </childCategoryHistogram>
      <!-- ... more childCategoryHistogram nodes here ... -->
      <count> long </count>
    </categoryHistogram>
    <!-- ... more categoryHistogram nodes here ... -->
  </categoryHistogramContainer>
</findItemsByKeywordsResponse>

aspectHistogramContainer	AspectHistogramContainer	Conditionally	Response container for aspect histograms. outputSelector: AspectHistogram
aspectHistogramContainer   .aspect	Aspect	Conditionally, repeatable: [1..*]	A characteristic of an item in a domain. For example, "Optical Zoom", "Brand", and "Megapixels" could be aspects of the Digital Cameras domain. Aspects are well-known, standardized characteristics of a domain, and they vary from domain to domain (the aspects of "Men's Shoes" are different from those of "Digital Cameras"). A search request on the eBay site will often display aspects and their respective aspect values on the left-had side of a query response. Aspects are extracted from item listing properties (such as item titles and subtitles), and represent the characteristics of active items. Values returned in the Aspect container can be used as inputs to the aspectFilter fields in a query to distill the items returned by the query. eBay generates aspects dynamically from the items currently listed; aspects provide a view into what is currently available on eBay. Because of this, aspect values returned one day cannot be guaranteed to be valid the next day. The following graphic shows how eBay might return a set of aspects for the Digital Cameras domain. In this graphic, "Product Type", "Brand", and "Megapixels" are aspects, and "Point & Shoot", "Canon", and "12.0 to 12.9 MP" are aspect values. Histogram values (item counts) are shown for each aspect value. outputSelector: AspectHistogram
aspectHistogramContainer   .aspect   [ attribute name ]	string	Conditionally	Name of an aspect that is part of a domain. For example, "Optical Zoom" or "Megapixels" could be aspects of the Digital Cameras domain. For the current aspect names associated with a specific item, refer to the aspectHistogramContainer returned for the respective item. This value is not returned if there are no matching aspects for the associated domain.
aspectHistogramContainer   .aspect.valueHistogram	AspectValueHistogram	Conditionally, repeatable: [0..*]	Container that returns the name of the respective aspect value and the histogram (the number of available items) that share that item characteristic. This value is not returned if there are no matching aspects for the associated domain. outputSelector: AspectHistogram
aspectHistogramContainer   .aspect.valueHistogram   [ attribute valueName ]	string	Conditionally	Name of an aspect value. For example, "Short Sleeve" could be an aspect value of the Sleeve Style aspect in the Women's Dresses domain, or "Athletic" could be an aspect value of the Style aspect in the Men's Shoes domain.
aspectHistogramContainer   .aspect.valueHistogram.count	long	Conditionally	Number of items that share the characteristic the respective aspect value. outputSelector: AspectHistogram
aspectHistogramContainer   .domainDisplayName	token	Conditionally	A buy-side group of items, for example "Shoes." Domains are extracted from item listing properties, such as the title, descriptions, and so on. outputSelector: AspectHistogram
aspectHistogramContainer   .domainName	string	Conditionally	A buy-side group of items that share aspects, but not necessarily an eBay category. For example "Women's Dresses" or "Digital Cameras" could be domains. You can use a domainName to label a set of aspects that you display. Domains are extracted from item listing properties (such as item titles and subtitles). outputSelector: AspectHistogram
categoryHistogramContainer	CategoryHistogramContainer	Conditionally	Response container for category histograms. Only returned when one or more category histograms are returned. A category histogram is not returned if the search query returns no matching items. Note: When searching the eBay Motors site, category histograms may not be available for some parent categories. In these cases, aspect histograms should be used to refine search results. This behavior is consistent with eBay Motors site search behavior. outputSelector: CategoryHistogram
categoryHistogramContainer   .categoryHistogram	CategoryHistogram	Conditionally, repeatable: [0..*]	Statistical (item count) information on the categories that contain items that match the search criteria or specified category or categories. A category histogram contains information for up to 10 child categories. Search result total entries may not necessarily match the sum of category histogram item counts. For search calls, the item count shows the distribution of matching items across each of the returned categories. A category histogram is not returned if there are no matching items or if the search is restricted to a single leaf category. For getHistograms, the category histogram contains the total item count for the specified category and item counts for the child categories containing the most item listings. A category histogram is not returned if the specified category is a leaf category. For categories associated with specific items, review the individual item containers returned in the search result. outputSelector: CategoryHistogram
categoryHistogramContainer   .categoryHistogram.categoryId	string	Conditionally	The unique ID of a category on the specified eBay site. Max length: 10. outputSelector: CategoryHistogram
categoryHistogramContainer   .categoryHistogram   .categoryName	string	Conditionally	Display name of a category as it appears on the eBay Web site. Max length: 30. outputSelector: CategoryHistogram
categoryHistogramContainer   .categoryHistogram   .childCategoryHistogram	CategoryHistogram	Conditionally, repeatable: [0..10]	Container for histogram information pertaining to a child of the category specified in the request. Histograms return data on up to 10 children. Histograms are only a single level deep. That is, a given category histogram contains only immediate children. outputSelector: CategoryHistogram
categoryHistogramContainer   .categoryHistogram   .childCategoryHistogram   .categoryId	string	Conditionally	The unique ID of a category on the specified eBay site. Max length: 10. outputSelector: CategoryHistogram
categoryHistogramContainer   .categoryHistogram   .childCategoryHistogram   .categoryName	string	Conditionally	Display name of a category as it appears on the eBay Web site. Max length: 30. outputSelector: CategoryHistogram
categoryHistogramContainer   .categoryHistogram   .childCategoryHistogram.count	long	Conditionally	The total number of items in the associated category that match the search criteria. outputSelector: CategoryHistogram
categoryHistogramContainer   .categoryHistogram.count	long	Conditionally	The total number of items in the associated category that match the search criteria. outputSelector: CategoryHistogram

Back to top

The outputSelector input field gives you control over which call-specific output fields may be returned from your queries. outputSelector accepts a set of preset values, each of which permits the return of a different set of fields. (All standard output fields are returned regardless of outputSelector.)

The table below details the fields that each outputSelector value controls. In addition, the table includes a none column that shows the fields that are not controlled by outputSelector settings. Note that some fields are returned only when certain conditions are met; see the associated field description for a clarification of these conditions.

Output Field	none	AspectHistogram	CategoryHistogram	SellerInfo	StoreInfo
ack	Y	-	-	-	-
aspectHistogramContainer	-	(Y)	-	-	-
aspectHistogramContainer.aspect	-	(Y)	-	-	-
aspectHistogramContainer.aspect.valueHistogram	-	(Y)	-	-	-
aspectHistogramContainer.aspect.valueHistogram.count	-	(Y)	-	-	-
aspectHistogramContainer.domainDisplayName	-	(Y)	-	-	-
aspectHistogramContainer.domainName	-	(Y)	-	-	-
categoryHistogramContainer	-	-	(Y)	-	-
categoryHistogramContainer.categoryHistogram	-	-	(Y)	-	-
categoryHistogramContainer.categoryHistogram.categoryId	-	-	(Y)	-	-
categoryHistogramContainer.categoryHistogram.categoryName	-	-	(Y)	-	-
categoryHistogramContainer.categoryHistogram   .childCategoryHistogram	-	-	(Y)	-	-
categoryHistogramContainer.categoryHistogram   .childCategoryHistogram.categoryId	-	-	(Y)	-	-
categoryHistogramContainer.categoryHistogram   .childCategoryHistogram.categoryName	-	-	(Y)	-	-
categoryHistogramContainer.categoryHistogram   .childCategoryHistogram.count	-	-	(Y)	-	-
categoryHistogramContainer.categoryHistogram.count	-	-	(Y)	-	-
errorMessage	(Y)	-	-	-	-
errorMessage.error	(Y)	-	-	-	-
errorMessage.error.category	(Y)	-	-	-	-
errorMessage.error.domain	(Y)	-	-	-	-
errorMessage.error.errorId	(Y)	-	-	-	-
errorMessage.error.exceptionId	(Y)	-	-	-	-
errorMessage.error.message	(Y)	-	-	-	-
errorMessage.error.parameter	(Y)	-	-	-	-
errorMessage.error.severity	(Y)	-	-	-	-
errorMessage.error.subdomain	(Y)	-	-	-	-
paginationOutput	(Y)	-	-	-	-
paginationOutput.entriesPerPage	(Y)	-	-	-	-
paginationOutput.pageNumber	(Y)	-	-	-	-
paginationOutput.totalEntries	(Y)	-	-	-	-
paginationOutput.totalPages	(Y)	-	-	-	-
searchResult	Y	-	-	-	-
searchResult.item	Y	-	-	-	-
searchResult.item.autoPay	Y	-	-	-	-
searchResult.item.charityId	(Y)	-	-	-	-
searchResult.item.compatibility	(Y)	-	-	-	-
searchResult.item.country	(Y)	-	-	-	-
searchResult.item.distance	(Y)	-	-	-	-
searchResult.item.galleryPlusPictureURL	(Y)	-	-	-	-
searchResult.item.galleryURL	(Y)	-	-	-	-
searchResult.item.globalId	Y	-	-	-	-
searchResult.item.itemId	Y	-	-	-	-
searchResult.item.listingInfo	(Y)	-	-	-	-
searchResult.item.listingInfo.bestOfferEnabled	(Y)	-	-	-	-
searchResult.item.listingInfo.buyItNowAvailable	(Y)	-	-	-	-
searchResult.item.listingInfo.buyItNowPrice	(Y)	-	-	-	-
searchResult.item.listingInfo.convertedBuyItNowPrice	(Y)	-	-	-	-
searchResult.item.listingInfo.endTime	(Y)	-	-	-	-
searchResult.item.listingInfo.gift	(Y)	-	-	-	-
searchResult.item.listingInfo.listingType	(Y)	-	-	-	-
searchResult.item.listingInfo.startTime	(Y)	-	-	-	-
searchResult.item.location	(Y)	-	-	-	-
searchResult.item.paymentMethod	(Y)	-	-	-	-
searchResult.item.postalCode	(Y)	-	-	-	-
searchResult.item.primaryCategory	Y	-	-	-	-
searchResult.item.primaryCategory.categoryId	Y	-	-	-	-
searchResult.item.primaryCategory.categoryName	Y	-	-	-	-
searchResult.item.productId	(Y)	-	-	-	-
searchResult.item.secondaryCategory	(Y)	-	-	-	-
searchResult.item.secondaryCategory.categoryId	(Y)	-	-	-	-
searchResult.item.secondaryCategory.categoryName	(Y)	-	-	-	-
searchResult.item.sellerInfo	-	-	-	(Y)	-
searchResult.item.sellerInfo.feedbackRatingStar	-	-	-	(Y)	-
searchResult.item.sellerInfo.feedbackScore	-	-	-	(Y)	-
searchResult.item.sellerInfo.positiveFeedbackPercent	-	-	-	(Y)	-
searchResult.item.sellerInfo.sellerUserName	-	-	-	(Y)	-
searchResult.item.sellerInfo.topRatedSeller	-	-	-	(Y)	-
searchResult.item.sellingStatus	(Y)	-	-	-	-
searchResult.item.sellingStatus.bidCount	(Y)	-	-	-	-
searchResult.item.sellingStatus.convertedCurrentPrice	(Y)	-	-	-	-
searchResult.item.sellingStatus.currentPrice	(Y)	-	-	-	-
searchResult.item.sellingStatus.sellingState	(Y)	-	-	-	-
searchResult.item.sellingStatus.timeLeft	(Y)	-	-	-	-
searchResult.item.shippingInfo	(Y)	-	-	-	-
searchResult.item.shippingInfo.shippingServiceCost	(Y)	-	-	-	-
searchResult.item.shippingInfo.shippingType	(Y)	-	-	-	-
searchResult.item.shippingInfo.shipToLocations	(Y)	-	-	-	-
searchResult.item.storeInfo	-	-	-	-	(Y)
searchResult.item.storeInfo.storeName	-	-	-	-	(Y)
searchResult.item.storeInfo.storeURL	-	-	-	-	(Y)
searchResult.item.subtitle	(Y)	-	-	-	-
searchResult.item.title	(Y)	-	-	-	-
searchResult.item.viewItemURL	(Y)	-	-	-	-
timestamp	Y	-	-	-	-
version	Y	-	-	-	-

Back to top

New to making API calls? Please see Making an API Call.

Note: Some item IDs, user IDs, or other data in these samples might no longer be active on eBay. If necessary, you can substitute current eBay data in your requests.

Available samples:

• Basic Call ↓ - Retrieves a set of items based on the keywords you provide.
• MaxPrice Item Filter ↓ - Retrieves a set of items based on the keywords you provide and a price filter.
• Filter by Price and Free Shipping ↓ - Retrieves a set of items with free shipping based on the keywords you provide and a price filter.
• Proximity Search ↓ - Retrieves a set of items based on the keywords you provide. Only items located within the specified distance from a supplied postal code are returned.
• Reviewing Seller Information, Items Sorted by Distance ↓ - Sort the responses by the distance from the buyer, as determined by the buyer's postal code.
• Specifying Affiliate Information ↓ - This sample specifies affiliate information and sorts the response according to the end time of the auction.

Retrieves a set of items based on the keywords you provide.

Description

The user is looking for a specific Harry Potter title.

Input

The keywords field specifies keywords for which items are returned. Multiple keywords are separated by spaces, which are coded as %20 in URL requests.

Note: URL samples have been wrapped for readability. To run the samples, undo the line wrapping and insert your own SECURITY-APPNAME.

URL format (HTTP GET). See also the non-wrapped version of this URL. For results in a format other than XML, 
specify a different value for responseencoding.

http://svcs.ebay.com/services/search/FindingService/v1?OPERATION-NAME=findItemsByKeywords
   &SERVICE-VERSION=1.0.0
   &SECURITY-APPNAME=YourAppID
   &RESPONSE-DATA-FORMAT=XML
   &REST-PAYLOAD
   &keywords=harry%20potter%20phoenix
   &paginationInput.entriesPerPage=2

   Here is the same input in XML format (HTTP POST). Note that this does not include standard values.

XML format (HTTP POST). Also available is the .txt version of this XML.

<?xml version="1.0" encoding="UTF-8"?>
<findItemsByKeywordsRequest xmlns="http://www.ebay.com/marketplace/search/v1/services">
  <keywords>harry potter phoenix</keywords>
  <paginationInput>
    <entriesPerPage>2</entriesPerPage>
  </paginationInput>
</findItemsByKeywordsRequest>

Output

XML format. Also available are the .txt version of this XML.

<?xml version="1.0" encoding="UTF-8"?>
<findItemsByKeywordsResponse xmlns:ms="http://www.ebay.com/marketplace/services"
xmlns="http://www.ebay.com/marketplace/search/v1/services">
   <ack>Success</ack>
   <version>1.0.0</version>
   <timestamp>2009-09-04T00:46:55.581Z</timestamp>
   <searchResult count="2">
      <item>
         <itemId>140343270924</itemId>
         <title>NINTENDO WII GAME HARRY POTTER ORDER OF THE PHOENIX NEW</title>
         <globalId>EBAY-US</globalId>
         <subtitle>??FAST SECURE SHIPPING SEE OUR STORE 100,000+ GAMES??</subtitle>
         <primaryCategory>
            <categoryId>139973</categoryId>
            <categoryName>Games</categoryName>
         </primaryCategory>
         <galleryURL>
         http://thumbs1.ebaystatic.com/pict/1403432709248080_1.jpg</galleryURL>
         <viewItemURL>http://cgi.ebay.com/NINTENDO-WII-GAME-HARRY-POTTER-ORDER-OF-THE-
         PHOENIX-NEW_W0QQitemZ140343270924QQcmdZViewItemQQptZVideo_Games_Games?hash=
         item20ad1c5e0c</viewItemURL>
         <productId type="ReferenceID">56277256</productId>
         <paymentMethod>PayPal</paymentMethod>
         <paymentMethod>VisaMC</paymentMethod>
         <paymentMethod>Discover</paymentMethod>
         <autoPay>false</autoPay>
         <postalCode>42266</postalCode>
         <location>Pembroke,KY,USA</location>
         <country>US</country>
         <shippingInfo>
            <shippingServiceCost currencyId="USD">0.0</shippingServiceCost>
            <shippingType>Free</shippingType>
            <shipToLocations>Worldwide</shipToLocations>
         </shippingInfo>
         <sellingStatus>
            <currentPrice currencyId="USD">30.99</currentPrice>
            <convertedCurrentPrice currencyId="USD">30.99</convertedCurrentPrice>
            <bidCount>0</bidCount>
            <sellingState>Active</sellingState>
            <timeLeft>P0DT5H35M49S</timeLeft>
         </sellingStatus>
         <listingInfo>
            <bestOfferEnabled>false</bestOfferEnabled>
            <buyItNowAvailable>true</buyItNowAvailable>
            <buyItNowPrice currencyId="USD">33.94</buyItNowPrice>
            <convertedBuyItNowPrice currencyId="USD">33.94</convertedBuyItNowPrice>
            <startTime>2009-09-01T06:22:44.000Z</startTime>
            <endTime>2009-09-04T06:22:44.000Z</endTime>
            <listingType>AuctionWithBIN</listingType>
            <gift>false</gift>
         </listingInfo>
      </item>
      <item>
         <itemId>230371938681</itemId>
         <title>Harry Potter and the Order of the Phoenix HD-DVD</title>
         <globalId>EBAY-US</globalId>
         <primaryCategory>
            <categoryId>617</categoryId>
            <categoryName>DVD, HD DVD & Blu-ray</categoryName>
         </primaryCategory>
         <galleryURL>
         http://thumbs1.ebaystatic.com/pict/2303719386818080_1.jpg</galleryURL>
         <viewItemURL>http://cgi.ebay.com/Harry-Potter-and-the-Order-of-the-Phoenix-HD-
         DVD_W0QQitemZ230371938681QQcmdZViewItemQQptZUS_DVD_HD_DVD_Blu_ray?hash=
         item35a33cd179</viewItemURL>
         <productId type="ReferenceID">62929195</productId>
         <paymentMethod>PayPal</paymentMethod>
         <autoPay>false</autoPay>
         <postalCode>21702</postalCode>
         <location>Frederick,MD,USA</location>
         <country>US</country>
         <shippingInfo>
            <shippingType>Calculated</shippingType>
            <shipToLocations>US</shipToLocations>
         </shippingInfo>
         <sellingStatus>
            <currentPrice currencyId="USD">2.5</currentPrice>
            <convertedCurrentPrice currencyId="USD">2.5</convertedCurrentPrice>
            <bidCount>8</bidCount>
            <sellingState>Active</sellingState>
            <timeLeft>P0DT0H1M28S</timeLeft>
         </sellingStatus>
         <listingInfo>
            <bestOfferEnabled>false</bestOfferEnabled>
            <buyItNowAvailable>false</buyItNowAvailable>
            <startTime>2009-08-28T00:48:23.000Z</startTime>
            <endTime>2009-09-04T00:48:23.000Z</endTime>
            <listingType>Auction</listingType>
            <gift>false</gift>
         </listingInfo>
      </item>
   </searchResult>
   <paginationOutput>
      <totalPages>433</totalPages>
      <totalEntries>866</totalEntries>
      <pageNumber>1</pageNumber>
      <entriesPerPage>2</entriesPerPage>
   </paginationOutput>
</findItemsByKeywordsResponse>

Back to list of samples

Retrieves a set of items based on the keywords you provide and a price filter.

Description

The user is looking for a specific Harry Potter title and has a maximum price ceiling.

Input

To specify a MaxPrice item filter, you set itemFilter.name to MaxPrice and itemFilter.value to the maximum price, $10.00. The user uses itemFilter.paramName and

and itemFilter.paramValue to specify the currency for the filter, US dollars, in this case.

Note: URL samples have been wrapped for readability. To run the samples, undo the line wrapping and insert your own SECURITY-APPNAME.

URL format (HTTP GET). See also the non-wrapped version of this URL. For results in a format other than XML, 
specify a different value for responseencoding.

http://svcs.ebay.com/services/search/FindingService/v1?OPERATION-NAME=findItemsByKeywords
   &SERVICE-VERSION=1.0.0
   &SECURITY-APPNAME=YourAppID
   &RESPONSE-DATA-FORMAT=XML
   &REST-PAYLOAD
   &keywords=harry%20potter%20phoenix
   &itemFilter.name=MaxPrice
   &itemFilter.value=10.00
   &itemFilter.paramName=Currency
   &itemFilter.paramValue=USD
   &paginationInput.entriesPerPage=2

   Here is the same input in XML format (HTTP POST). Note that this does not include standard values.

XML format (HTTP POST). Also available is the .txt version of this XML.

<?xml version="1.0" encoding="UTF-8"?>
<findItemsByKeywordsRequest xmlns="http://www.ebay.com/marketplace/search/v1/services">
  <keywords>harry potter phoenix</keywords>
  <itemFilter>
    <name>MaxPrice</name>
    <value>10.00</value>
    <paramName>Currency</paramName>
    <paramValue>USD</paramValue>
  </itemFilter>
  <paginationInput>
    <entriesPerPage>2</entriesPerPage>
  </paginationInput>
</findItemsByKeywordsRequest>

Output

The response contains matching items with a current price of $10 or less.

XML format. Also available is the .txt version of this XML.

<?xml version="1.0" encoding="UTF-8"?>
<findItemsByKeywordsResponse xmlns:ms="http://www.ebay.com/marketplace/services"
xmlns="http://www.ebay.com/marketplace/search/v1/services">
   <ack>Success</ack>
   <version>1.0.0</version>
   <timestamp>2009-09-04T00:47:12.456Z</timestamp>
   <searchResult count="2">
      <item>
         <itemId>230371938681</itemId>
         <title>Harry Potter and the Order of the Phoenix HD-DVD</title>
         <globalId>EBAY-US</globalId>
         <primaryCategory>
            <categoryId>617</categoryId>
            <categoryName>DVD, HD DVD & Blu-ray</categoryName>
         </primaryCategory>
         <galleryURL>
         http://thumbs1.ebaystatic.com/pict/2303719386818080_1.jpg</galleryURL>
         <viewItemURL>http://cgi.ebay.com/Harry-Potter-and-the-Order-of-the-Phoenix-HD-
         DVD_W0QQitemZ230371938681QQcmdZViewItemQQptZUS_DVD_HD_DVD_Blu_ray?hash=
         item35a33cd179</viewItemURL>
         <productId type="ReferenceID">62929195</productId>
         <paymentMethod>PayPal</paymentMethod>
         <autoPay>false</autoPay>
         <postalCode>21702</postalCode>
         <location>Frederick,MD,USA</location>
         <country>US</country>
         <shippingInfo>
            <shippingType>Calculated</shippingType>
            <shipToLocations>US</shipToLocations>
         </shippingInfo>
         <sellingStatus>
            <currentPrice currencyId="USD">2.5</currentPrice>
            <convertedCurrentPrice currencyId="USD">2.5</convertedCurrentPrice>
            <bidCount>8</bidCount>
            <sellingState>Active</sellingState>
            <timeLeft>P0DT0H1M11S</timeLeft>
         </sellingStatus>
         <listingInfo>
            <bestOfferEnabled>false</bestOfferEnabled>
            <buyItNowAvailable>false</buyItNowAvailable>
            <startTime>2009-08-28T00:48:23.000Z</startTime>
            <endTime>2009-09-04T00:48:23.000Z</endTime>
            <listingType>Auction</listingType>
            <gift>false</gift>
         </listingInfo>
      </item>
      <item>
         <itemId>140342419442</itemId>
         <title>*HARRY POTTER* 'Order Of The Phoenix' Adjustable Cap!</title>
         <globalId>EBAY-US</globalId>
         <primaryCategory>
            <categoryId>29798</categoryId>
            <categoryName>Other</categoryName>
         </primaryCategory>
         <galleryURL>
         http://thumbs3.ebaystatic.com/pict/1403424194428080_1.jpg</galleryURL>
         <viewItemURL>http://cgi.ebay.com/HARRY-POTTER-Order-Of-The-Phoenix-Adjustable-
         Cap_W0QQitemZ140342419442QQcmdZViewItemQQptZLH_DefaultDomain_0?hash=
         item20ad0f5ff2</viewItemURL>
         <paymentMethod>PayPal</paymentMethod>
         <autoPay>false</autoPay>
         <postalCode>45623</postalCode>
         <location>Crown City,OH,USA</location>
         <country>US</country>
         <shippingInfo>
            <shippingServiceCost currencyId="USD">4.19</shippingServiceCost>
            <shippingType>Flat</shippingType>
            <shipToLocations>US</shipToLocations>
         </shippingInfo>
         <sellingStatus>
            <currentPrice currencyId="USD">1.99</currentPrice>
            <convertedCurrentPrice currencyId="USD">1.99</convertedCurrentPrice>
            <bidCount>0</bidCount>
            <sellingState>Active</sellingState>
            <timeLeft>P0DT0H54M50S</timeLeft>
         </sellingStatus>
         <listingInfo>
            <bestOfferEnabled>false</bestOfferEnabled>
            <buyItNowAvailable>false</buyItNowAvailable>
            <startTime>2009-08-28T01:42:02.000Z</startTime>
            <endTime>2009-09-04T01:42:02.000Z</endTime>
            <listingType>Auction</listingType>
            <gift>false</gift>
         </listingInfo>
      </item>
   </searchResult>
   <paginationOutput>
      <totalPages>212</totalPages>
      <totalEntries>424</totalEntries>
      <pageNumber>1</pageNumber>
      <entriesPerPage>2</entriesPerPage>
   </paginationOutput>
</findItemsByKeywordsResponse>

Back to list of samples

Retrieves a set of items with free shipping based on the keywords you provide and a price filter.

Description

The user is looking for a specific Harry Potter title and has a maximum price ceiling and doesn't want to pay for shipping, either.

Input

When you specify multiple item filters in a name-value request, you must index each item filter, starting with "0."

Note: URL samples have been wrapped for readability. To run the samples, undo the line wrapping and insert your own SECURITY-APPNAME.

URL format (HTTP GET). See also the non-wrapped version of this URL. For results in a format other than XML, 
specify a different value for responseencoding.

http://svcs.ebay.com/services/search/FindingService/v1?OPERATION-NAME=findItemsByKeywords
   &SERVICE-VERSION=1.0.0
   &SECURITY-APPNAME=YourAppID
   &RESPONSE-DATA-FORMAT=XML
   &REST-PAYLOAD
   &keywords=harry%20potter%20phoenix
   &itemFilter(0).name=MaxPrice
   &itemFilter(0).value=10.00
   &itemFilter(0).paramName=Currency
   &itemFilter(0).paramValue=USD
   &itemFilter(1).name=FreeShippingOnly
   &itemFilter(1).value=true
   &paginationInput.entriesPerPage=2

   Here is the same input in XML format (HTTP POST). Note that this does not include standard values.

XML format (HTTP POST). Also available is the .txt version of this XML.

<?xml version="1.0" encoding="UTF-8"?>
<findItemsByKeywordsRequest xmlns="http://www.ebay.com/marketplace/search/v1/services">
  <keywords>harry potter phoenix</keywords>
  <itemFilter>
    <name>MaxPrice</name>
    <value>10.00</value>
    <paramName>Currency</paramName>
    <paramValue>USD</paramValue>
  </itemFilter>
  <itemFilter>
    <name>FreeShippingOnly</name>
    <value>true</value>
  </itemFilter>
  <paginationInput>
    <entriesPerPage>2</entriesPerPage>
  </paginationInput>
</findItemsByKeywordsRequest>

Output

The response contains matching items with a current price of $10 or less, and no shipping charges.

XML format. Also available is the .txt version of this XML.

<?xml version="1.0" encoding="UTF-8"?>
<findItemsByKeywordsResponse xmlns:ms="http://www.ebay.com/marketplace/services"
xmlns="http://www.ebay.com/marketplace/search/v1/services">
   <ack>Success</ack>
   <version>1.0.0</version>
   <timestamp>2009-09-04T18:40:34.579Z</timestamp>
   <searchResult count="2">
      <item>
         <itemId>350241298435</itemId>
         <title>Harry Potter and the Order of the Phoenix DVD NEW</title>
         <globalId>EBAY-US</globalId>
         <subtitle>Authentic Guaranteed Free Shipping Buy 10 Get 1 Free</subtitle>
         <primaryCategory>
            <categoryId>617</categoryId>
            <categoryName>DVD, HD DVD & Blu-ray</categoryName>
         </primaryCategory>
         <galleryURL>
         http://thumbs2.ebaystatic.com/pict/3502412984358080_1.jpg</galleryURL>
         <viewItemURL>http://cgi.ebay.com/Harry-Potter-and-the-Order-of-the-Phoenix-DVD-
         NEW_W0QQitemZ350241298435QQcmdZViewItemQQptZUS_DVD_HD_DVD_Blu_ray?hash=
         item518c021803</viewItemURL>
         <productId type="ReferenceID">62940319</productId>
         <paymentMethod>PayPal</paymentMethod>
         <autoPay>false</autoPay>
         <location>China</location>
         <country>CN</country>
         <shippingInfo>
            <shippingServiceCost currencyId="USD">0.0</shippingServiceCost>
            <shippingType>Free</shippingType>
            <shipToLocations>Worldwide</shipToLocations>
         </shippingInfo>
         <sellingStatus>
            <currentPrice currencyId="USD">7.99</currentPrice>
            <convertedCurrentPrice currencyId="USD">7.99</convertedCurrentPrice>
            <sellingState>Active</sellingState>
            <timeLeft>P12DT0H33M48S</timeLeft>
         </sellingStatus>
         <listingInfo>
            <bestOfferEnabled>false</bestOfferEnabled>
            <buyItNowAvailable>false</buyItNowAvailable>
            <startTime>2009-08-17T19:14:22.000Z</startTime>
            <endTime>2009-09-16T19:14:22.000Z</endTime>
            <listingType>FixedPrice</listingType>
            <gift>false</gift>
         </listingInfo>
      </item>
      <item>
         <itemId>170377305715</itemId>
         <title>Harry Potter and the Order of the Phoenix (Wii)</title>
         <globalId>EBAY-US</globalId>
         <subtitle>Great Graphics, Action Packed, Follows Movie</subtitle>
         <primaryCategory>
            <categoryId>139973</categoryId>
            <categoryName>Games</categoryName>
         </primaryCategory>
         <galleryURL>
         http://thumbs2.ebaystatic.com/pict/1703773057158080_1.jpg</galleryURL>
         <viewItemURL>http://cgi.ebay.com/Harry-Potter-and-the-Order-of-the-Phoenix-
         Wii_W0QQitemZ170377305715QQcmdZViewItemQQptZVideo_Games_Games?hash=
         item27ab475e73</viewItemURL>
         <productId type="ReferenceID">56277256</productId>
         <paymentMethod>PayPal</paymentMethod>
         <autoPay>false</autoPay>
         <postalCode>36695</postalCode>
         <location>Mobile,AL,USA</location>
         <country>US</country>
         <shippingInfo>
            <shippingServiceCost currencyId="USD">0.0</shippingServiceCost>
            <shippingType>Free</shippingType>
            <shipToLocations>US</shipToLocations>
         </shippingInfo>
         <sellingStatus>
            <currentPrice currencyId="USD">9.99</currentPrice>
            <convertedCurrentPrice currencyId="USD">9.99</convertedCurrentPrice>
            <bidCount>1</bidCount>
            <sellingState>Active</sellingState>
            <timeLeft>P1DT3H21M56S</timeLeft>
         </sellingStatus>
         <listingInfo>
            <bestOfferEnabled>false</bestOfferEnabled>
            <buyItNowAvailable>false</buyItNowAvailable>
            <startTime>2009-08-29T22:02:30.000Z</startTime>
            <endTime>2009-09-05T22:02:30.000Z</endTime>
            <listingType>Auction</listingType>
            <gift>false</gift>
         </listingInfo>
      </item>
   </searchResult>
   <paginationOutput>
      <totalPages>26</totalPages>
      <totalEntries>52</totalEntries>
      <pageNumber>1</pageNumber>
      <entriesPerPage>2</entriesPerPage>
   </paginationOutput>
</findItemsByKeywordsResponse>

Back to list of samples

Retrieves a set of items based on the keywords you provide. Only items located within the specified distance from a supplied postal code are returned.

Description

The user is looking for a specific item and wants to see what items are local to their location.

Input

Supply a postal code in the buyerPostalCode field and specify the maximum distance to search for items in the item filter Distance field. eBay returns only those items that are found within the specified distance from the supplied postal code. The distance will be calculated in the units that are local to the specified postal code (kilometers or miles).This type of search is called a "proximity" search.

Note: URL samples have been wrapped for readability. To run the samples, undo the line wrapping and insert your own SECURITY-APPNAME.

URL format (HTTP GET). See also the non-wrapped version of this URL. For results in a format other than XML, 
specify a different value for responseencoding.

http://svcs.ebay.com/services/search/FindingService/v1?OPERATION-NAME=findItemsByKeywords
   &SERVICE-VERSION=1.0.0
   &GLOBAL-ID=EBAY-US
   &SECURITY-APPNAME=YourAppID
   &RESPONSE-DATA-FORMAT=XML
   &REST-PAYLOAD=TRUE
   &keywords=bagpipes
   &buyerPostalCode=95125
   &itemFilter.name=MaxDistance
   &itemFilter.value=25

   Here is the same input in XML format (HTTP POST). Note that this does not include standard values.

XML format (HTTP POST). Also available is the .txt version of this XML.

<?xml version="1.0" encoding="UTF-8"?>
<findItemsByKeywordsRequest xmlns="http://www.ebay.com/marketplace/search/v1/services">
  <keywords>bagpipes</keywords>
  <buyerPostalCode>95125</buyerPostalCode>
  <itemFilter>
    <name>MaxDistance</name>
    <value>25</value>
  </itemFilter>
</findItemsByKeywordsRequest>

Output

XML format. Also available are the .txt version of this XML.

<?xml version="1.0" encoding="utf-8"?>
<findItemsByKeywordsResponse xmlns:ms="http://www.ebay.com/marketplace/services"
xmlns="http://www.ebay.com/marketplace/search/v1/services">
   <ack>Success</ack>
   <version>1.0.0</version>
   <timestamp>2009-09-10T18:15:23.966Z</timestamp>
   <searchResult count="1">
      <item>
         <itemId>250496290774</itemId>
         <title>1950 union pacific railroad ad scottish play BAGPIPE</title>
         <globalId>EBAY-US</globalId>
         <primaryCategory>
            <categoryId>35</categoryId>
            <categoryName>Other</categoryName>
         </primaryCategory>
         <galleryURL>
         http://thumbs2.ebaystatic.com/pict/2504962907748080_1.jpg</galleryURL>
         <viewItemURL>http://cgi.ebay.com/1950-union-pacific-railroad-ad-scottish-play-
         BAGPIPE_W0QQitemZ250496290774QQcmdZViewItemQQptZLH_DefaultDomain_0?hash=
         item3a52be0fd6</viewItemURL>
         <paymentMethod>PayPal</paymentMethod>
         <autoPay>false</autoPay>
         <postalCode>95125</postalCode>
         <location>San Jose,CA,USA</location>
         <country>US</country>
         <shippingInfo>
            <shippingServiceCost currencyId="USD">6.7</shippingServiceCost>
            <shippingType>Flat</shippingType>
            <shipToLocations>Worldwide</shipToLocations>
         </shippingInfo>
         <sellingStatus>
            <currentPrice currencyId="USD">9.99</currentPrice>
            <convertedCurrentPrice currencyId="USD">9.99</convertedCurrentPrice>
            <bidCount>0</bidCount>
            <sellingState>Active</sellingState>
            <timeLeft>P2DT11H37M29S</timeLeft>
         </sellingStatus>
         <listingInfo>
            <bestOfferEnabled>false</bestOfferEnabled>
            <buyItNowAvailable>true</buyItNowAvailable>
            <buyItNowPrice currencyId="USD">15.0</buyItNowPrice>
            <convertedBuyItNowPrice currencyId="USD">15.0</convertedBuyItNowPrice>
            <startTime>2009-09-10T05:52:52.000Z</startTime>
            <endTime>2009-09-13T05:52:52.000Z</endTime>
            <listingType>AuctionWithBIN</listingType>
            <gift>false</gift>
         </listingInfo>
         <distance unit="mi">5.0</distance>
      </item>
   </searchResult>
   <paginationOutput>
      <totalPages>1</totalPages>
      <totalEntries>1</totalEntries>
      <pageNumber>1</pageNumber>
      <entriesPerPage>100</entriesPerPage>
   </paginationOutput>
</findItemsByKeywordsResponse>

Back to list of samples

Sort the responses by the distance from the buyer, as determined by the buyer's postal code.

Description

Using the buyers postal code, eBay sorts the responses by the items closest to the buyer. The query uses an outputSelector to include seller information in the response. In addition, both a minimum and a maximum price are specified, so the results return only the items that fall within the set price range.

Input

Query for "Pre-CBS" within a specified price range. The response includes seller information and items are sorted by distance, with the closest to the seller listed first.

URL format (HTTP GET). See also the non-wrapped version of this URL. For results in a format other than XML, 
specify a different value for responseencoding.

http://svcs.ebay.com/services/search/FindingService/v1?OPERATION-NAME=findItemsByKeywords
   &SERVICE-VERSION=1.0.0
   &SECURITY-APPNAME=YourAppID
   &RESPONSE-DATA-FORMAT=XML
   &REST-PAYLOAD
   &buyerPostalCode=95060
   &sortOrder=Distance
   &outputSelector=SellerInfo
   &itemFilter(0).name=MaxPrice
   &itemFilter(0).value=2500.00
   &itemFilter(0).paramName=Currency
   &itemFilter(0).paramValue=USD
   &itemFilter(1).name=MinPrice
   &itemFilter(1).value=2000.00
   &itemFilter(1).paramName=Currency
   &itemFilter(1).paramValue=USD
   &keywords=%22pre-CBS%22

   Here is the same input in XML format (HTTP POST). Note that this does not include standard values.

XML format (HTTP POST). Also available is the .txt version of this XML.

<?xml version="1.0" encoding="UTF-8"?>
<findItemsByKeywordsRequest xmlns="http://www.ebay.com/marketplace/search/v1/services">
  <keywords>pre-CBS</keywords>
  <buyerPostalCode>95060</buyerPostalCode>
  <sortOrder>Distance</sortOrder>
  <outputSelector>SellerInfo</outputSelector>
  <itemFilter>
    <name>MaxPrice</name>
    <value>2500.00</value>
    <paramName>Currency</paramName>
    <paramValue>USD</paramValue>
  </itemFilter>
  <itemFilter>
    <name>MinPrice</name>
    <value>1000.00</value>
    <paramName>Currency</paramName>
    <paramValue>USD</paramValue>
  </itemFilter>
</findItemsByKeywordsRequest>

Output

XML format. Also available is the .txt version of this XML.

<findItemsAdvancedResponse xmlns:ms="http://www.ebay.com/marketplace/services"
xmlns="http://www.ebay.com/marketplace/search/v1/services">
   <ack>Success</ack>
   <version>1.1.0</version>
   <timestamp>2009-12-05T00:05:48.118Z</timestamp>
   <searchResult count="3">
      <item>
         <itemId>220521054527</itemId>
         <title>Fender Bassman Head and 2x12 Cabinet 1964 AA864 Pre-CBS</title>
         <globalId>EBAY-US</globalId>
         <subtitle>Super Clean! New Tubes, custom J&L Covers ROCK MACHINE!</subtitle>
         <primaryCategory>
            <categoryId>10171</categoryId>
            <categoryName>Electric</categoryName>
         </primaryCategory>
         <galleryURL>
         http://thumbs4.ebaystatic.com/pict/2205210545278080_1.jpg</galleryURL>
         <viewItemURL>http://cgi.ebay.com/Fender-Bassman-Head-and-2x12-Cabinet-1964-AA864-
         Pre-CBS_W0QQitemZ220521054527QQcmdZViewItemQQptZLH_DefaultDomain_0?hash=
         item335814413f</viewItemURL>
         <paymentMethod>PayPal</paymentMethod>
         <autoPay>false</autoPay>
         <postalCode>67211</postalCode>
         <location>Wichita,KS,USA</location>
         <country>US</country>
         <sellerInfo>
            <sellerUserName>wichitaband</sellerUserName>
            <feedbackScore>2965</feedbackScore>
            <positiveFeedbackPercent>100.0</positiveFeedbackPercent>
            <feedbackRatingStar>Red</feedbackRatingStar>
            <topRatedSeller>false</topRatedSeller>
         </sellerInfo>
         <shippingInfo>
            <shippingType>Calculated</shippingType>
            <shipToLocations>Worldwide</shipToLocations>
         </shippingInfo>
         <sellingStatus>
            <currentPrice currencyId="USD">1399.0</currentPrice>
            <convertedCurrentPrice currencyId="USD">1399.0</convertedCurrentPrice>
            <bidCount>0</bidCount>
            <sellingState>Active</sellingState>
            <timeLeft>P5DT19H1M50S</timeLeft>
         </sellingStatus>
         <listingInfo>
            <bestOfferEnabled>false</bestOfferEnabled>
            <buyItNowAvailable>true</buyItNowAvailable>
            <buyItNowPrice currencyId="USD">1599.0</buyItNowPrice>
            <convertedBuyItNowPrice currencyId="USD">1599.0</convertedBuyItNowPrice>
            <startTime>2009-12-03T19:07:38.000Z</startTime>
            <endTime>2009-12-10T19:07:38.000Z</endTime>
            <listingType>AuctionWithBIN</listingType>
            <gift>false</gift>
         </listingInfo>
         <galleryPlusPictureURL>
         http://galleryplus.ebay.com/ws/web/220521054527_1_0_1.jpg</galleryPlusPictureURL>
         <distance unit="mi">1360.0</distance>
      </item>
      <item>
         <itemId>130347910088</itemId>
         <title>Vintage 1964 Pre-CBS Fender Precision Bass Guitar Neck</title>
         <globalId>EBAY-US</globalId>
         <subtitle>ORIGINAL PRE-CBS FENDER NECK. CLAY DOTS!</subtitle>
         <primaryCategory>
            <categoryId>41423</categoryId>
            <categoryName>Necks</categoryName>
         </primaryCategory>
         <galleryURL>
         http://thumbs1.ebaystatic.com/pict/1303479100888080_1.jpg</galleryURL>
         <viewItemURL>http://cgi.ebay.com/Vintage-1964-Pre-CBS-Fender-Precision-Bass-
         Guitar-Neck_W0QQitemZ130347910088QQcmdZViewItemQQptZGuitar_Accessories?hash=
         item1e595743c8</viewItemURL>
         <paymentMethod>PayPal</paymentMethod>
         <paymentMethod>VisaMC</paymentMethod>
         <paymentMethod>AmEx</paymentMethod>
         <paymentMethod>Discover</paymentMethod>
         <autoPay>false</autoPay>
         <postalCode>91403</postalCode>
         <location>Sherman Oaks,CA,USA</location>
         <country>US</country>
         <sellerInfo>
            <sellerUserName>vintage_sales_inc_parts_dept</sellerUserName>
            <feedbackScore>456</feedbackScore>
            <positiveFeedbackPercent>100.0</positiveFeedbackPercent>
            <feedbackRatingStar>Turquoise</feedbackRatingStar>
            <topRatedSeller>true</topRatedSeller>
         </sellerInfo>
         <shippingInfo>
            <shippingServiceCost currencyId="USD">20.0</shippingServiceCost>
            <shippingType>Flat</shippingType>
            <shipToLocations>Worldwide</shipToLocations>
         </shippingInfo>
         <sellingStatus>
            <currentPrice currencyId="USD">1595.0</currentPrice>
            <convertedCurrentPrice currencyId="USD">1595.0</convertedCurrentPrice>
            <sellingState>Active</sellingState>
            <timeLeft>P3DT2H56M48S</timeLeft>
         </sellingStatus>
         <listingInfo>
            <bestOfferEnabled>true</bestOfferEnabled>
            <buyItNowAvailable>false</buyItNowAvailable>
            <startTime>2009-11-28T03:02:36.000Z</startTime>
            <endTime>2009-12-08T03:02:36.000Z</endTime>
            <listingType>FixedPrice</listingType>
            <gift>false</gift>
         </listingInfo>
         <distance unit="mi">285.0</distance>
      </item>
      <item>
         <itemId>230406185397</itemId>
         <title>1960 Pre-CBS FENDER Musicmaster Guitar Slab board Clean</title>
         <globalId>EBAY-US</globalId>
         <primaryCategory>
            <categoryId>118985</categoryId>
            <categoryName>Electric</categoryName>
         </primaryCategory>
         <galleryURL>
         http://thumbs2.ebaystatic.com/pict/2304061853978080_1.jpg</galleryURL>
         <viewItemURL>http://cgi.ebay.com/1960-Pre-CBS-FENDER-Musicmaster-Guitar-Slab-
         board-Clean_W0QQitemZ230406185397QQcmdZViewItemQQptZGuitar?hash=
         item35a54761b5</viewItemURL>
         <paymentMethod>PayPal</paymentMethod>
         <autoPay>false</autoPay>
         <postalCode>44256</postalCode>
         <location>Medina,OH,USA</location>
         <country>US</country>
         <sellerInfo>
            <sellerUserName>axehax</sellerUserName>
            <feedbackScore>1833</feedbackScore>
            <positiveFeedbackPercent>100.0</positiveFeedbackPercent>
            <feedbackRatingStar>Red</feedbackRatingStar>
            <topRatedSeller>true</topRatedSeller>
         </sellerInfo>
         <shippingInfo>
            <shippingServiceCost currencyId="USD">0.0</shippingServiceCost>
            <shippingType>FlatDomesticCalculatedInternational</shippingType>
            <shipToLocations>Worldwide</shipToLocations>
         </shippingInfo>
         <sellingStatus>
            <currentPrice currencyId="USD">1200.0</currentPrice>
            <convertedCurrentPrice currencyId="USD">1200.0</convertedCurrentPrice>
            <sellingState>Active</sellingState>
            <timeLeft>P2DT17H46M23S</timeLeft>
         </sellingStatus>
         <listingInfo>
            <bestOfferEnabled>false</bestOfferEnabled>
            <buyItNowAvailable>false</buyItNowAvailable>
            <startTime>2009-11-30T17:52:11.000Z</startTime>
            <endTime>2009-12-07T17:52:11.000Z</endTime>
            <listingType>FixedPrice</listingType>
            <gift>false</gift>
         </listingInfo>
         <distance unit="mi">2160.0</distance>
      </item>
   </searchResult>
   <paginationOutput>
      <pageNumber>1</pageNumber>
      <entriesPerPage>100</entriesPerPage>
      <totalPages>1</totalPages>
      <totalEntries>3</totalEntries>
   </paginationOutput>
</findItemsAdvancedResponse>

Back to list of samples

This sample specifies affiliate information and sorts the response according to the end time of the auction.

Description

Affiliates earn money from eBay for driving traffic to eBay. For more information, see eBay Partner Network. eBay knows that a sale came from your application because you include your affiliate ID in API calls. Affiliate tracking is enabled for all of the search calls in the Finding API.

Affiliate-related fields enable the tracking of user activity.

Input

The affiliate container has the following fields: networkId, trackingId, and customId.

The networkId specifies the third party who is your tracking partner. This number is 9 if you are registered with eBay Partner Network. The trackingId (a number obtained from your tracking partner) specifies an ID to identify you to your tracking partner. The customId need not be specified, but you can use up to 256 characters to create an ID to better monitor your marketing efforts.

In addition to specifying affiliate information, this sample also specifies the sort order of EndTime, the auctions ending soonest are listed first in the response. By default, items are sorted by BestMatch.

URL format (HTTP GET). See also the non-wrapped version of this URL. For results in a format other than XML, 
specify a different value for responseencoding.

http://svcs.ebay.com/services/search/FindingService/v1?OPERATION-NAME=findItemsByKeywords
   &SERVICE-VERSION=1.0.0
   &SECURITY-APPNAME=YourAppID
   &RESPONSE-DATA-FORMAT=XML
   &REST-PAYLOAD
   &affiliate.networkId=9
   &affiliate.trackingId=1234567890
   &affiliate.customId=k-man
   &sortOrder=EndTime
   &paginationInput.entriesPerPage=2
   &keywords=camalots

   Here is the same input in XML format (HTTP POST). Note that this does not include standard values.

XML format (HTTP POST). Also available is the .txt version of this XML.

<?xml version="1.0" encoding="UTF-8"?>
<findItemsByKeywordsRequest xmlns="http://www.ebay.com/marketplace/search/v1/services">
  <affiliate>
    <networkId>9</networkId>
    <trackingId>1234567890</trackingId>
    <customId>k-man</customId>
  </affiliate>
  <sortOrder>EndTime</sortOrder>
  <paginationInput>
    <entriesPerPage>2</entriesPerPage>
  </paginationInput>
  <keywords>camalots</keywords>
</findItemsByKeywordsRequest>

Output

XML format. Also available is the .txt version of this XML.

<findItemsAdvancedResponse xmlns:ms="http://www.ebay.com/marketplace/services"
xmlns="http://www.ebay.com/marketplace/search/v1/services">
   <ack>Success</ack>
   <version>1.1.0</version>
   <timestamp>2009-12-04T23:57:45.584Z</timestamp>
   <searchResult count="2">
      <item>
         <itemId>260515819366</itemId>
         <title>Black Diamond Camalots Sizes 3 and 3.5 used.</title>
         <globalId>EBAY-US</globalId>
         <primaryCategory>
            <categoryId>50814</categoryId>
            <categoryName>Carabiners & Hardware</categoryName>
         </primaryCategory>
         <galleryURL>
         http://thumbs3.ebaystatic.com/pict/2605158193668080_1.jpg</galleryURL>
         <viewItemURL>http://rover.ebay.com/rover/1/711-53200-19255-0/1?campid=
         1234567890&customid=k-man&toolid=0&mpre=
         http%3A%2F%2Fcgi.ebay.com%2FBlack-Diamond-Camalots-Sizes-3-and-3-5-
         used_W0QQitemZ260515819366QQcmdZViewItemQQptZLH_DefaultDomain_0%3Fhash%3Ditem3ca7
         f3ef66</viewItemURL>
         <paymentMethod>PayPal</paymentMethod>
         <autoPay>false</autoPay>
         <postalCode>37042</postalCode>
         <location>Clarksville,TN,USA</location>
         <country>US</country>
         <shippingInfo>
            <shippingType>Calculated</shippingType>
            <shipToLocations>US</shipToLocations>
         </shippingInfo>
         <sellingStatus>
            <currentPrice currencyId="USD">30.6</currentPrice>
            <convertedCurrentPrice currencyId="USD">30.6</convertedCurrentPrice>
            <bidCount>4</bidCount>
            <sellingState>Active</sellingState>
            <timeLeft>P2DT18H9M19S</timeLeft>
         </sellingStatus>
         <listingInfo>
            <bestOfferEnabled>false</bestOfferEnabled>
            <buyItNowAvailable>false</buyItNowAvailable>
            <startTime>2009-11-30T18:07:04.000Z</startTime>
            <endTime>2009-12-07T18:07:04.000Z</endTime>
            <listingType>Auction</listingType>
            <gift>false</gift>
         </listingInfo>
      </item>
      <item>
         <itemId>140361562585</itemId>
         <title>Camalots!  Black Diamond protection cams NICE!</title>
         <globalId>EBAY-US</globalId>
         <primaryCategory>
            <categoryId>50814</categoryId>
            <categoryName>Carabiners & Hardware</categoryName>
         </primaryCategory>
         <galleryURL>
         http://thumbs2.ebaystatic.com/pict/1403615625858080_1.jpg</galleryURL>
         <viewItemURL>http://rover.ebay.com/rover/1/711-53200-19255-0/1?campid=
         1234567890&customid=k-man&toolid=0&mpre=
         http%3A%2F%2Fcgi.ebay.com%2FCamalots-Black-Diamond-protection-cams-
         NICE_W0QQitemZ140361562585QQcmdZViewItemQQptZLH_DefaultDomain_0%3Fhash%3Ditem20ae
         3379d9</viewItemURL>
         <paymentMethod>PayPal</paymentMethod>
         <autoPay>false</autoPay>
         <postalCode>80521</postalCode>
         <location>Fort Collins,CO,USA</location>
         <country>US</country>
         <shippingInfo>
            <shippingServiceCost currencyId="USD">10.0</shippingServiceCost>
            <shippingType>Flat</shippingType>
            <shipToLocations>Worldwide</shipToLocations>
         </shippingInfo>
         <sellingStatus>
            <currentPrice currencyId="USD">150.0</currentPrice>
            <convertedCurrentPrice currencyId="USD">150.0</convertedCurrentPrice>
            <sellingState>Active</sellingState>
            <timeLeft>P27DT3H20M21S</timeLeft>
         </sellingStatus>
         <listingInfo>
            <bestOfferEnabled>true</bestOfferEnabled>
            <buyItNowAvailable>false</buyItNowAvailable>
            <startTime>2009-12-02T03:18:06.000Z</startTime>
            <endTime>2010-01-01T03:18:06.000Z</endTime>
            <listingType>FixedPrice</listingType>
            <gift>false</gift>
         </listingInfo>
      </item>
   </searchResult>
   <paginationOutput>
      <pageNumber>1</pageNumber>
      <entriesPerPage>2</entriesPerPage>
      <totalPages>4</totalPages>
      <totalEntries>7</totalEntries>
   </paginationOutput>
</findItemsAdvancedResponse>

Back to list of samples

Back to top

Back to top

This document was generated with a customized version of the apireferencedocs tool.

© 2009–2010 eBay, Inc. All rights reserved. This documentation and the API may only be used in accordance with the eBay Developers Program and API License Agreement.