/
Geolocation Search: Distance Facet Configuration

Geolocation Search: Distance Facet Configuration

Owned by Lana Starchuk (Deactivated)
Last updated: Mar 15, 2022
9 min read

 

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.

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:

 

{     "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:

"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:

{     "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:

"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 100mi’

Distance between Niece and Paris is less than 100mi, so the current facet selection will return the following results:

v2/search:

     "ClientGuid": "SPECIFY YOUR CLIENT GUID HERE",     "ClientData": {         "Origin": {             "Latitude": "43.675819", // France, Niece             "Longitude": "7.289429"         }     },     "FacetSelections": {         "location": [             "3"         ]     } }

 

Response:

Facets object:

{             "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:

 "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 1000mi’

Distance between Niece and US cities is more than 1000 mi, so the current facet selection will return results from both Europe and US:

v2/search:

 "ClientGuid": "SPECIFY YOUR CLIENT GUID HERE",     "ClientData": {         "Origin": {             "Latitude": "43.675819", //France, Niece             "Longitude": "7.289429"         }     },     "FacetSelections": {         "location": [             "4"         ]     } }

 

Results:

"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:

 {     "IndexName": "XXXXXXXXXXXXXXXX",     "ClientGuid": "SPECIFY YOUR CLIENT GUID HERE",     "ClientData": {         "Origin": {             "Latitude": "52.237049", //Warsaw, Poland coordinates             "Longitude": "21.017532"         }     },     "FacetSelections": {         "location": [             "1"         ]     } }

 

Response:

{     "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:

 {     "IndexName": "XXXXXXXXXXXXXXXX",     "ClientGuid": "SPECIFY YOUR CLIENT GUID HERE",     "ClientData": {         "Origin": {             "Latitude": "43.675819", // France, Niece             "Longitude": "7.289429"         }     },     "FacetSelections": {         "location": [             "4"         ]     } }

 

Results:

 "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:

{     "IndexName": "XXXXXXXXXXXXXXX",     "ClientGuid": "SPECIFY YOUR CLIENT GUID HERE",     "ClientData": {         "Origin": {             "Latitude": "43.675819", // France, Niece             "Longitude": "7.289429"         }     },     "FacetSelections": {         "location": [             "4"         ]     },     "SortBy":"Farthest" }

 

Results:

"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:

  1. A new string property ZipCode has been added under ClientData object

  2. To trigger a zip code search, ZipCode and Origin lat/lon must be passed

 

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.

Related content