FindPopularSearches - Call Reference - eBay Shopping Web Services

FindPopularSearches

FindPopularSearches finds the words more frequently used by eBay users when searching for listings. If you use keywords, this call returns available alternative search terms in addition to popular related search terms.

This call has been designed to be useful to applications which support shopping comparisons and browsing. It can help a buyer find alternative or related search terms they would like to consider. An alternative search term differs from related in that the alternative may replace the query you are looking for, whereas related is a refinement of the query. For example, a search for the keyword "Dell" might reveal alternatives search terms such as "HP" and "Toshiba". The related search might include "Dell Monitor" or "Dell Desktop".

On input, you may specify keywords or category IDs. You can use them separately to retrieve items by keyword or category, or combine them to limit the search to a specific item and category combination. For example, you could search for popular searches by the keyword "Nikon" or by category Digital Cameras (# 29997), but if you combine keyword and category in a single query, you will get the most popular "Nikon" search terms in the Digital Camera category.

For information about specifying affiliate parameters, see Affiliate URL Parameters and HTTP Header Values.

To find the most popular search terms across all categories, set IncludeChildCategories as true and do not specify any keywords or categories.

You may specify up to 10 keywords but be aware that each keyword will be evaluated individually and the result will include which keyword is the related search data is for.

Up to 10 CategoryIDs may be specified except when you also specify IncludeChildCategories as true. If you set IncludeChildCategories as true in the request, you may only specify a single CategoryID.

A default of 20 items is returned with a limit of 1000.

Best Practices

FindPopularSearches will return popular search terms but does not return any item information. By combining FindPopularSearches with FindPopularItems, you can find the most popular items from the most used (popular) search terms. This can help users determine what buyers are looking for and finding interesting..

More Tips

If you discover other useful practices, feel free to add them in the User-Contributed Notes at the bottom of this page.

If you're looking for more tips, try searching the Knowledge Base and Developer Forums.

Related calls:

FindPopularItems - Searches for popular items based on a category or keyword. Returns WatchCount in addition to item information.

FindPopularSearches Input

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).

Argument	Type	Reqd?	Meaning
Standard Input Fields [Jump to call-specific fields]
MessageID	string	Optional	If you pass a value in MessageID in a request, we'll return the same value in CorrelationID in the response. If you're making a lot of calls, you can use this for tracking that a response is returned for every request and to match particular responses to particular requests. (In this case, specify a different value for each request.) You can specify any value that is useful to you.
Call-specific Input Fields
CategoryID	string (repeatable)	Optional	Specify CategoryID to restrict your query to a specific category. Up to 10 categories may be specified If you are using a URL, and you want to specify multiple values, use a comma. For example, if you want to specify Fiction Books and Children's Books, specify CategoryID=377,279. If the specified category ID doesn't match an existing category for the site, an invalid-category error message is returned. To determine valid categories: Use the FindItemsAdvanced CategoryHistogram value in the IncludeSelector field to retrieve matching categories. Then make another FindItemsAdvanced call with the ID of a matching category. CategoryID can be used in combination with QueryKeywords and IncludeChildCategories. When IncludeChildCategories is true and used in conjunction with CategoryID, one and only one CategoryID is allowed. Otherwise, up to 10 CategoryIDs are allowed. To retrieve the most popular keywords for a root category, set one of the CategoryIDs to -1 or do not include CategoryID in the Request. Max length: 10.
IncludeChildCategories	boolean	Optional	If true, only one CategoryID can be specified, and keywords are returned for that category and its subcategories. When IncludeChildCategories is true and used in conjunction with CategoryID, one and only one CategoryID is allowed. If false, keywords are returned only for the categories identified by CategoryID. The default is false. Default: false.
MaxKeywords	int	Optional	The maximum number of keywords to be retrieved per category for this call. Min: 1. Max: 1000. Default: 20.
MaxResultsPerPage	int	Optional	Specifies the maximum number of PopularSearchResults per page in the returned list. If not specified, the default returns 20 results per page. Default: 20.
PageNumber	int	Optional	Specifies the number of the page of data to return in the current call. Specify a positive value equal to or lower than the number of pages available (which you determine by examining the results of your initial request). Default: 1.
QueryKeywords	string (repeatable)	Optional	A query that specifies a string for searching titles of items on eBay. If you are using a URL, then to search for multiple words, use "%20". For example, use Harry%20Potter to search for items containing those words in any order. You can incorporate wildcards into a multi-word search, as in the following: ap%20ip. The words "and" and "or" are treated like any other word. Only use "and", "or", or "the" if you are searching for listings containing these words. QueryKeywords can be used in combination with CategoryID and IncludeChildCategories.

