InfoSpace - Implementation
SDK Home | Client Side Results SDK - Home
Page last modified: 24 Apr 2017

IMPLEMENTATION STEPS

After your web server has calculated the signature token using the access key, the web page returned to the browser client will include a few lines of JavaScript required to request and render search results.

Include Reference to InfoSpace JS

In your web application include a reference to InfoSpace’s client-side search results JS in the head tag, the JS includes configuration settings specific to your cobrand.

<script type="text/javascript" src="//csr.inspsearchapi.com/lib/infospace.search.js">
</script>

Construct Page Elements

The InfoSpace JS will execute an asynchronous client-side call to InfoSpace for search results, and the JSON response will be used by the InfoSpace JS to build the page markup that makes up the Search modules. All search results will render simultaneously on the page. For each search results container include a <div> on the page where it should appear. For each <div> include the id that matches the containers specified in the doSearch() call. Example HTML:

<div id="topResults"></div>
<div id="bottomResults"></div>
<div id="relatedResults"></div>
<div id="mainResults"></div>

Configure doSearch Request

The parameters you include in the doSearch call will be passed to InfoSpace’s search service to retrieve search results.

Important: Include the script block to call insp.search.doSearch(), as seen in the below example, just before the closing </body> tag of your page.

Note: You cannot call doSearch() from the document ready event or from jQuery. The doSearch() call must be embedded in your html page, preferably just before the closing </body> tag.

Example doSearch call and parameters

Note: to see an example with customized styles, see the “Customize Styles of Search Results” section below.

<script type="text/javascript">
   insp.search.doSearch({
     query: 'pizza',  // take care to encode the query term properly, refer to Best Practices Tip #7
     accessId: 'site.segment',
     signature: 'gd3Qjqhd_ye8jo4e7WFBANCFYs4',
     page: 2,
     containers: {
       'top': {id:'topResults'},
       'main': {id:'mainResults'},
       'bottom': {id:'bottomResults'},
       'right': {id:'rightResults'},
       'related': {id:'relatedResults'},
       'spelling': {id:'spellSuggestResults'}
     }
   });
</script>

Key Parameters

Key Description Accepted Values Default
query The user’s search query. Ensure that this is the same exact query term that was used to generate the signature value below. String Required
accessId Work with your Partnership Manager to obtain your accessId. This field also contains the segment used for desktops. For more information, refer to the accessId documentation. String Required
signature Encoded hashed value of timestamp, access key, and query terms. Refer to Best Practices Tip #7 for how to generate this properly String Required
page Sets the page for a partner’s organic or non-paid search results set for that call. Integer. Must be >= 1 Required
containers Mapping of Infospace search results containers (top, main, bottom, right, related) to partner’s `<div>` tags. String for each container Required
category Sets the category for the user’s search. web, images, video, news, shopping web
deviceSegments Specifies which segment to use when searching with a device other than a desktop. Currently, supported devices are mobile and tablet. Object Optional
clickTrackingUrl This is the URL that will contain the information you want to receive on a end-user click. For more information on this topic, refer to this section.
Limit the length of the URL to 1000 chars or less.
String Optional
adLinesCount This parameter specifies how many lines to use to display the ads. Integer. Valid values are: 1, 2, or 3 3
sellerRatings If this is set to true, seller ratings are displayed for the ads. Boolean true
sellerFirstLayout This enables or disables the "Seller First Layout" feature. When enabled, it overrides anything set for the siteLinks key. Boolean false
siteLinks This specifies how site links will be display (if at all). String. Valid values are: 'oneLine', 'all' or 'none' 'all'
linkTarget Specifies how clicks are opened, whether they are opened in a new tab or not. Note: The linkTarget parameter applies to ads and results:
  • Set the value to _blank to bring up a new page when any link on the page is clicked.
  • Set the value to _top to use the same page when any link on the page is clicked.
String, valid values: '_blank' or '_top' '_blank'
country Specifies the country to be targeted when requesting results (refer to the table Additional Information at the bottom of this page). String, example values: 'us', 'uk', 'es' 'us'
language Specifies the language to be targeted when requesting results (refer to the table under Additional Information at the bottom of this page). String, example values: 'en', 'fr', 'es' 'en'
adultFilter Specifies whether or not you want adult content returned. "on" or "off" Optional
searchUrlFormat This parameter specifies a tokenized string that directs the user to your SERP page. This is used when an end-user clicks on a related search or a spelling suggest link. The token is {searchTerm}. As an example, “/search/Web?q={searchTerm}” String Optional, but required if you have related search or spell suggest results
isTest Used to indicate to content providers that the request is a test and should not be included in revenue collection. Boolean false
onComplete This callback is invoked once the results have been rendered. It will contain additional information about the results that were returned. Further details will be forthcoming. JavaScript callback Optional
onError If there are any errors or warnings that occurred during the call, this callback will be invoked with a list of those errors and warnings. JavaScript callback Optional

