API - front end integration

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

Sorting Object

Results Object

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

Open

API Call

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

Open

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.

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

Response: Response is a JSON object sent back to the caller.

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

Click here for instructions on adding Hawksearch Event Tracking Code .