Table of Contents
Overview
The Hawksearch service enables online retailers and publishers the ability to drive a rich, compelling user experience. This experience drives visitors to the products and information that they are seeking.
Hawksearch provides the ability to power the product listing pages for categories and brand pages on the site in addition to driving the search page on the site. This document will cover integration between an existing site and Hawksearch to drive: Search Results and Landing Pages. The focus will be the API approach.
The Hawksearch Recommendation service requires tracking events from a user on your website. This document also describes the steps to install client side tracking on your website to send relevant data to the Recommendation engine.
Output Formats
The Hawksearch API provides three response formats. JSON, XML, and HTML are currently available.
Domains
Hawksearch has three environments available: Development, Staging/Test and a load-balanced Production. When performing integration, each engine can be accessed by using these domains:
Development Environment
When including the scripts below, please use the appropriate domains for the development environment.
Hawk URL: http://dev.hawksearch.net/
Tracking URL: http://tracking-dev.hawksearch.net/
Recommendations URL: http://recs-dev.hawksearch.net/Staging/Test Environment
When including the scripts below, please use the appropriate domains for the test environment.
Engine Reference URL: http://test.hawksearch.net/
Tracking URL: http://tracking-test.hawksearch.net/
Recommendations URL: http://recs-test.hawksearch.net/Production Environment
When including the scripts below, please use the following domain for the production/live environment.
Engine Reference URL: http://yourenginename.hawksearch.com/ Provided at time of launch.
Tracking URL: http://tracking.hawksearch.com/
Recommendations URL: http://recs.hawksearch.com/
Sample Hawksearch Engine
As reference, a sample Hawksearch engine exists to test out API usage. This engine exists at:
http://dev.hawksearch.net/sites/demo/
The associated User Interface can also be accessed at:
http://dev.hawksearch.net/sites/demo/_preview/preview.aspx
Query Hawksearch API
Query parameters can be utilized so that the engine returns back only the relevant content.
Keywords
Parameter Name: keyword
Description: The keyword parameter expects a word or phrase. The keyword value is utilized to execute a keyword search and will return results based on the matching words.
Example:
http://dev.hawksearch.net/sites/demo/?keyword=boots&hawkoutput=xml
Facets
Parameter Name: Depends on how it is configured
Description: The facet name is configured in the fields/facets area of the Hawksearch Dashboard. If used, the engine refines the results based on the facets selected. For example, if Patagonia is specified, the results will only show products that are from the Patagonia brand.
Example:
http://dev.hawksearch.net/sites/demo/?brand=patagonia&hawkoutput=xml
If you only wish to extract facet values for a specific facet like brand, category out from Hawksearch without requiring to receive any results or other components in the xml you can request that using the hawkfacets parameter in the URL. In this case the xml will only contain data for facet you requested for.
Example: For extracting facet values for a specific facet like brand:
http://dev.hawksearch.net/sites/demo/?hawkfacets=brand&hawkoutput=xml
Many Per Page
Parameter Name: mpp
Description: This value determines how many products to show per page. If mpp is not defined, it will default to 12 records per page.
Example:
http://dev.hawksearch.net/sites/demo/?pg=3&mpp=12&hawkoutput=xml
Page Number
Parameter Name: pg
Description: This value determines which page to show a result list. If mpp is not defined, it will default to 12 records per page. If pg is not defined, it will default to the first page.
Example:
http://dev.hawksearch.net/sites/demo/?pg=3&mpp=12&hawkoutput=xml
Sort
Parameter Name: sort
Description: This value determines how the list will be sorted. Relevance ranking will not apply if a sort value is defined. If sort is not defined, it will default to relevance ranking or a default sort order.
Example:
http://dev.hawksearch.net/sites/demo/?sort=salepriceasc&hawkoutput=xml
Search Within
Parameter Name: searchWithin
Description: This value can perform an additional keyword search within existing criteria.
Example:
http://dev.hawksearch.net/sites/demo/?searchWithin=blue& keyword=north+face&hawkoutput=xml
Content Type
Parameter Name: it
Description: This parameter is used to select which content type to show from Hawksearch. For example, this is used with displays tabs for products or content search.
Example:
http://dev.hawksearch.net/sites/demo/? keyword=patagonia&it=content&hawkoutput=xml
Output
Parameter Name: hawkoutput
Description: This parameter is to indicate what format the response should be. html, xml,json and custom are valid values. When using value custom all components will be returned as the html and you will have the option to request only items be returned in a certain format using the hawkitem list parameter as explained in the next section.
Example:
http://dev.hawksearch.net/sites/demo/? keyword=patagonia&it=content&hawkoutput=xml
API Response
JSON
Using the sample engine, you can access the JSON response via this URL:
http://dev.hawksearch.net/sites/demo/?hawkoutput=json
The JSON response includes:
Success
Pagination
Sorting
Results
Facets
Selections
Merchandising
Location
Target
DidYouMean
TrackingId
MetaRobots
HeaderTitle
MetaDescription
MetaKeywords
RelCanonical
FeaturedItems
Keyword
Original
PageLayoutId
SearchDuration
QueryUsedAllKeywords
API Response Examples below display what properties are returned for each element.
Pagination Object
Sorting Object
Results Object
Facets Object
Selections Object
"Selections": {
"department": {
"Label": "Department",
"Items": [
{
"Label": "Kids",
"Value": "Kids"
}
]
}
}
Merchandising Object
"Merchandising": {
"Items": [
{
"Zone": "BannerTop",
"Html": "<img border=\"0\" src=\"http://dev.hawksearch.net/assets/38/images.jpg\" alt=\"The North Face\" width=\"411\" height=\"123\" />"
}
]
}
Merchandising Object with Featured Items
"FeaturedItems":{
"Items":
[
{
"Zone":"FeaturedTop",
"Items":
[
{
"Score": 0.005307952,
"ItemName": "Logo Hat - The North Face",
"ImageURL": "/assets/1/14/DimThumbnail/{DE7A166C-24F5-453B-B970-
A30BD746C21D}.jpg",
"ImageAlt": "10187",
"Id": "Item_74303",
"CustomURL": "/products/logo-hat-the-north-face/",
"TrackingId": "1213044",
"Brand": "The North Face",
"Price": "18",
"SalePrice": "18",
"IsOnSale": false,
"BestFragment": "... - the <b>north<\/b> <b>face<\/b> the logo hat has the <b>north<\/b> <b>face<\/b> logo and '1968' embroidered on this washed cotton twill hat.<br> <br> men accessories hats & headwear specials sat dec 15th kids women accessories hats & headwear women hats & headwear caps men hats & headwear caps the <b>north<\/b> ...",
"MinPrice": "18",
"MaxPrice": "18",
"MinSalePrice": "0",
"MaxSalePrice": "0"
}
]
}
]
}
Location Object
If Location is not blank, a Redirect Rule generated a target URL for the visitor to go to.
"location": ""
XML
Using the sample engine, you can access the XML response via this URL:
http://dev.hawksearch.net/sites/demo/?hawkoutput=xml
The same objects appear, but formatted in XML.
HTML
Using the sample engine, you can access the pre-formatted HTML response via this URL:
http://dev.hawksearch.net/sites/demo/?hawkoutput=html
If the HTML format is utilized, also consider Hawksearch’s JavaScript UI integration for an easier integration.
Sample Queries
SAMPLE #1: “I searched for ‘jackets’ having two brands selected.”
Page URL
API Call
SAMPLE #2: “I searched for ‘parka’ that are on sale having the Patagonia brand selected.”
Page URL:
API Call
http://dev.hawksearch.net/sites/demo/?keyword=parka&brand=Patagonia&department=Sale&hawkoutput=xml
Spelling Suggestion/Spell Check
In the event that there are no search results returned for a particular keyword being searched for Hawksearch might return a spelling suggestion or spell check override( if you have one set up for the keyword in the Hawksearch backend) as part of the response returned from the API. Depending upon the format of requested API please check the xml or json value for the <DidYouMean> xml tag on xml responses or DidYouMean property on json response.
You can then choose to generate a link that you can use to display the suggested word to the site user or you can choose to redirect to the search page with the suggested keyword. Based on the requirements discussion of your site if we chose to return the search results for the corrected keyword in the event that we have a certain number (based on how we discuss the business rule) of minimum results for the original keyword automatically redirect to the search page with the corrected keyword then the response will be available on the API as follows.
Scenario 1 (Automatic Replacement)
User searches for “patagon” and we return results for “Patagonia”
Request Url to Hawksearch: http://dev.hawksearch.net/sites/demo?keyword=patagon
Response from Hawksearch for the fields related to this functionality:
<OriginalKeyword>patagon</OriginalKeyword>
<Keyword>patagonia</Keyword>
<DidYouMean></DidYouMean>
Scenario 2 (Request for Original Keyword)
User wants to see results for original keyword (Patagon) instead of replaced keyword (Patagonia)
Request Url to Hawksearch: http://dev.hawksearch.net/sites/demo?keyword=patagon&hawkspellcheck=0
Response from Hawksearch the fields related to this functionality:
<OriginalKeyword></OriginalKeyword>
<Keyword>patagon</Keyword>
<DidYouMean>patagonia</DidYouMean>
Scenario 3(Regular Request)
User searches for keyword and enough results are returned for original keyword
Request Url to Hawksearch: http://dev.hawksearch.net/sites/demo?keyword=coat
Response from Hawksearch for the fields related to this functionality:
<OriginalKeyword></OriginalKeyword>
<Keyword>coat</Keyword>
<DidYouMean></DidYouMean>
True Client IP and User Agent
In order to enable Hawksearch to track results correctly for your site and use the correct IP when tracking the results, please pass in the true client IP and the user-agent when you make the request to Hawksearch.
enginename is the engine ID provided by your Hawksearch Representative. If you don’t have your enginename, please contact your implementation team.
VB.Net Code Sample
Dim qs As URLParameters = New URLParameters(HttpContext.Current.Request.QueryString, "ajax;json;guid;PageId")
Dim HawkSearchUrl As String = “http://dev.hawksearch.net/sites/enginename”
Dim URL As String = HawkSearchUrl & "/" & qs.ToString()
Dim r As HttpWebRequest = WebRequest.Create(URL)
If Request IsNot Nothing Then
r.UserAgent = Request.UserAgent
r.Headers.Add("HTTP_TRUE_CLIENT_IP", Request.UserHostAddress)
End If
Dim myCache As New System.Net.CredentialCache()
myCache.Add(New Uri(URL), "Basic", New System.Net.NetworkCredential(AppSettings("WindowsAuthLogin"), AppSettings("WindowsAuthPassword")))
r.Credentials = myCache
Dim resp As System.Net.HttpWebResponse = r.GetResponse()
Dim sr As New System.IO.StreamReader(resp.GetResponseStream())
Dim html As String = sr.ReadToEnd()
sr.Close()
SEO
In order to improve SEO on the site please make sure the search page has been added to the robots.txt on your site and disallowed so search engines do not reach it. There should always be a no index/no follow on the search pages. For improving SEO functionality on the site for popular search terms ask us more about the SEO Booster functionality we offer.
NOTE: By default all major bots requests for SEARCH PAGES are blocked from being served by the hawksearch servers. The idea is to use landing pages for any custom category/brand/custom landing page that needs to be indexed by search engines. However if you have custom requirement where you still need the search page to be served for web crawlers please include the parameter below with the corresponding request to Hawksearch.
Request for Search
http://dev.hawksearch.net/sites/demo/?keyword=jackets1&hawkoutput=html&hawkrobots=allow
Request for Landing Page
http://dev.hawksearch.net/sites/demo/?lpurl=/accessory&hawkoutput=html&hawkrobots=allow
JavaScript Block
The following JavaScript needs to be installed on every page of your site. The block should look as follows. Please either adjust or add as needed. The enginename is the engine ID associated with your Hawksearch account. The ClientGuid is the Tracking Key associated with your account.
To lookup the Engine Name and Tracking Key for your account please look in the Hawksearch workbench under Admin >> Account Info.
<!-- Hawksearch Header Includes -->
<script type="text/javascript">
//<![CDATA[
(function (HawkSearch, undefined) {
HawkSearch.HawkUrl = 'http://dev.hawksearch.net/sites/enginename';
HawkSearch.TrackingUrl = 'http://tracking-dev.hawksearch.net';
HawkSearch.RecommenderUrl = 'http://recs-dev.hawksearch.net';
HawkSearch.ClientGuid = 'tracking_key';
if ("https:" == document.location.protocol) {
HawkSearch.HawkUrl = HawkSearch.HawkUrl.replace("http://", "https://");
HawkSearch.TrackingUrl = HawkSearch.TrackingUrl.replace("http://", "https://");
HawkSearch.RecommenderUrl = HawkSearch.RecommenderUrl.replace("http://", "https://");
}
}(window.HawkSearch = window.HawkSearch || {}));
var hawkJSScriptDoc = document.createElement("script");
hawkJSScriptDoc.async = true;
hawkJSScriptDoc.src = HawkSearch.HawkUrl + '/includes/hawksearch.min.js?v1.0';
var hawkJSTag = document.getElementsByTagName('script')[0];
hawkJSTag.parentNode.insertBefore(hawkJSScriptDoc, hawkJSTag);
var hawkCSSScriptDoc = document.createElement("link");
hawkCSSScriptDoc.setAttribute("rel", "stylesheet");
hawkCSSScriptDoc.setAttribute("type", "text/css");
hawkCSSScriptDoc.setAttribute("href", HawkSearch.HawkUrl + '/includes/hawksearch.css');
document.head.appendChild(hawkCSSScriptDoc);
//]]>
</script>
Auto-Complete for Search Results
Within the Hawksearch Workbench, settings can be modified to control what shows in the Auto-Complete section.
To enable it on your page, there are two steps:
Add the Auto-Complete JavaScript block to the end of the <BODY> tag.
textboxname is the ID of the search text box. Look to your existing HTML code to add the matching ID.
textboxnamefooter is the ID of the search text box if you have one on the footer. Look to your existing HTML code to add the matching ID.
<!-- Hawksearch - Auto-Suggest -->
<script type="text/javascript">
//<![CDATA[
HawkSearch.initAutoSuggest = function () {
HawkSearch.suggestInit('%%textboxname%%', {
lookupUrlPrefix: HawkSearch.HawkUrl + '/?fn=ajax&f=GetSuggestions',
hiddenDivName: '',
isAutoWidth: true
});
HawkSearch.suggestInit('%%textboxnamefooter%%', {
lookupUrlPrefix: HawkSearch.HawkUrl + '/?fn=ajax&f=GetSuggestions',
hiddenDivName: '',
isAbove: true
});
};
//]]>
</script>
Autocomplete Integration:
The autocomplete feature can be integrated through API similar to the search functionality. Hawksearch sends the response in JSON format which can be consumed by your website and displayed appropriately.
Request: GET request made through a URL built as follows:
https://DOMAIN_URL/ENGINE_NAME/?fn=ajax&f=GetSuggestions&q=KEYWORD&hawkoutput=json
Parameter | Description | Value |
|---|---|---|
fn | Indicates ajax request | ajax |
f | The function name to be called | GetSuggestions |
q | The keyword. This is the text typed by the user | user-entered alphanumeric value |
hawkoutput | Indicates the format of the response | json |
Response: Response is a JSON object sent back to the caller.
Parameter | DataType | Details |
|---|---|---|
Count | Numeric | Total products available for the keyword |
ContentCount | Numeric | Total content items available for the keyword |
Categories | Array of Category Objects | Every category object is a category suggestion: |
Products | Array of Product | Based on the request parameter DisplayFullResponse, the product object has all its fields output or the standard autocomplete format |
Content | Array of Content Item Objects | Array of content item objects with Value and url properties. |
Popular | Array of Popular Searches | Every popular search term object is an object with these two properties: |
SearchWebsiteUrl | Url | Base website url for clickable links. |
TrackingVersion | Alphanumeric text of size 2 | v1 or v2 based on your engine version |
KeywordField | Alphabetic | Parameter used to denote the keyword field |
CategoryHeading | Alphanumeric | Header text for Categories |
ContentHeading | Alphanumeric | Header text for Content Items |
ProductHeading | Alphanumeric | Header text for Products |
PopularHeading | Alphanumeric | Header text for Popular Searches |
ViewAllButtonLabel | Alphanumeric | Header text for “View All” link |
Example URLs for various environments as follows:
Environment | Environment URL |
|---|---|
Dev | https://dev.hawksearch.net/sites/demo/?fn=ajax&f=GetSuggestions&q=coat&hawkoutput=json |
Test | https://test.hawksearch.net/sites/demo/?fn=ajax&f=GetSuggestions&q=coat&hawkoutput=json |
Production | https://api.hawksearch.info/sites/demo/?fn=ajax&f=GetSuggestions&q=coat&hawkoutput=json Note: if you have been provided with a custom domain such as yoursite.hawksearch.com, please replace api.hawksearch.info in the above url with your custom domain URL. |
HTTP/Keep-Alive
In the event that you see unexpected timeout errors from the site when testing, please confirm your http web request settings for the request you make to hawksearch. In some cases, the clients reset the connection instead of leaving it in Time_Wait/Close_Wait causing IIS to log it as an interruption. In this scenario please force the request to be Http 1.0 with no keep alive and see if timeouts no longer appear.
Event Tracking Code
NOTE: In order to populate data in the Hawksearch Reports, and to leverage Personalized Search, it is CRITICAL to implement Tracking Integration.
Click here for instructions on adding Hawksearch Event Tracking Code .