BOSS API Specification

Please note, that depending on the service you are using, the specific service may have exceptions that override the universal arguments set for BOSS API. Please read each services section before use. The following specification details the GET or input function of the Yahoo BOSS API. There are two API calls that can be used in Yahoo BOSS API, a multi-service with keywords GET function and a multi-service and multi-keyword GET function that specifies the keywords per service to be searched.

Syntax for Data Reads (GET)

  1. https://yboss.yahooapis.com/ysearch/{service,*}?q={keywords}
  2. https://yboss.yahooapis.com/ysearch/{service,*}?service1.q={keywords}&service2.q={keywords}

Service

Below is a list of data sources that can be used with the Query specifications described above:

Service Description
web Yahoo web search index results with basic url, title, and abstract data.
limitedweb Limited web results. Index refresh rate ~ 3days.
images Image search. Image Search includes images from the Yahoo Image Search index and Flickr.
news News search. News Search includes late breaking news articles from the past 30 days.
ads Advertising. If publisher has qualified for Yahoo Search Advertising.

General API Rules

    • and - operators are transparent to the gateway and passed to

    respective service

  1. Batch requests can be made across services using a comma separated list.

  2. Keywords parameters can be used by service(s).

  3. Keywords parameter will default across all appropriate services unless individual keyword values are provided for each service selected.

Basic Rules

Support for XML and JSON formats are provided in the order the service was requested. 50 results are returned per query request for web, limitedweb, and news results.

Note

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

BOSS API Examples

  1. Searching for ipod through web data:
    • https://yboss.yahooapis.com/ysearch/web?q=ipod
  2. Search the web, images, news services with different query
    • https://yboss.yahooapis.com/ysearch/web,images?web.q=ipod&images.q=mp3
  3. Search the web, images, news services with different queries and different SiteRestricts
    • https://yboss.yahooapis.com/ysearch/limitedweb,news?limitedweb.q=google&limitedweb.sites=apple.com,techcrunch.com&news.q=mp3&news.sites=news.yahoo.com

Universal Yahoo BOSS API Arguments

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

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

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.

format The data format of the response. Value can be set to either "xml" or "json". Default sets format to`` “json”``.
callback 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.

Note

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

Note

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

Example:

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

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

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

Example:

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.

Note

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

Note

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.

Note

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:

<bossresponse responsecode="200">
  <web start="0" count="50" totalresults="362000">
    <results>
      <result>
        <date>2011/02/01</date>
        <clickurl>http://www.barackobama.com/</clickurl>
        <url>http://www.barackobama.com/</url>

        <dispurl type="default">www.barack&lt;b&gt;obama&lt;/b&gt;.com</dispurl>
        <title type="default">Organizing for America | BarackObama.com</title>
        <abstract type="default">Organizing for America is the grassroots organization that supports President &lt;b&gt;Obama&lt;/b&gt;'s agenda for change. Visit BarackObama.com for blog posts, local events, information about ...</abstract></result>

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

<a href="http://www.barackobama.com"> http://www.barackobama.com/></a>