See also Samples.

See also the Deprecated Objects link above. Fields presented in this color are deprecated, and fields presented in this color are not returned (or soon will not be returned) or are not operational (or soon will be non-operational).

<?xml version="1.0" encoding="utf-8"?>
<FindPopularSearchesResponse xmlns="urn:ebay:apis:eBLBaseComponents">
  <!-- Standard Output Fields -->
  <Ack> AckCodeType </Ack>
  <Build> string </Build>
  <CorrelationID> string </CorrelationID>
  <Errors> ErrorType 
    <ErrorClassification> ErrorClassificationCodeType </ErrorClassification>
    <ErrorCode> token </ErrorCode>
    <ErrorParameters ParamID="string"> ErrorParameterType 
      <Value> string </Value>
    </ErrorParameters>
    <!-- ... more ErrorParameters nodes here ... -->
    <LongMessage> string </LongMessage>
    <SeverityCode> SeverityCodeType </SeverityCode>
    <ShortMessage> string </ShortMessage>
  </Errors>
  <!-- ... more Errors nodes here ... -->
  <Timestamp> dateTime </Timestamp>
  <Version> string </Version>
  <!-- Call-specific Output Fields -->
  <PageNumber> int </PageNumber>
  <PopularSearchResult> PopularSearchesType 
    <AlternativeSearches> string </AlternativeSearches>
    <CategoryID> string </CategoryID>
    <CategoryParentID> string </CategoryParentID>
    <QueryKeywords> string </QueryKeywords>
    <RelatedSearches> string </RelatedSearches>
  </PopularSearchResult>
  <!-- ... more PopularSearchResult nodes here ... -->
  <TotalPages> int </TotalPages>
</FindPopularSearchesResponse>

