HalfFinding API

eBay Half Finding API User Guide


Important: As of September 1, 2017, sellers will no longer be able to list and buyers will no longer be able to buy on Half.com. However, the findHalfItems call will still be functional as long as there are Half.com listings in the eBay system. Half.com users will still have access to their My Account Page until November 30, 2017. For more information on this change, please see the Half.com Closing FAQ page.


The Half Finding API provides programmatic access to items listed on the Half.com website. It lets you search and browse for items listed on Half.com that are associated with a specific product ID and provides useful metadata to refine searches and enhance the search experience. Developers can use this API to build search and browse capabilities into bidding and buying applications. Currently, you can filter item searches by item condition and/or seller.

This user guide contains the following information:

Service Overview

The Half Finding API provides one call, findHalfItems, that helps buyers and sellers find items on the Half.com website. The findHalfItems call uses a product ID and retrieves items associated with that product, based on the item filtering supplied.

Remember that ProductID is required for findHalfItems. The productID can be of various types. Common types are ISBN numbers, or universal product codes (UPC) or the eBay assigned Reference ID for that product (Reference type). In some scenarios, the ISBN number or the UPC number is known in advance, and so findHalfItems can be called directly, using that known value. In other scenarios, the productID is not known, but other things about the product are known, such as its title, description, and so forth. To get the product ID in those scenarios, , you can use the FindHalfProducts call provided by the Shopping API.

Notice that although FindHalfProducts does return some items for the returned product, it only returns a relatively few items, around 25 per product. The findHalfItems call returns a lot more items, around 1500 per product.

Refining a Search with Item Filters

Item Filters limit the items returned from the query to only those matching the filter criteria. Currently, the items can be filtered by item condition and/or seller ID. Item filters represent constraints applied to the return of items, providing better control over the search results by narrowing the range of items returned. The itemFilter node contains name/value pairs to describe specific filters. Item filters are optional.

The following snippet shows two item filters in the same request: these are ANDed so that only brand new items from a specific seller are returned:

Sample itemfilter input (SOAP)

 <ser:itemFilter>
  <ser:name>Condition</ser:name>
  <ser:value>BrandNew</ser:value>
 </ser:itemFilter>
 <ser:itemFilter>
  <ser:name>Seller</ser:name>
  <ser:value>magical_bookseller</ser:value>
 </ser:itemFilter>

Paginating Search Results

Use paginationInput and its child elements to break the items matching the search criteria down into smaller subsets, or "pages" of data. The paginationInput.entriesPerPage field specifies the maximum number of items to return for each page. The paginationInput.pageNumber field specifies the maximum number of pages to return in the current call.

Sample pagination input (SOAP)

 <ser:paginationInput>
  <ser:entriesPerPage>10</ser:entriesPerPage>
  <ser:pageNumber>2</ser:pageNumber>
 </ser:paginationInput>

Authentication

All that is required to use the Half Finding API is an AppID. If you already have an AppID for use with another eBay API, such as the Shopping or Merchandising APIs, it will work for the Half Finding API, as well. You must specify your AppID in the X-EBAY-SOA-SECURITY-APPNAME HTTP header (or SECURITY-APPNAME URL parameter) of every request.

API Call Limits

The standard call limit for the Half Finding API is 5000 calls per day per IP address. The call limit can be increased to up to 1.5 million calls per day per IP address by completing the Compatible Application Check, which is a free service that the eBay Developers Program provides to its members.

Related APIs

The following eBay APIs can be useful when programming with the Half Finding API:

Back to top

Copyright © 2009–2011 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.