Skip to main content

In addition to filters, you can specify certain properties to control the way data is returned. These do not control which data is returned, but rather how it is sorted and the volume of the response.

Sorting Search Results

Use the sortOrder field in search requests (e.g., findItemsByKeywords) to specify the order in which the returned items are sorted. For example, you can specify a value of PricePlusShippingAsc to sort results by the combined cost of item price plus shipping cost, with the lowest priced items first. Or, you could use a value of EndTime to sort auctions by their end times, with those ending soonest first. Sorting has no effect upon the quantity of results returned.

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.

For more information, including available sort values, see the sortOrder input field in the API Reference. The available sort values are the same for all search calls in the Finding API.

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 any given request. The paginationInput.pageNumber field specifies which "page" of data to return in the current call.

Sample pagination input (XML)

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

Sample pagination input (HTTP GET)

...&paginationInput.entriesPerPage=10&paginationInput.pageNumber=2...

There are corresponding fields in the response for pagination data. The paginationOutput.totalEntries field 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. The paginationOutput.totalPages property indicates the total number of calls that would be required to retrieve all of the matching items. The value specified in the paginationInput.pageNumber field of search requests indicates where in the sequence of multiple calls the application is, relative to the number returned in paginationInput.totalPages.

Sample pagination output (XML)

<paginationOutput>
  <pageNumber>2</pageNumber>  
  <entriesPerPage>10</entriesPerPage>
  <totalPages>21</totalPages>
  <totalEntries>207</totalEntries>
</paginationOutput>

The 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 count value will typically match the entriesPerPage value, except when your search returns fewer results than the value specified in entriesPerPage or when retrieving the last page of results.

Selecting Additional Data to Return in Search Results

In the search results, searchResult.item contains a default set of data for items matching your request. If you want more data than the default data, you can use one or more outputSelector fields, as shown in the OutputSelectorType definition.

To use multiple outputSelector fields in a URL, an array notation is required, as shown in the following example:

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

Got thoughts? Click the feedback button – your insights help us improve!