Return Value	Type	Returned?	Meaning
Standard Output Fields [Jump to call-specific fields]
Ack	AckCodeType	Always	Indicates whether the call was successfully processed by eBay. Applicable values: • CustomCode (out) Reserved for internal or future use. • Failure (out) Request processing failed • Success (out) Request processing succeeded • Warning (out) Request processing completed with warning information being included in the response message (Not all values in AckCodeType apply to this field.)
Build	string	Always	This refers to the particular software build that eBay used when processing the request and generating the response. This includes the version number plus additional information. eBay Developer Support may request the build information when helping you resolve technical issues.
CorrelationID	string	Conditionally	If you pass a value in MessageID in a request, we will return the same value in CorrelationID in the response. You can use this for tracking that a response is returned for every request and to match particular responses to particular requests. Only returned if MessageID was used.
Errors	ErrorType (repeatable)	Conditionally	A list of application-level errors or warnings (if any) that were raised when eBay processed the request. Application-level errors occur due to problems with business-level data on the client side or on the eBay server side. For example, an error would occur if the request contains an invalid combination of fields, or it is missing a required field, or the value of the field is not recognized. An error could also occur if eBay encountered a problem in our internal business logic while processing the request. Only returned if there were warnings or errors.
Errors.ErrorClassification	ErrorClassificationCodeType	Conditionally	API errors are divided between two classes: system errors and request errors. Applicable values: • CustomCode (out) Reserved for internal or future use. • RequestError (out) An error has occurred either as a result of a problem in the sending application or because the application's end-user has attempted to submit invalid data (or missing data). In these cases, do not retry the request. The problem must be corrected before the request can be made again. If the problem is due to something in the application (such as a missing required field), the application must be changed. If the problem is a result of end-user data, the application must alert the end-user to the problem and provide the means for the end-user to correct the data. Once the problem in the application or data is resolved, resend the request to eBay with the corrected data. • SystemError (out) Indicates that an error has occurred on the eBay system side, such as a database or server down. An application can retry the request as-is a reasonable number of times (eBay recommends twice). If the error persists, contact Developer Technical Support. Once the problem has been resolved, the request may be resent in its original form. See Errors by Number.
Errors.ErrorCode	token	Conditionally	A unique code that identifies the particular error condition that occurred. Your application can use error codes as identifiers in your customized error-handling algorithms. See Errors by Number.
Errors.ErrorParameters	ErrorParameterType (repeatable)	Conditionally	Some warning and error messages return one or more variables that contain contextual information about the error. This is often the field or value that triggered the error. You can usually predict where these will occur by looking at the "replaceable_value" indicators in our Errors by Number page. See Errors by Number.
Errors.ErrorParameters [ attribute ParamID ]	string	Conditionally	The index of the parameter in the error.
Errors.ErrorParameters.Value	string	Conditionally	The value of the variable.
Errors.LongMessage	string	Conditionally	A more detailed description of the condition that raised the error. See Errors by Number.
Errors.SeverityCode	SeverityCodeType	Conditionally	Indicates whether the error caused the request to fail. If the request fails and the source of the problem is within the application (such as a missing required element), please change the application before you retry the request. If the problem is due to end-user input data, please alert the end-user to the problem and provide the means for them to correct the data. Once the problem in the application or data is resolved, you can attempt to re-send the request to eBay. If the source of the problem is on eBay's side, you can retry the request as-is a reasonable number of times (eBay recommends twice). If the error persists, contact Developer Technical Support. Once the problem has been resolved, the request may be resent in its original form. When a warning occurs, the error is returned in addition to the business data. In this case, you do not need to retry the request (as the original request was successful). However, depending on the cause or nature of the warning, you might need to contact either the end user or eBay to effect a long term solution to the problem to prevent it from reoccurring in the future. Applicable values: • CustomCode (out) Reserved for internal or future use • Error (out) The request that triggered the error was not processed successfully. When a serious application-level error occurs, the error is returned instead of the business data. • Warning (out) The request was processed successfully, but something occurred that may affect your application or the user. For example, eBay may have changed a value the user sent in. In this case, eBay returns a normal, successful response and also returns the warning. See: Errors by Number Requirements for Error Handling for more information (in the eBay Trading Web Services guide)
Errors.ShortMessage	string	Conditionally	A brief description of the condition that raised the error. See Errors by Number.
Timestamp	dateTime	Always	This value represents the date and time when eBay 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.
Version	string	Always	The release version that eBay used to process the request. Note: This is usually the latest release version, as specified in the release notes. (eBay releases the API to international sites about a week after we release it to the US site.) If a field in the response returns the token "CustomCode", it usually means that the field is a code type (a token or enumeration), and that in your request URL (or HTTP header) you specified a version that is older than the version in which the token was added to the call. See eBay Versioning Strategy.
Call-specific Output Fields
PageNumber	int	Conditionally	Indicates the page of data returned by the current call. For instance, for the first set of items can be returned, this field has a value of one.
PopularSearchResult	PopularSearchesType (repeatable)	Always	Organization of keywords by category. For each category, its ID and its parent's ID and keywords are listed.
PopularSearchResult .AlternativeSearches	string	Conditionally	Alternative search keywords for the query keywords, separated by semicolons. You can use this to find other search terms buyers and sellers may be interested in. For example, if a seller lists an item with "wedding" in the title, they may also be interested in adding "bridal" to the title because bridal is an alternative search keyword which buyers have used.
PopularSearchResult.CategoryID	string	Conditionally	Numeric ID of a category on eBay.
PopularSearchResult .CategoryParentID	string	Conditionally	Category ID identifying a category that is an ancestor of the category indicated in CategoryID.
PopularSearchResult .QueryKeywords	string	Conditionally	Specifies which query keywords corresponds to this PopularSearchResult. Query Keywords are returned in the output to clarify which result set corresponds to which Query Keyword inputs (as there can be more than one set of keywords in the input).
PopularSearchResult .RelatedSearches	string	Conditionally	Keywords related to the query keywords, separated by semicolons. You can use this to find more detailed related keywords. For example, the query keyword "wedding" is related to searches for "wedding decorations;wedding favors;wedding supplies;wedding dresses..." which helps the seller and buyer specify their query with more detail and precision.
TotalPages	int	Conditionally	Indicates the total number of pages of data that could be returned by repeated requests. Returned with a value of 0 if no pages are available.

FindPopularSearches Detail Controls

This call does not use a detail control mechanism.

