API - front end integration

This information is for older versions of Hawksearch and not the latest v4.0. This is not compatible with the Search Api or Indexing Api. Please contact Hawksearch for more information

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:

  1. 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/

  2. 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/

  3. 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-na.hawksearch.com/
    Recommendations URL: http://recs-na.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

 

"Pagination": { "NofResults": 173, "CurrentPage": 1, "Items": [ { "Label": "12 Items Per Page", "PageSize": 12, "IsDefault": true, "Selected": true }, { "Label": "24 Items Per Page", "PageSize": 24, "IsDefault": false, "Selected": false }, { "Label": "36 Items Per Page", "PageSize": 36, "IsDefault": false, "Selected": false }, { "Label": "72 Items Per Page", "PageSize": 72, "IsDefault": false, "Selected": false } ], "MaxPerPage": 12, "NofPages": 15 }

 

Sorting Object

"Sorting": { "Value": "score", "Items": [ { "Label": "Best Match", "Value": "score", "IsDefault": true, "Selected": true }, { "Label": "Price: Lowest to Highest", "Value": "salepriceasc", "IsDefault": false, "Selected": false }, { "Label": "Price: Highest to Lowest", "Value": "salepricedesc", "IsDefault": false, "Selected": false } ] }

 

Results Object

"Results": [ { "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 &#39;1968&#39; embroidered on this washed cotton twill hat.&#60;br&#62; &#60;br&#62; 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" }, { "Score": 7.017364E-4, "ItemName": "Baby Llama Beanie", "ImageURL": "/assets/1/14/DimThumbnail/The-North-Face-Baby-Llama-Beanie-jake-blue.jpg", "ImageAlt": "Llama", "Id": "Item_118551", "CustomURL": "/products/baby-llama-beanie-/", "TrackingId": "1213044", "Brand": "The North Face", "Price": "25", "SalePrice": "11.97", "IsOnSale": true, "BestFragment": "... design, the <b>north<\/b> <b>face<\/b> baby llama beanie is about the cutest thing you can pull on your baby&#39;s head. made from lightweight acrylic fibers, this <b>north<\/b> <b>face<\/b> hat has a fleece ear band for extra warmth and a soft feel against the skin.&#60;&#47;div&#62;&#60;div&#62;&#38;nbsp&#59;&#60;&#47;div&#62;&#60;&#47;div&#62;&#60;&#47;div&#62; ...", "MinPrice": "25", "MaxPrice": "25", "MinSalePrice": "11.97", "MaxSalePrice": "11.97" } ]

 

Facets Object

 

Selections Object

Merchandising Object

 Merchandising Object with Featured Items

Location Object

If Location is not blank, a Redirect Rule generated a target URL for the visitor to go to.


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

http://dev.hawksearch.net/sites/demo/_preview/preview.aspx?keyword=jackets&brand=Burton,Columbia%20Sportswear

API Call

http://dev.hawksearch.net/sites/demo/?keyword=jackets&brand=Burton,Columbia%20Sportswear&hawkoutput=json

SAMPLE #2: “I searched for ‘parka’ that are on sale having the Patagonia brand selected.”

Page URL:

http://dev.hawksearch.net/sites/demo/_preview/preview.aspx?keyword=parka&brand=Patagonia&department=Sale

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


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.


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:

  1. 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.

 

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

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

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:
Value - Name of the category
Url - navigation url

Products

Array of Product
Objects

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
Objects

Every popular search term object is an object with these two properties:
Value - Name of the category
Url - navigation url

SearchWebsiteUrl

Url

Base website url for clickable links.
Appended to the Urls present in other object arrays.

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:


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 .