Querying for Content

Once the CoBrand ID and SubDomain information are in place, the site is ready to submit its first request in a Query URL along with the appropriate HTTP Headers.

The Query URL consists of a Base URL and Parameters and sends a standard HTTP GET request to the InfoSpace servers, which in return sends results as a UTF-8 encoded XML response.


HTTP Headers

The HTTP Headers pass information about the user and the request to assist in the following:

  • Increased quality of ads and results
  • Spam identification and mitigation
  • Automatically localizing results

It also passes required information, such as:

  • User Agent
  • Referrer
  • X-forwarded-for

Note: this should not be the request header of the server making the call to InfoSpace.

Implementation Steps

  1. Include all of the HTTP request header fields from the end user’s request. User-Agent, Referrer & X-forwarded-for fields are all required, however, passing all user request header fields is recommended to assist with features such as Auto-Localization.
  2. Make sure the headers are properly formatted, paying close attention that all header fields are separated by a new line. Guidelines can be found at:  http://www.w3.org/Protocols/HTTP/HTRQ_Headers.html
  3. Correctly URI encode all the request header fields including white space and carriage returns.
  4. The complete request header from the end user must be URI encoded and passed in the request header to the API in a new header field named 'x-insp-user-headers'

Example User-Request Headers

Host: www.partnersite.com
User-Agent: Mozilla/5.0 (Windows NT 6.1; WOW64; rv:16.0) Gecko/20100101 Firefox/16.0
Accept: text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8
Accept-Language: en-US,en;q=0.5
Accept-Encoding: gzip, deflate
Referrer: www.referringsite.com
X-forwarded-for: 1.1.1.1, 2.2.2.2, 3.3.3.3

Example Encoded User-Request Headers

X-Insp-User-Headers: Host%3A%20www.partnersite.com%0AUser-Agent%3A%20Mozilla%2F5.0%20(Windows%20NT%206.1%3B%20WOW64%3B%20rv%3A16.0)%20Gecko%2F20100101%20Firefox%2F16.0%0AAccept%3A%20text%2Fhtml%2Capplication%2Fxhtml%2Bxml%2Capplication%2Fxml%3Bq%3D0.9%2C*%2F*%3Bq%3D0.8%0AAccept-Language%3A%20en-US%2Cen%3Bq%3D0.5%0AAccept-Encoding%3A%20gzip%2C%20deflate%0AReferrer%3A%20www.referringsite.com%0AX-forwarded-for%3A%201.1.1.1%2C%202.2.2.2%2C%203.3.3.3%0A

The Base URL

The Base URL can be thought of as the delivery mechanism for the query request. The Base URL consists of a Partner SubDomain, an infospace.com URL, the CoBrand ID, ‘wsapi’ (a path parameter to the search API) and a request for results.

It is possible for partners to have more than one CoBrand ID for reporting purposes. If a site has more than one CoBrand ID, the site must determine which CoBrand ID to include in the query.

The format of the Base URL is:

[partner subdomain].infospace.com/[cobrand id]/wsapi/results?

An example of a fictitious Base URL, given the SubDomain of ‘partnercompanyinc’ and the CoBrand ID of ‘partnerco’, would look like:

http://partnercompanyinc.infospace.com/partnerco/wsapi/results?

Using Parameters

Parameters are added after the Base URL and are preceded by an ampersand ‘&’. Parameters are expressed as 'Name=Value' pairs with no white spaces.

There is no specific order to where a parameter must appear. This means the 'enduserip' parameter may be given as the first, last or middle parameter and it would make no difference to the query engine so long as it’s present and the value is correct.

Parameters values must be URI encoded.

An example request searching for ‘cars’, in the web category, with the return set beginning with the twenty-first item, would look like:

http://partnercompanyinc.infospace.com/partnerco/wsapi/results?&query=cars&category=web&qi=21&enduserip=71.164.114.232&X-Insp-User-Headers=USER-AGENT%3A%20Mozilla%2F5.0%20(Windows%20NT%206.1%3B%20WOW64%3B%20rv%3A10.0.2)%20Gecko%2F20100101%20Firefox%2F10.0.2%0Areferer%3A%20http%3A%2F%2Fwww.somewebsite.com%2Fsearch.php%3Fq%3Dkelly%2Bclarkson%0A&signature=SIGNATURE_VALUE

In this case the query string is a single word so no URI encoding was added, notice the 'x-insp-user-headers' parameter is URI encoded. Had the query been for, ‘Blue Cars’ the query parameter would have looked like, '&query=Blue%20Cars'.

Parameter List

Parameter Summary Accepted values Default Notes
query The user’s search query. string, no limit none (required field) All query requests should be encoded in UTF-8. XML responses will be UTF-8 encoded.
Empty queries will result in an error.
enduserip IP of user requesting partner’s search results. Valid IP
(xxx.xxx.xxx.xxx)
none (required field) When sending a URL query string to InfoSpace, the query must provide the IP address of the end user requesting the results using the enduserip parameter. This value cannot be a hard coded value; it must be the actual end user IP.
Note: ensure that internal IP addresses are not passed – a common error during setup.
category Sets the category for the user’s search. web, images, video, news web The category parameter allows the site to specify what type of results to return. The categories are typically web, images, video and news. By setting this parameter the site can request return items of a specific type. Sites typically have a category bar in header area to allow the user to select a certain category for their search.
qi Sets the start position of a partner’s non-paid results set for that call. (See Pagination) Integer 1 The qi parameter is used in pagination and allows the site to request a specific set of returned items. The number of items per page returned is set by the partner site. The qi parameter allows the site to specify the starting position in the non-paid return set of items to be returned. For example if a site displays 10 items per page, to get the third page of results the qi parameter would be set to 21 to get items 21 through 30.
refinement Requests related search suggestions. (See Related Searches) related none The refinement parameter is used to request additional phrases or terms related to the user’s query.
Note: the CoBrand settings must first have the Related Searches feature enabled.
signature Encoded hashed value of time-stamp, access key, and query string. string none The order of query string parameters in the URL must not be changed, the order that is signed must be the order that is sent in the request URL. For more info see Access Keys

Next: The Result Set
Back to: Access Keys