Contextual Web Search Documentation for Yahoo! Search Web Services

Support & Community

The Contextual Web Search service is discussed on the yws-search-general mailing list.

Request URL

http://search.yahooapis.com/WebSearchService/V1/contextSearch

Note that due to the context being a potentially lengthy string, contextual searches should be submitted using the POST protocol rather than the GET protocol.

Request parameters

See information on constructing REST queries

Parameter	Value	Description
appid	string (required)	The application ID. See Application IDs for more information.
query	string	The query to search for (UTF-8 encoded). This query supports the full search language of Yahoo! Search, including meta keywords. For details on constructing queries, see Search Tips.
context	string (required)	The context to extract meaning from (UTF-8 encoded).
results	integer: default 10, max 100	The number of results to return.
start	integer: default 1	The starting result position to return (1-based). The finishing position (start + results - 1) cannot exceed 1000.
format	any (default), html, msword, pdf, ppt, rss, txt, xls	Specifies the kind of file to search for.
adult_ok	no value (default), or 1	Specifies whether to allow results with adult content. Enter a 1 to allow adult content.
similar_ok	no value (default), or 1	Specifies whether to allow multiple results with similar content. Enter a 1 to allow similar content.
language	string: default en	The language the results are written in. Supported Languages.
country	string: default no value	The country code for the country the website is located in. Supported Country Codes.
site	string: default no value	A domain to restrict your searches to (e.g. www.yahoo.com). You may submit up to 30 values (site=www.yahoo.com&site=www.cnn.com).
license	any (default), cc_any, cc_commercial, cc_modifiable	The Creative Commons license that the contents are licensed under. You may submit multiple values (e.g. license=cc_commercial&license=cc_modifiable).
output	string: xml (default), json, php	The format for the output. If json is requested, the results will be returned in JSON format. If php is requested, the results will be returned in Serialized PHP format.
callback	string	The name of the callback function to wrap around the JSON data. The following characters are allowed: A-Z a-z 0-9 . [] and _. If output=json has not been requested, this parameter has no effect. More information on the callback can be found in the Yahoo! Developer Network JSON Documentation.

Sample Request (URL: http://search.yahooapis.com/WebSearchService/V1/contextSearch):

Response fields

The schema document for this service response is located at http://search.yahooapis.com/WebSearchService/V1/WebSearchResponse.xsd

Field	Description
ResultSet	Contains all of the query responses.
Result	Contains each individual response.
totalResultsAvailable	The number of query matches in the database.
totalResultsReturned	The number of query matches returned. This may be lower than the number of results requested if there were fewer total results available.
firstResultPosition	The position of the first result in the overall search.
Title	The title of the web page.
Summary	Summary text associated with the web page.
Url	The URL for the web page.
ClickUrl	The URL for linking to the page. See URL linking for more information.
MimeType	The MIME type of the page
ModificationDate	The date the page was last modified, in unix timestamp format.
Cache	The URL of the cached result, and its size in bytes.

Sample response

The following is a sample response for the sample query above:

<ResultSet xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="urn:yahoo:srch" xsi:schemaLocation="urn:yahoo:srch http://search.yahooapis.com/WebSearchService/V1/WebSearchResponse.xsd" totalResultsAvailable="3610652" totalResultsReturned="2" firstResultPosition="1">
  <Result>
    <Title>Find in a Library: Florentine sculptors of the Renaissance.</Title>
    <Summary>... der Renaissance. Subjects: Italian, Sculptors, Sculpture, Italy, Florence, Renaissance Contents ... architect and decorator --, The Madonna in Florentine sculpture of the ...</Summary>
    <Url>http://www.worldcatlibraries.org/wcpa/ow/c62daeba8bdccafe.html</Url>
    <ClickUrl>http://rds.yahoo.com/S=96857362/K=madonna/v=2/XP=yws/SID=w/l=WS1/R=1/H=0/MI=free/IPC=us/SHE=0/SIG=1fn2o7plb/EXP=1110911915/*-http%3A//rdrw1.yahoo.com/click?u=http://www.worldcatlibraries.org/wcpa/ow/c62daeba8bdccafe.html&y=0289E64123A68E71&i=482&c=11645&q=02%5ESSHPM%5BL7r~%7Bpqq~%3F%3Dvk~sv~q%3Fl%7Cjsokpml%3D%3FM%5E%5BUJLK7hzvxwkz%7B3/1%26%26-*%263%3Divmxvq%3Fr~mf%3D6%3FM%5E%5BUJLK7hzvxwkz%7B3/1%2B%26)%27%2B3o~vqkzml6%3FM%5E%5BUJLK7hzvxwkz%7B3/1%2B%26*/,3mzq~vll~q%7Cz6%3FM%5E%5BUJLK7hzvxwkz%7B3/1%2B%26,(.3vqlovm~kvpq66&e=utf-8&r=0&d=wow~YHOO-en-us&n=8QE45H0TQSQK5E0U&s=50&t=&m=4235DA33&x=013F6AEDAC5DB671</ClickUrl>
    <ModificationDate>1110355200</ModificationDate>
    <MimeType>text/html</MimeType>
  </Result>
  <Result>
    <Title>United Press International: Putting faces on Jesus and Virgin Mary</Title>
    <Summary>UPI Perspectives. Putting faces on Jesus and Virgin Mary. By FREDERICK M. WINSHIP. Published 9/16/2002 11:15 AM. NEW YORK, Sept. ... on an ebony cross by Giambologna, considered the greatest 16th century Italian sculptors in the Mannerist style ... whose "Profile of a Young Madonna," a low relief portrait in stone ...</Summary>
    <Url>http://www.upi.com/view.cfm?StoryID=20020916-105519-8545r</Url>
    <ClickUrl>http://rds.yahoo.com/S=96857362/K=madonna/v=2/XP=yws/SID=w/l=WS1/R=2/H=0/IPC=us/SHE=0/SIG=12dgic8rc/EXP=1110911915/*-http%3A//www.upi.com/view.cfm?StoryID=20020916-105519-8545r</ClickUrl>
    <ModificationDate>1108972800</ModificationDate>
    <MimeType>text/html</MimeType>
  </Result>
</ResultSet>

Rate Limit

The Contextual Web Search service is limited to 5,000 queries per IP address per day. See information on rate limiting and our Usage Policy to learn about acceptable uses and how to request additional queries.

Errors

The Contextual Web Search service returns the standard errors. There are no service-specific errors.