deviceSegments

In order to specify different segments based on the device type, use the deviceSegments optional parameter. Supported devices include mobile and tablet. Here is an example of how this would work:

  accessID: 'dogpile.info.dogpl',   // required field that specifies the segment for desktops
  deviceSegments: { mobile: 'info.dogpl.mobile', tablet: 'info.dogpl.tablet' }

onComplete() Callback

Property Description
maxAlgoResultCount The field contains the estimated number of algo results based on the provided query. This will be zero (0) if there were no results from the query term.
maxAlgoPage The estimated maximum page of algo results, based on maxAlgoResultCount and the 'main' group layout. This will be one (1) if algo result count or the 'main' group layout are undefined or zero.
mainResultCount This will contain the number of algo results displayed in the main region.
topResultCount This is the number of ads displayed in the top region.
bottomResultCount This is the number of ads displayed in the bottom region.
relatedResultCount This is the number of ads displayed in the related region.
adDisplayUrls This contains the list of display URLs of the ads rendered on the page.

The following snippet of code is an example of onComplete() usage in a call to doSearch() that displays the string No results returned for the provided query. when no results are returned for a query.

  onComplete: function(details) {
    if (details) {
      if (details['maxAlgoResultCount'] == 0) {
        var pageLevelDiv = document.getElementById('pageLevelDiv');
        var noResultsDiv = document.createElement('div');
        noResultsDiv.innerHTML = '<span>No results returned for the provided query.</span>';
        pageLevelDiv.appendChild(noResultsDiv);
      }
    }
  },

The onComplete() functionality can also be used to implement pagination. The following snippet of code is an example to generate links for additional pages of results.

  onComplete: function(details) {
      var maxPagesToShow = 10;
      var paginationHtml = "";
      for (var i = 1; i <= Math.min(maxPagesToShow, details.maxAlgoPage); ++i) {
          var link = ' | <a href="/search?q=' + query + '&page=' + i + '">' + i + '</a>';
          paginationHtml = paginationHtml + link;
      }
      $('#pagination').html(paginationHtml);
    }

The following onComplete() snippet shows how to display what the adDisplayUrls array contains. This enables developers to write code to process this data in whatever fashion they want. Note that this pattern of code can be used for other properties of the details object passed into this function.

  onComplete: function(details) {
        if (details) {
            alert(JSON.stringify(details.adDisplayUrls));
        }
    }

The code above will generate an alert popup window containing data that will something look like this:

  [{"provider":"google","url":"www.acme.com/"} ,
   {"provider":"yahoo","url":"www.someplaceelse.com/"},
   {"provider":"yahoo","url":"www.anothersite.com/"},
   {"provider":"yahoo","url":"www.mysite.com/"}]

Customize Styles of Search Results

Partners have the option to customize the style of search results for each container separately in the doSearch request. Note that styling is optional, if not specified then search results will be rendered with default style.

General Constraints

When providing the style overrides, there are some constraints in how the values should be passed to doSearch():

  • Color formats should not use the # character to prefix the hexadecimal values. So:
    • 'fbf' and 'ffbbff' are valid
    • '#fbf' and '#ffbbff' are not valid, and will be ignored
  • Font size values should not use px, so:
    • 12 and '12' are valid
    • '12px' is not valid, and will be ignored
  • Width values should use px, so:
    • '200px' is valid
    • 200 and '200' are not valid, and will be ignored

Belly Ad Style Notes

What are Belly Ads

Partners may blend paid results with their algorithmic results on their Web vertical in what’s called a Belly Ad layout. Those paid results are called Belly Ads. To use this layout, Belly Ads must be configured by a Partnership Manager, and the “main” results region/container must be implemented on the page. Policy restrictions apply.

Note: You must implement the “main” region/container on your results page before a Partnership Manager will configure Belly Ads in your feed.

Belly Ad Attribution

  1. Each Belly Ad will include an inline Ad Attribution.

