Hawksearch Versions: Hawksearch V4.0. Additional implementation changes might be needed to use this feature.
Note: Geolocation Search feature is already available for Hawksearch v4.0L clients. Please contact your Client Success Director for details and implementation.
Search: Dashboard Configuration
We have added a new range facet option - a Distance facet type which allows our customers to narrow down a list of results and sort them by distance within a chosen range. Your site visitors can now search by a zip code and get back list of relevant search results. This functionality will allow them to see the store location/products available in the physical location closest to them.
Fields
The first step to setting up Geolocation Search is to add a location field to your attribute.txt file and add a Location field under Workbench → Data Configuration → Fields. Make sure that this field is saved as a GeoPoint Value as shown below:
More information about setting up Fields can be found here.
Once the field is set up, the next step is adding a Distance facet.
Facets
Distance facet falls under the Range facet type. A Location field needs to be passed to Hawksearch in feeds. Use the following configuration to set up a Geolocation Search facet:
You can choose preferred Distance Unit Type:
And Distance Calculation Type:
An Arc length is the distance between two points along a section of a curve
A Plane length is a flat surface with no thickness
Also, distance range facet values need to be set up:
More information about setting up Facets can be found here.
Setting Up Sorting Set for Distance Facet
Geolocation Search should be set up as a separate sorting set as it will only apply when a user is searching by zip code.
To define a Nearest option – please select sorting value with an option ‘Sort By’ equal to Asc
To define a Farthest option – please select sorting value with an option ‘Sort By’ equal to Desc
In a display rule a condition needs to be added to trigger this sorting set. We want to use this sorting set, only when a distance facet selection is made.
Display rule is defined as: Location is not {{empty}}
Sample setup:
For more information, please follow instructions on sorting sets refinement: Sorting/Pagination
Implementation Details
Note: Please review this article if you are not sure where to find your client guid.
Sorting
Example:
Example
"Sorting": {
"Items": [
{
"Label": "Nearest",
"Value": "Nearest",
"IsDefault": true,
"Selected": false
},
{
"Label": "Farthest",
"Value": "Farthest",
"IsDefault": false,
"Selected": true
}
]
}
Indexing Geo Location
Attribute file must contain latitude and longitude information for each item.
After fields configuration, the index needs to be rebuilt.
Put a ‘lat’ and ‘long’ values for the fields defined as geolocation:
v2/indexing/index-items:
Example:
{
"IndexName": "XXXXXXXXXXXXXXXX",
"Items": [
{
"id": [
"1"
],
"title": [
"Testing Geo"
],
"location": [
{
"lat": "42.09975", //Chicago coordinates
"lon": "-87.7809"
}
]
//other attributes
}
]
}
Searching within a Radius
Sorting Sets
Example:
Example
"Sorting": {
"Items": [
{
"Label": "Nearest",
"Value": "Nearest",
"IsDefault": true,
"Selected": false
},
{
"Label": "Farthest",
"Value": "Farthest",
"IsDefault": false,
"Selected": true
}
]
}
Use ‘Origin’ to provide your current location. Let’s say you are currently in Europe
Sample 1 – Get overall Geo Location Facet Values
v2/search:
Example
{
"IndexName": "XXXXXXXXXXXXXXXX",
"ClientGuid": "SPECIFY YOUR CLIENT GUID HERE"
}
Go over the ‘Facet’ object in the response and look for the geo location facet, to see how many documents are indexed:
Example
"Facets": [
{
"FacetId": 165084,
"Name": "Distance",
"Field": "location",
"FieldType": "range",
"FacetType": "checkbox",
"DataType": "geopoint",
...
"Ranges": [
{
"Label": "Within 100 miles",
"Value": "1",
"IsNumeric": false,
"UBound": "100"
},
{
"Label": "Within 500 miles",
"Value": "2",
"IsNumeric": false,
"UBound": "500"
},
{
"Label": "Within 1000 miles",
"Value": "3",
"IsNumeric": false,
"UBound": "1000"
},
{
"Label": "Within 1000+ miles",
"Value": "4",
"IsNumeric": false,
"UBound": "10000000"
}
],
"Values": [
{
"Label": "Within 1000 miles",
"Value": "3",
"Count": 3,
"Selected": false
},
{
"Label": "Within 1000+ miles",
"Value": "4",
"Count": 4,
"Selected": false
}
],
"HiddenValues": [],
"ShowFacetCount": false
},...
Sample 2 – Including Facet Selection ‘less than 100km’
Distance between Niece and Paris is less than 100km, so the current facet selection will return the result
v2/search:
Example
"ClientGuid": "SPECIFY YOUR CLIENT GUID HERE",
"ClientData": {
"Origin": {
"Latitude": "43.675819", // France, Niece
"Longitude": "7.289429"
}
},
"FacetSelections": {
"location": [
"3"
]
}
}
Response:
Facets object:
Example
{
"FacetId": 165084,
"Name": "Distance",
"Field": "location",
"FieldType": "range",
"FacetType": "distance",
"DataType": "geopoint",
…
"Ranges": [
{
"Label": "Within 100 miles",
"Value": "1",
"IsNumeric": false,
"UBound": "100"
},
{
"Label": "Within 500 miles",
"Value": "2",
"IsNumeric": false,
"UBound": "500"
},
{
"Label": "Within 1000 miles",
"Value": "3",
"IsNumeric": false,
"UBound": "1000"
},
{
"Label": "Within 1000+ miles",
"Value": "4",
"IsNumeric": false,
"UBound": "10000000"
}
],
"Values": [
{
"Label": "Within 1000 miles",
"Value": "3",
"Count": 1,
"Selected": true
}
],
"HiddenValues": [],
"ShowFacetCount": false
}
Results:
Example
"Results": [
{
"DocId": "4",
"Score": 3.0,
"Document": {
"id": [
"4"
],
"title": [
"Testing GeoLocation Paris"
],
"itemname": [
"Testing GeoLocation Paris"
],
"location": [
{
"lon": 2.349014,
"lat": 48.864716
}
],
"title_test_copy": [
"Testing GeoLocation Paris"
],
"distance": [
{
"location": 429.36060401011923,
"unit": "Miles"
}
]
},
"BestFragments": {
"itemname": "Testing GeoLocation Paris",
"title": "Testing GeoLocation Paris"
},
"IsPin": false,
"IsVisible": true
}
]
Sample 3 – Including Facet Selection ‘more than 1000km’
Distance between Niece and US cities is more than 1000 km, so the current facet selection will return the Europe and US results.
v2/search:
Example
"ClientGuid": "SPECIFY YOUR CLIENT GUID HERE",
"ClientData": {
"Origin": {
"Latitude": "43.675819", //France, Niece
"Longitude": "7.289429"
}
},
"FacetSelections": {
"location": [
"4"
]
}
}
Results:
Example
"Results": [
{
"DocId": "4",
"Score": 3.0,
"Document": {
"id": [
"4"
],
"title": [
"Testing GeoLocation Paris"
],
"itemname": [
"Testing GeoLocation Paris"
],
"location": [
{
"lon": 2.349014,
"lat": 48.864716
}
],
"distance": [
{
"location": 429.36060401011923,
"unit": "Miles"
}
]
},
"BestFragments": {
"itemname": "Testing GeoLocation Paris",
"title": "Testing GeoLocation Paris"
},
"IsPin": false,
"IsVisible": true
},
{
"DocId": "3",
"Score": 3.0,
"Document": {
"id": [
"3"
],
"title": [
"Testing GeoLocation Kenosha, WI"
],
"itemname": [
"Testing GeoLocation Kenosha, WI"
],
"location": [
{
"lon": -87.822899,
"lat": 42.588081
}
],
"distance": [
{
"location": 4506.9174631212691,
"unit": "Miles"
}
]
},
"BestFragments": {
"itemname": "Testing GeoLocation Kenosha, WI",
"title": "Testing GeoLocation Kenosha, WI"
},
"IsPin": false,
"IsVisible": true
},
{
"DocId": "7",
"Score": 3.0,
"Document": {
"id": [
"7"
],
"title": [
"Testing GeoLocation Kenosha 2, WI"
],
"itemname": [
"Testing GeoLocation Kenosha 2, WI"
],
"location": [
{
"lon": -87.94244,
"lat": 42.62502
}
],
"distance": [
{
"location": 4510.1909999873233,
"unit": "Miles"
}
]
},
"BestFragments": {
"itemname": "Testing GeoLocation Kenosha 2, WI",
"title": "Testing GeoLocation Kenosha 2, WI"
},
"IsPin": false,
"IsVisible": true
},
{
"DocId": "6",
"Score": 3.0,
"Document": {
"id": [
"6"
],
"title": [
"Testing GeoLocation Pleaseant Prairie, WI"
],
"itemname": [
"Testing GeoLocation Pleaseant Prairie, WI"
],
"location": [
{
"lon": -87.93434,
"lat": 42.5385
}
],
"distance": [
{
"location": 4513.507854383739,
"unit": "Miles"
}
]
},
"BestFragments": {
"itemname": "Testing GeoLocation Pleaseant Prairie, WI",
"title": "Testing GeoLocation Pleaseant Prairie, WI"
},
"IsPin": false,
"IsVisible": true
}
...
]
Sample 4 – Including Facet Selection Returns no Results
There are no documents indexed with the 100 miles radius around Warsaw
v2/search:
Example
{
"IndexName": "XXXXXXXXXXXXXXXX",
"ClientGuid": "SPECIFY YOUR CLIENT GUID HERE",
"ClientData": {
"Origin": {
"Latitude": "52.237049", //Warsaw, Poland coordinates
"Longitude": "21.017532"
}
},
"FacetSelections": {
"location": [
"1"
]
}
}
Response:
Example
{
"Facets": [...],
"VisitorTargets": [...],
"TrackingId": "a13668e9-fd37-4969-980e-17aeec0f5f86",
"Success": true,
"Pagination": {
"NofResults": 0,
"CurrentPage": 1,
"MaxPerPage": 12,
"NofPages": 0,
...
}
...
}
Sample 5 – Including Facet Selection and Sorting by Nearest Location
In this example ‘Nearest’ is a default option of the sorting set. The results are sorted by the nearest.
v2/search:
Example
{
"IndexName": "XXXXXXXXXXXXXXXX",
"ClientGuid": "SPECIFY YOUR CLIENT GUID HERE",
"ClientData": {
"Origin": {
"Latitude": "43.675819", // France, Niece
"Longitude": "7.289429"
}
},
"FacetSelections": {
"location": [
"4"
]
}
}
Results:
Example
"Results": [
{
"DocId": "4",
"Score": 2.0,
"Document": {
"id": [
"4"
],
"title": [
"Testing GeoLocation Paris"
],
"location": [
{
"lon": 2.349014,
"lat": 48.864716
}
],
"title_test_copy": [
"Testing GeoLocation Paris"
]
},
"BestFragments": {
"title": "Testing GeoLocation Paris"
},
"IsPin": false,
"IsVisible": true
},
{
"DocId": "3",
"Score": 2.0,
"Document": {
"id": [
"3"
],
"title": [
"Testing GeoLocation Kenosha, WI"
],
"location": [
{
"lon": -87.822899,
"lat": 42.588081
}
],
"title_test_copy": [
"Testing GeoLocation Kenosha, WI"
]
},
"BestFragments": {
"title": "Testing GeoLocation Kenosha, WI"
},
"IsPin": false,
"IsVisible": true
},
{
"DocId": "1",
"Score": 2.0,
"Document": {
"id": [
"1"
],
"title": [
"Testing GeoLocation Chicago"
],
"location": [
{
"lon": -87.7809,
"lat": 42.09975
}
],
"title_test_copy": [
"Testing GeoLocation Chicago"
]
},
"BestFragments": {
"title": "Testing GeoLocation Chicago"
},
"IsPin": false,
"IsVisible": true
},
{
"DocId": "2",
"Score": 2.0,
"Document": {
"id": [
"2"
],
"title": [
"Testing GeoLocation Rockford, Il"
],
"location": [
{
"lon": -89.064445,
"lat": 42.259445
}
],
"title_test_copy": [
"Rockford, Il"
]
},
"BestFragments": {
"title": "Testing GeoLocation Rockford, Il"
},
"IsPin": false,
"IsVisible": true
}
],
Sample 6 – Including Facet Selection and Sorting by Farthest Location
Adding "SortBy":"Farthest" parameter to the request
v2/search:
Example
{
"IndexName": "XXXXXXXXXXXXXXX",
"ClientGuid": "SPECIFY YOUR CLIENT GUID HERE",
"ClientData": {
"Origin": {
"Latitude": "43.675819", // France, Niece
"Longitude": "7.289429"
}
},
"FacetSelections": {
"location": [
"4"
]
},
"SortBy":"Farthest"
}
Results:
Example
"Results": [
{
"DocId": "2",
"Score": 2.0,
"Document": {
"id": [
"2"
],
"title": [
"Testing GeoLocation Rockford, Il"
],
"location": [
{
"lon": -89.064445,
"lat": 42.259445
}
],
"title_test_copy": [
"Testing GeoLocation Rockford, Il"
]
},
"BestFragments": {
"title": "Testing GeoLocation Rockford, Il"
},
"IsPin": false,
"IsVisible": true
},
{
"DocId": "1",
"Score": 2.0,
"Document": {
"id": [
"1"
],
"title": [
"Testing GeoLocation Chicago"
],
"location": [
{
"lon": -87.7809,
"lat": 42.09975
}
],
"title_test_copy": [
"Testing GeoLocation Chicago"
]
},
"BestFragments": {
"title": "Testing GeoLocation Chicago"
},
"IsPin": false,
"IsVisible": true
},
{
"DocId": "3",
"Score": 2.0,
"Document": {
"id": [
"3"
],
"title": [
"Testing GeoLocation Kenosha, WI"
],
"location": [
{
"lon": -87.822899,
"lat": 42.588081
}
],
"title_test_copy": [
"Testing GeoLocation Kenosha, WI"
]
},
"BestFragments": {
"title": "Testing GeoLocation Kenosha, WI"
},
"IsPin": false,
"IsVisible": true
},
{
"DocId": "4",
"Score": 2.0,
"Document": {
"id": [
"4"
],
"title": [
"Testing GeoLocation Paris"
],
"location": [
{
"lon": 2.349014,
"lat": 48.864716
}
],
"title_test_copy": [
"Testing GeoLocation Paris"
]
},
"BestFragments": {
"title": "Testing GeoLocation Paris"
},
"IsPin": false,
"IsVisible": true
}
],
…
Tracking for Reporting
Even though the API request contains latitude and longitude, we have a mode where you can also pass a zip code in for tracking purposes. It is important to pass zip code in the object shown below if you are looking to see reporting around geolocation search. If zip code is not passed, no data will be tracked.
In order to track data for reporting, the following information needs to be passed to Hawksearch:
A new string property ZipCode has been added under ClientData object
To trigger a zip code search, ZipCode and Origin lat/lon must be passed
Example that can be used to test tracking:
Example
{
},
"item": [
{
"name": "Geo location tracking",
"request": {
"method": "POST",
"header": [
{
"key": "Content-Type",
"value": "application/json"
}
],
"body": {
"mode": "raw",
"raw": "{\r\n \"ClientGuid\": \"SPECIFY YOUR CLIENT GUID HERE\",\r\n \"ClientData\": {\r\n \"Origin\": {\r\n \"Latitude\": \"42.01187\", //chicago\r\n \"Longitude\": \"-87.99496\"\r\n },\r\n \"ZipCode\" :\"testing zip code\"\r\n },\r\n \"IndexName\": \"XXXXXXXXXXXXXXXX\",\r\n \"Keyword\": \"testing geolocation\"\r\n}"
},
"url": {
"raw": "https://searchapi-dev.hawksearch.net/api/v2/search",
"protocol": "https",
"host": [
"searchapi-dev",
"hawksearch",
"net"
],
"path": [
"api",
"v2",
"search"
]
}
},
"response": []
},
{
"name": "trackevent",
"request": {
"method": "POST",
"header": [
{
"key": "Content-Type",
"value": "application/json"
}
],
"body": {
"mode": "raw",
"raw": "{\r\n \"ClientGuid\": \"SPECIFY YOUR CLIENT GUID HERE\",\r\n \"VisitId\": \"8XXXXXXXXXXXXXXXX\",\r\n \"VisitorId\": \"XXXXXXXXXXXXXXXX\",\r\n \"EventType\": 2,\r\n //Use https://www.base64encode.org/ to Decode below, and then encode back\r\n \"EventData\": \"eyJRdWVyeUlkIjoiYTBmM2YxZjItNWY0ZS00NTcwLWE4YmItOGQwY2ZjODNlNGExIiwiVHJhY2tpbmdJZCI6Ijc1MWViMDY4LWFlNGEtNDI5Ny1iYzE0LWZhMTgzZDdmMTZlZiIsIlR5cGVJZCI6MSwiVmlld3BvcnRIZWlnaHQiOjQzMSwiVmlld3BvcnRXaWR0aCI6MTkwMywia2V5d29yZCI6ImJsYWNrcyJ9\" \r\n}"
},
"url": {
"raw": "https://tracking-dev.hawksearch.net/api/trackevent",
"protocol": "https",
"host": [
"tracking-dev",
"hawksearch",
"net"
],
"path": [
"api",
"trackevent"
]
}
},
"response": []
}
]
}
Please note that zip codes that were searched for will appear in the Keyword column within Hawksearch Search reports.
Best Practices
As a best practice we recommend to use this facet for searches under 250 miles radius for performance reasons. If you are looking to pull in results for a larger radius or see all possible results, a different approach may need to be chosen. Please reach out to our Support or Client Success Directors teams should you have questions.