Search Feed Endpoint and Required Parameters

Endpoint

https://xml-nar-ss.ysm.yahoo.com/d/search/p/sortable/xmlb/ 

Required parameters

mkt

Syntax  

mkt= ca | us 

serveUrl

To ensure quality serving, you need to provide us with the serveUrl. The serveUrl is the fully-qualified name of the web page that you use to serve sponsored listings — the ad display page.

Syntax

serveUrl=URL_for_ad_display_page

where URL_for_ad_display_page is partner-supplied, URL-encoded, and adheres to IETF standards for URL specification as follows (whichever applies):

  • protocol://host_name/path_name/page_name
  • protocol://host_name/page_name

Keywords

The Keywords parameter defines the search term supplied by your user. In the initial query, you must specify Keywords explicitly. For subsequent queries, Sponsored Search supplies Keywords in the XML <NextArgs> and <PrevArgs> elements, which you must extract and append to your subsequent paging query.

Syntax

Keywords=search_term

where search_term is URL-encoded.

Partner

The Partner parameter defines the source tag, which Yahoo saves along with information about your search activity. This way, Yahoo can calculate and report accounting and performance statistics specific to your Web application usage.

Syntax

Partner=source_tag

affilData

The affilData parameter provides information about the user who supplied the search term. This information includes the following:

  • IP address of the machine that’s in direct communication with the partner server. The IP address must be the value of the REMOTE_ADDR environment variable from the HTTP request header, not the IP address of the server making the request to Yahoo
  • Software employed by the user or proxy server to submit a request (typically a Web browser). Derived from the HTTP_USER_AGENT environment variable in the HTTP request header.
  • Client-proxy routing loop to the partner server, derived from the HTTP_X_FORWARDED_FOR value in the HTTP request header.

Sponsored Search uses this information to detect search spam and for geolocation.

Syntax

affilData=user_data_list
where user_data_list is a URL-encoded sequence of subparameter specifications:
  • ip
  • ua
  • xfip
The subparameters look like this before encoding:
ip=REMOTE_ADDR[&xfip=HTTP_X_FORWARDED_FOR]&ua=HTTP_USER_AGENT

and subparameter value assignments are collected from HTTP environment variables that supply:

  • ip=REMOTE_ADDR value (required), which is a valid IP address for the machine in direct communication with the partner server, derived from the REMOTE_ADDR environment variable in the HTTP request header.
    The IP addresses may be in the quad-dotted, IPv4 address form, or in the ASCII IPv6 form.
    Note: Ensure that the IP address is the value of the REMOTE_ADDR environment variable from the HTTP request header, not the IP of the server making the request to Yahoo
  • xfip=HTTP_X_FORWARDED_FOR value (recommended), which is the client- proxy routing loop, derived from the HTTP_X_FORWARDED_FOR value in the HTTP request header.
    Note: Do not include xfip if there is no HTTP_X_FORWARDED_FOR environment variable.
  • ua=HTTP_USER_AGENT value (required), which is a character string that identifies the application, derived from the HTTP_USER_AGENT environment variable in the HTTP request header (such as Web browser or crawler type) used by the machine in direct communication with the partner server.
    Note: URL-encode the ua value before it is added to the overall affilData string.

maxCount

Available for Sponsored Search only

The maxCount parameter defines the maximum number of Sponsored Search results to return with each retrieval.

Note: The required minimum number of ads is 2.

Syntax¶

maxCount=max_listings_per_page