Belly Ad Shading

  1. Background shading for Belly Ads is mandatory. In other words, the background color of the belly ads must be different than the background color of the algorithmic results.
  2. The backgroundColor value specified in the styles for the top container will automatically be applied to Belly Ads.
  3. If the backgroundColor specified for the top container is the same as the backgroundColor specified for the main container, the default belly ad background color (#F5FAFF) will be applied instead.
  4. If there is NO backgroundColor specified for the top container, the default belly ad background color (#F5FAFF) will be applied.

Example

Example doSearch request with some styles specified to be different than the defaults.

<script type="text/javascript">
  insp.search.doSearch({
    query: 'pizza',
    accessId: 'dogpile.info.dogpl',
    signature: 'gd3Qjqhd_ye8jo4e7WFBANCFYs4',
  category: 'web',
  page: 1,
    containers: {
      'top': {
      id:'topResults',
      styles:{
        'fontFamily': 'Tahoma',
        'backgroundColor': '#F5FAFF' 
      }
    },
    'main': {
      id:'mainResults',
      styles:{
    'fontFamily': 'Tahoma',
         'backgroundColor': '#FFFFFF'
      }
    },
    'bottom': {
      id:'bottomResults',
      styles:{
        'fontFamily': 'Tahoma',
        'backgroundColor': '#F5FAFF' 
      }
    },
    'right': {
      id:'rightResults',
      styles:{
        'fontFamily': 'Tahoma'
      }
    },
    'related': {
      id:'relatedResults',
      styles:{
        'fontFamily': 'Tahoma'
      }
    }
  },
  searchUrlFormat: '/search/Web?q={searchTerm}'
  )};
</script>

Key Parameters for Top, Main, Bottom, and Right Containers

Key Description Accepted Values Default
fontFamily Font family applied to all search results. Font list restricted by our search partners. Arial, Times New Roman, Verdana, Tahoma, Georgia, Trebuchet MS, Roboto, Helvetica Neue Arial
titleFontSize Font size for the search result title, typically larger than other result elements. 8 to 16 16
titleColor Font color for the search result title. 000000 to FFFFFF 1122cc
titleUnderline Turns underlining on or off for the title of the region. true or false true
urlFontSize Font size for the search result’s display URL. 8 to 16 13
urlColor Font color for the search results' display URL. 000000 to FFFFFF 009933
textFontSize Font size for the search results' description text. 8 to 16 13
textColor Font color for the search result’s description text. 000000 to FFFFFF 000000
rolloverLinkColor Sets the title color for the ad title, display url, and site links. 000000 to FFFFFF None
titleBold Turns bolding on or off for the title of the region. true or false false
smallColor Font color for small text like search result provider and result date. 000000 to FFFFFF 999999
backgroundColor Background color for a search results container (used for ad shading) 000000 to FFFFFF FFFFFF
width Width of the `<div>` container. String

Key Parameters for Related Container

Key Description Accepted Values Default
fontFamily Font family applied to related search terms. Arial, Times New Roman, Verdana, Tahoma, Georgia, Trebuchet MS, Roboto, Helvetica Neue Arial
fontSize Font size for the related search terms. 8 to 16 13
fontColor Font color for the related search terms. 000000 to FFFFFF 1122CC

Key Parameters for Spell Suggest Container

Key Description Accepted Values Default
fontFamily Font family applied to spell suggest search terms. Arial, Times New Roman, Verdana, Tahoma, Georgia, Trebuchet MS, Roboto, Helvetica Neue Arial
fontSize Font size for the spell suggest search terms. 8 to 16 12
fontColor Font color for the spell suggest search terms. 000000 to FFFFFF 1122CC

Additional Information

Allowed Country and Language Values

Language Country Code Language Code
Arabic ae, bh, dz, eh, eg, er, iq, jo, km, kw, lb, ly, mr, om, ps, qa, sa, so, tn, ye ar
Bulgarian bg bg
Chinese (China) cn zh_CN
Chinese (Taiwan) tw zh_TW
Croatian hr hr
Czech cz cs
Danish dk da
Dutch nl
English ag, ai, aq, au, bb, bd, bm, bn, bs, ca, cc, ck, cm, cx, dm, fk, fj, fm, gd, gg, gi, gm, gs, gu, gy, id, ie, im, in, je, jm, ke, ki, kn, ky, lc, lk, lr, ls, mh, ms, mt, mv, my, nf, ng, np, nr, nu, nz, pg, pn, sb, sc, sg, sh, sl, ss, sz, tc, tk, to, tt, tv, tz, ug, uk, us, vc, vg, vi, vu, ws, za, zm, zw en
Finnish fi fi
French bf, bi, bj, cd, cf, cg, ci, dj, fr, ga, gf, gn, ht, kh, ma, mc, mg, ml, mq, mu, nc, ne, pf, pm, re, rw, sn, td, tf, tg, wf, yt fr
German at, ch, de, lt, lu, na de
Greek cy, gr el
Hebrew il iw
Hungarian hu hu
Italian it, sm, va it
Japanese jp ja
Korean kr ko
Norwegian no, sj no
Polish pl pl
Portuguese ao, br, cv, gw, mz, pt, st pt
Romanian ro ro
Russian by, ge, kg, kz, lv, md, ru, tj, tm, uz ru
Serbian cs, rs, sr sr
Slovak sk sk
Spanish ar, aw, bo, bz, do, cl, co, cr, ec, es, gp, gt, gq, hn, mx, ni, pa, pe, pr, py, sv, uy, ve es
Swedish ax, se sv
Thai th th
Turkish mk, mn, tr tr