Universal Yahoo BOSS API Arguments

The following arguments apply to these BOSS API services: Web, Limitedweb, Image, and News.

Argument Description
service Web; Limitedweb; Images; News; Blogs services


Ordinal position of first result. First position is 0. Default sets start to 0.

Note: Start parameter cannot be greater than 1000. All services return a maximum of 1000 results only.


Total number of results to return. Maximum default value is 50.


  • The maximum default value for images is 35.
  • Blogs maximum default value is 20.


Web and News:

Specifies which regional (country) search product to query. See Supported Regions and Languages . Default sets region to "us". Region must be used in parallel with language.


Specifies which regional (country) search product to query. See Supported Regions and Languages. Default sets region to "us". Region must be used in parallel with language.

The format is market=en-us language-region).


The data format of the response. Value can be set to either "xml" or "json". Default sets format to "json".


Returns the response of the query wrapped inside the function name passed. This parameter is valid only if format is set to "json". No default value exists.

sites Restricts BOSS API search results to a set of pre-defined sites. Multiple sites must be comma separated. Example: sites=abc.com,cnn.com.

A user can also exclude results from certain sites when conducting web and image search by using the unary "-" operator.

Note: The images source does not yet support multiple sites.

Note: This argument can use a single site parameter. Example: sites=mysite.com.

Note: This argument will work for Video as a single site restrict. Example: sites=examplevideo.com.


URL encode any reserved characters in the query and parameters before sending the BOSS API call. See Reserved Characters and Escape Values for more information.


Yahoo Search BOSS API supports the use of HTTPS in your url. For example, https/yboss.yahooapis.com/ysearch/web?q=yahoo. Each programming language enforces certain specifications in using HTTPS that are beyond the scope of this guide. If you have specific questions please use the BOSS Yahoo group.

Universal BOSS API Query Operators

Phrase Words

To ensure the exact query keywords are present in the search result, in the exact order, use quotation marks " " around the query keywords.

Example: https://yboss.yahooapis.com/ysearch/web?q="Apple Pie"&format=xml

Using the AND, OR (|, &) operator




You can use the Boolean operator OR/AND to combine query words. The OR/AND must be in all caps or else it is treated as a query term. Note: You can substitute | or & for each respective operator.

AND/OR queries are best used with combination of braces or quotes. See examples below.

Please see the following example queries to get a better understanding

  • Mixing AND/OR queries

    Example 1: You are searching for “apple ipod” AND “apple iphone” AND “steve jobs”

    Query is /ysearch/web?q=((apple ipod)AND(apple iphone)AND(steve jobs))

    Example 2: You are searching for “Steve Jobs” AND "iphone" OR "ipad" at bestbuy.com OR newegg.com

    Query is /ysearch/web?q=((steve jobs)AND((ipad)OR(iphone)))&sites=bestbuy.com,newegg.com

    Example 3: “steve” OR “jobs” combined with “apple TV” in askville.amazon.com

    Query is /ysearch/web?q=(((steve)OR(jobs))AND(“apple tv”))&sites=askville.amazon.com

Using unary operators


https://yboss.yahooapis.com/ysearch/web?q=query -query&format=xml

You can prefix any word or phrase in a query with a plus sign (+) or a minus sign (-):

  • Placing a plus sign before a word or phrase tells the search cluster to find only those documents containing that word or phrase.
  • Placing a minus sign before a word or phrase tells the search cluster to discard any documents containing that word or phrase.

The effect of these unary operators is limited to the word or phrase immediately following the operator. Using a plus or minus on one word in a query does not affect following words or the same word elsewhere in the query.


The | and the & operators must be escaped before use in the BOSS API. See Reserved Characters and Escape Values.


Unary operators do not recognize parentheses; if you place a unary operator before words in parentheses, the operator applies only to the first word. For example, the query cake -(coconut chocolate) discards only documents containing the word coconut, but keeps documents containing the word chocolate.

A Note on Response URL's
url vs clickurl - coding convention

The clickurl returns a navigation URL that leads to the target URL for each result. Yahoo returns a clickurl that are captured in either <clickurl> or <b_clickurl> field in the XML Response. A clickurl allows Yahoo to capture important information on product usage.


You are required to include clickurl in anchor link of your search results. You cannot modify the clickurl in any manner.

Examine the following XML elements:

You would then generate the following HTML fragment for a search results page:

Table of Contents