The GeoSearch feature of the BotCentral platform allows you to create a location-based search function to your chatbot, without having to create your own RESTful API or handle geolocation data. You can simply provide a list of locations in a Google Sheet, and the BotCentral platform will create a web hook for you.

Create a Google Sheet of You Locations

In Google Sheets, create a new sheet with at least the following columns:

  • id
  • active
  • locationName
  • country
  • address1
  • city
  • state
  • zipPostalCode

You do not need to provide geocoordinates (lat, long) — the platform will find the locations for you. For this tutorial we’ll be using this example sheet of restaurant locations near our office. You can see in the example that we have additional columns defined, some of which we’ll use in this tutorial.

Be sure to set the Share settings on your Google Sheet to Anyone with the link can view.

Create a GeoSearch DataSource

First, select the Knowledge feature from the main menu and click Add DataSource.


Give the new DataSource a relevant name and select KnowledgeBase for the Type. Paste in the sharing link from the Google Sheet.


When you click the Add button, some new fields appear.


Copy the complete URL from Search by City and save it for later.[longstringofrandomnumbers]

Testing Your GeoSearch Import

To make sure your data has been formatted and uploaded correctly, use the Test feature on the left side of the screen. Try searching by city, and entering a city you have locations for. If you get results, everything is working as it should.


Now let’s build a bot that uses this data.

Create a Location Context

We’ll start with a Required Context that creates a location object. This is very simple.


All you need is set the Context Type to Location and the Request Type to Text, and then add a message asking the user for their location.

For simplicity’s sake, we’re setting the Name of this Content to location — but you could pick something else if you wanted to.

Build a GeoSearch Responder

Now we need to create a Responder to call the GeoSearch API.


Give the Responder a relevant Name.

Calling the GeoSearch API

The Webhook is the URL provided by the GeoSearch builder, up to the question mark.

That is, if the URL is:[longstringofrandomnumbers]

Use this:

In the Params section, you need two parameters.

  • Key source
    • Value the source parameter from the URL — the [longstringofrandomnumbers]
  • Key latLong
    • Value {$location.latlng}
  • Key specialTags
    • Value {$botContext.placeType}

Set the Method to GET. And, for this tutorial, we’ll use the Structured Result Type.


This will search the content of the Google Sheet for locations near the user, based on the user’s location. The {$location} object automatically calls the location context we created earlier, so getting the user’s location is all handled automatically.

The last parameter determines what type of location the search will look for. We’ll deal with getting this from the user when we create the Welcome message.

Parsing the GeoSearch Results

We’re going to use Structured Tiles to present the results to the user.


The top of each tile will show the location’s name, the street address, and the city:

{$.successResult.storeLocations[i].address1}, {$.successResult.storeLocations[i].city}

The {$.successResult.success} object holds all the results from searching the GeoSearch, and [i] lets you iterate over those results. The identifier after that specifies a column label from the Google Sheet.

Now we’ll add a couple buttons to the tile: a “Get Directions” button that will link to a Google Map of the location, and a “Try Again” button that will trigger the Welcome message.


The Callback for the Get Directions button is:{$.successResult.storeLocations[i].address1}, {$.successResult.storeLocations[i].city}, {$.successResult.storeLocations[i].zipPostalCode}

Calling the GeoSearch Responder

Now that we have a working Responder, we just need to create a Message to call it. This is very easy.


We’ll add a little note in Pre-result to display before the locations are shown.


And we’ll add a little Postprocess Code to deal with the possibility of no results coming back from the responder.

var results = botContext.getResponderResultsCount();
botContext.printDebugMessage('Results Count = ' + results);

if (results < 1){
  // no results

This will trigger the FAIL message, will display a notice to the user and then try again.

Handling No Results

Let’s create the FAIL message.


This tells the user: Something went wrong. Let’s try that again…

Then, we’ll let the user trigger the Welcome message by using a single Quick Reply.


The user will see Try Again, and if they click on it try again will be treated as input for pattern matching.

Now let’s create the Welcome message, and be sure to add try again as a pattern.

GeoSearch Welcome Message

Our Welcome message will ask the user what type of location they are looking for, present two options using Quick Replies, and then set the bot variable that will be used by the Responder.


The Quick Replies will let the user choose between Restaurant and Coffee Shop.


Then we’ll use getQuickReplyPayload() in Process User Response to save the answer for the Responder.

var response = botContext.getQuickReplyPayload();
if(response != null){
    botContext.printDebugMessage('User selected ' + response);
    botContext.setTriggerNextMessage('Show GEO');

Now we have a bot that will:

  • ask the user which type of place they want to look for
  • get the user’s current location
  • search for a places close to the user’s location
  • return a list of places to the user
  • let the user get directions

Not bad for not having to build and host your own API.

../_images/test-geo-phone-start.png ../_images/test-geo-ask-location-phone.png ../_images/test-geo-get-location-phone.png ../_images/test-geo-places-found-phone.gif