FindPopularSearches Samples

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 ↓ - This search is a basic sample.
CategoryID Call ↓ - This search is a basic sample which combines keyword query with CategoryID.

Sample: Basic Call

This search is a basic sample.

Input

Here is an example of using a keyword query to obtain detailed information about popular searches.

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://open.api.ebay.com/shopping?callname=FindPopularSearches
   &responseencoding=XML
   &appid=YourAppIDHere
   &siteid=0
   &version=531
   &QueryKeywords=dell

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"?>
<FindPopularSearchesRequest xmlns="urn:ebay:apis:eBLBaseComponents">
  <QueryKeywords>dell</QueryKeywords>
</FindPopularSearchesRequest>

Output

Here is an example of the output that you can obtain using this call.

If you chose XML as the response encoding type, you would get something like this.

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

<?xml version="1.0" encoding="UTF-8" ?> 
<FindPopularSearchesResponse xmlns="urn:ebay:apis:eBLBaseComponents">
  <Timestamp>2007-09-12T23:47:01.000Z</Timestamp> 
  <Ack>Success</Ack> 
  <Build>e531_intl_APILW2_5315915_R1</Build> 
  <Version>531</Version> 
  <PopularSearchResult>
    <QueryKeywords>dell</QueryKeywords> 
    <AlternativeSearches>latitude;inspiron;dimension;alienware;lcd;toshiba</AlternativeSearches> 
    <RelatedSearches>dell laptop;dell dimension;dell computer;dell desktop;dell notebook;dell pc;dell 4700;dell axim;dell monitor;dell inspiron;dell pda</RelatedSearches> 
  </PopularSearchResult>
</FindPopularSearchesResponse>

Sample: CategoryID Call

This search is a basic sample which combines keyword query with CategoryID.

Input

Here is an example of using a keyword query and CategoryID to obtain detailed information about popular searches. It restricts the keyword query for "dell" to the Computers & Networking and Laptops & Notebooks categories.

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://open.api.ebay.com/shopping?callname=FindPopularSearches
   &responseencoding=XML
   &appid=YourAppIDHere
   &siteid=0
   &version=533
   &QueryKeywords=dell
   &CategoryID=58058,51148

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"?>
<FindPopularSearchesRequest xmlns="urn:ebay:apis:eBLBaseComponents">
  <CategoryID>58058</CategoryID>
  <CategoryID>51148</CategoryID>
  <QueryKeywords>dell</QueryKeywords>
</FindPopularSearchesRequest>

Output

Here is an example of the output that you can obtain using this call.

If you chose XML as the response encoding type, you would get something like this.

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

</FindPopularSearchesResponse>
<?xml version="1.0" encoding="UTF-8" ?> 
<FindPopularSearchesResponse xmlns="urn:ebay:apis:eBLBaseComponents">
  <Timestamp>2007-10-03T01:22:39.218Z</Timestamp> 
  <Ack>Success</Ack> 
  <Build>e533_core_Bundled_5430035_R1</Build> 
  <Version>533</Version> 
  <PopularSearchResult>
    <CategoryID>58058</CategoryID> 
    <CategoryParentID>58058</CategoryParentID> 
    <QueryKeywords>dell</QueryKeywords> 
    <AlternativeSearches>laptop;hp;alienware</AlternativeSearches> 
    <RelatedSearches>dell laptop;dell dimension;dell inspiron;dell desktop;dell dimension xps</RelatedSearches> 
  </PopularSearchResult>
  <PopularSearchResult>
    <CategoryID>51148</CategoryID> 
    <CategoryParentID>58058</CategoryParentID> 
    <QueryKeywords>dell</QueryKeywords> 
    <AlternativeSearches>inspiron;toshiba;ibm;hp;compaq;laptop;new;sony;gateway;centrino;acer</AlternativeSearches> 
    <RelatedSearches>dell inspiron;dell xps;dell new;dell 700m;dell 6000;dell latitude;dell p4;dell inspiron 6000</RelatedSearches> 
  </PopularSearchResult>
</FindPopularSearchesResponse>

FindPopularSearches Change History

Version	Description
531 2007-21-09	(added) New call.

User-Contributed Notes

This document was generated with a customized version of the apireferencedocs tool [0.5M zip].

eBay Shopping API Call Reference Version 573

Best Practices

More Tips

eBay Shopping API
Call Reference Version 573