VOGO Voice – Knowledge Base

Using Geocoder to Lookup Information

Estimated reading time: 9 min

Geocoding is the process of transforming input data such as street addresses into location points (latitude and longitude). Reverse Geocoding, on the other hand, converts location points to the name of a place or street address.  By using 3rd party services, the VOGO Voice Geocoder connector provides easy access to execute the READ only function of geocoding and reverse geocoding.

Adopting a comprehensive methodology, the tutorial aims to give you a guided walkthrough in a simplified manner to create two interaction models, one implementing the geocoding process and the other executing the reverse geocoding. This instructional tutorial aims at employing an elementary use-case to illustrate how to interact with a Geocoder web service within a custom interaction model to retrieve location based information. 

Prerequisites

  • VOGO Voice account: https://www.vogovoice.com/
  • Access rights to the Slots and Intents section under Settings.
  • Access rights to Interaction builder platform.
  • API key authentication requirement is relatively dependent on the Geocoder provider selected. BYOK (Bring your own API Key)
  • Alexa device (In the case of using location information, choose an appropriate device such as Alexa Auto, Alexa Echo Buds or Alexa app on the phone) 

Setting up a Geocoder connector instance

In order to create a Geocoder connector instance
1. Log into your VOGO Voice account to be directed to VOGO Voice Management Console (https://account.vogovoice.com)
2. Navigate to Settings on the top right-hand corner of the Dashboard and select Integration from the list of tabs displayed.
Settings > Integration
3. Click on the Add Button on the top left-hand corner of the screen.

4. In the Select Account Type window, choose the Geocoder icon from the list of connectors and click Create Connector button which opens up Add Geocoder Account window.
5. Populate the required fields in the Add Geocoder Connector window.

Field Values

Name: Provide the username of the Geocoder account. Here, the name provided is Geocoder Connector.
Provider: Select from the drop-down list the specific geocoder provider whose Geocoding and Reverse Geocoding service is made use of. The chosen service provider here is opencage.

To learn more about the 3rd party providers refer the Geocoder connector guide: https://university.vogovoice.com/kb/geocoder/

API Key: The API Key essentials are dependent on the geocoder provider service selected. Here the chosen 3rd party provider being opencage, the steps followed to obtain the API key are as illustrated below.

👍 Note: You may choose any provider service of your preference besides the one we have chosen in the demo.

To procure the API key, visit opencagedata.com and navigate to the API section on its homepage as shown below.

  • Click on Sign up for your free API key call to action button as highlighted below.
  • To sign up, you will be required to populate the necessary fields, after which you will be sent two emails, one to confirm your email address and another providing you with the free API key.

API Key: Populate the API key field with the procured key.

6. After filling in the required fields click the Save button to set up and integrate the connector instance with the platform.

Steps to create a custom slot titled POI (Point of Interest)

  1. Log into your VOGO Voice account to be directed to VOGO Voice Management Console (https://account.vogovoice.com)
  2. Navigate to Settings on the top right-hand corner of the screen and select Slots from the list of tabs displayed. 
    Settings > Slots
  3. Click on the create New Slot button on the bottom right-hand corner of the screen.

4. In the Add New Slot pop-up window that appears, create a slot by the name POI and add Denver Art Museum as the slot value together with defining itsslot Name as address. In the field titled Value input the address of Denver Art Museum .i.e 100 W 14th Ave Pkwy, Denver, CO 80204, United States. When finished click the Save button at the bottom of the window.

To learn how to create custom slots refer the guide: https://university.vogovoice.com/kb/guide-creating-custom-slots/

Steps to create a ‘What is my street address’ Intent for Geocoding

In order to execute an interaction flow for the users to retrieve the location points (latitude and longitude) of a locality which for the purpose of illustrating has been selected here as the Denver Art Museum, requires the need to create a custom intent to be invoked through the skill. 

Create an intent titled ‘What is my street address’ with a set of suitable sample utterances mapped to it. Let’s say the sample utterances are: “What is the location of {POI}”, and “Tell me the location of {POI}”, where ‘POI’ is the slot name. Assign the slot type to POI, which is the custom slot created with a suitable value assigned to it. 

To learn how to create custom intents refer the guide: https://university.vogovoice.com/kb/creating-intents/

Steps to create a ‘Where am I located’ Intent for Reverse Geocoding

In order to execute an interaction flow for the users to retrieve the street address from the given location points, we need to create a custom intent to be invoked through the skill. 

Create an intent titled ‘Where am I located’ with a set of suitable sample utterances mapped to it. Let’s say the sample utterances are: “Tell me my location”, and “What is my location”, but with no slot values assigned to it as the purpose here being to convert the location points (latitude and longitude) detected by the Alexa device to its street address.

Steps to create a ‘What is my Street Address’ Interaction flow for Geocoding

Now that we have created a What is my Street Address intent, let’s create an interaction flow associated with the intent to be executed through the skill.

1. Navigate to Interactions on the vertical bar displayed on the left-hand side of the Dashboard.
2. Click on the Interaction button at the bottom right-hand corner of the screen and select the ‘What is my Street Address’ intent to be directed into the Interaction builder platform. 

3. In the flow diagram area you will be able to see the Start and Response component.
4. Unlink the Start component from the Response card by clicking the delete icon placed in the middle of the chain.

5. Drag and drop the Geocoder component onto the flow diagram area and connect the anchor symbol of Next on the Start component to the Geocoder component.
6. Connect the anchor symbol of Next on the Geocoder component to the anchor symbol on the Response card.

🖍Note: To interconnect the different components click on their respective Anchor symbols so as to chain and hold them in the interaction flow.

7. Upon launching into What is my Street Address interaction, navigate to the topmost part of the interaction builder platform interface and you will see What is the location of POI with a blank wild card slot which is set to capture the POI.

8. Configure the Geocoder component by clicking the pencil to access the Configuration window and fill in the required fields to query and retrieve the location based information.

Steps to Configure the Geocoder connector instance 

  • Name: The name is provided by default and can be changed manually. It is used to identify the connector instance and how it is referenced throughout the flow. 
  • Geocoder Type: Choose from the drop-down list the specific geocoding type based on the requirement, which here is selected as Geocoding for the purpose of converting street address into spatial data (latitude/longitude).
  • Address: To input the value i.e the street address navigate to the Data tab adjacent to the Components on the top left-hand side of the interaction builder platform and navigate further down the Data section to inputs. Click on its plus button to have its subsection appear. In the list that appears, click on the plus button of POI which will open up a list namely address and value. From the list select value by dragging and dropping it in the Address field of the Geocoder configuration window which will automatically generate the address of Denver Art Museum in its respective field.
  • Limit: Set the limit of data records to be retrieved from the result set as 1. 

9. Roll the mouse over the Response component to see the voice, computer and camera icon on the top right-hand side of the component.
10. Clicking on the Voice icon opens a Speak pop-up window with a field titled Say wherein you need to type the voice action intended to be spoken to the user upon retrieving the location based information.

Say: The latitude and longitude based on your location are {{connectors.c1.first.latitude}} and {{connectors.c1.first.longitude}}

To learn about different template engines to be followed to run functions visit https://university.vogovoice.com/kb/template-engine/

To add a display message in a video-enabled voice-assisted device
1. Click on the Computer icon, and type in a condensed version of the voice message in the field titled Display Message of the Show pop-up window.
2. Populate the required fields and click the Save button. 
Title: Geocoding
Display Message: The latitude and longitude based on your location are {{connectors.c1.first.latitude}} and {{connectors.c1.first.longitude}}

For further reference on how to populate the additional fields visit https://university.vogovoice.com/kb/guide-response-component/

The screenshot below captures the aforementioned interaction flow.

Testing and Validation

  1. Click on the Test button next to the Flow Editor button on the interaction builder platform. 

2. In the Tests pop-up window that appears click the + button on its top right-hand corner. 

3. Fill the Name field of the Test Response window that shows up.
4. In the Conversation section of the Test Response, What is my Street Address intent through which this interaction flow has been initiated will be auto-generated in the User invokes field.
1.  Fill the ‘With slots’ field titled ‘POI’ under Conversation with the input as Denver Art Museum.

5. Finally, click the Save button to save the input and perform the test.
6. To validate the Test Response, click on the lightning symbol on the left-hand side of the test case. 

7. On the resultant Test Response window, the blue chat bubble will present the previously input message within the Response component. The lightning bolt symbol in yellow represents the Geocoder connector instance. 

8. Click on the chat bubble to see the details of the response. To take a detailed look at the data fetching part of the connector instance, click on the respective lightning bolt icon highlighted in yellow. 

To know more about testing an interaction refer https://university.vogovoice.com/kb/testings/

Steps to create a ‘Where am I located’ Interaction flow for Reverse Geocoding

Now let’s create an interaction flow by implementing the Where am I located intent for the purpose of executing the Reverse Geocoding process.
1. Navigate to Interactions on the vertical bar displayed on the left-hand side of the Dashboard.
2. Click on the Interaction button at the bottom right-hand corner of the screen and select the ‘Where am I located’ intent to be directed into the Interaction builder platform. 

3. In the flow diagram area you will be able to see the Start and Response component.
4. Unlink the Start component from the Response card by clicking the delete icon placed in the middle of the chain.

5. Drag and drop the Geocoder component onto the flow diagram area and connect the anchor symbol of Next on the Start component to the Geocoder component.
6. Connect the anchor symbol of Next on the Geocoder component to the anchor symbol on the Response card.
7. Configure the Geocoder component by clicking the pencil to access the Configuration window and fill in the required fields to query and retrieve the location based information.

Steps to Configure the Geocoder connector instance 

  • Name: The name is provided by default and can be changed manually. It is used to identify the connector instance and how it is referenced throughout the flow. 
  • Geocoder Type: Choose from the drop-down list the specific geocoding type based on the requirement, which here is selected as Reverse Geocoding for the purpose of converting spatial data (latitude/longitude) into street address.
  • Geometry: This field requires to be defined with the syntax geolocation.latitude and geolocation.longitude to capture the location of the device. To input the syntax navigate to the Data tab adjacent to the Components on the top left-hand side of the interaction builder platform and navigate further down the Data section to geolocation. Click on its plus button to have its subsection appear. In the list that appears, click on the plus button of latitude and select it by dragging and dropping it in the Geometry field titled latitude in the Geocoder configuration window.  Then click on the plus button of longitude and select it by dragging and dropping it in the Geometry field titled longitude. Doing so will automatically generate its respective data types as Path.

8. Roll the mouse over the Response component to see the voice, computer and camera icon on the top right-hand side of the component.
9. Clicking on the Voice icon opens a Speak pop-up window with a field titled Say wherein you need to type the voice action intended to be spoken to the user upon retrieving the location based information.
Say:  The street address is {{connectors.c1.first.streetNumber}} {{connectors.c1.first.streetName}} {{connectors.c1.first.city}} {{connectors.c1.first.state}} {{connectors.c1.first.zipcode}} {{connectors.c1.first.country}}

To add a display message in a video-enabled voice-assisted device
1. Click on the Computer icon, and type in a condensed version of the voice message in the field titled Display Message of the Show pop-up window.
2. Populate the required fields and click the Save button. 
Title: Reverse Geocoding
Display Message: The street address is {{connectors.c1.first.streetNumber}} {{connectors.c1.first.streetName}} {{connectors.c1.first.city}} {{connectors.c1.first.state}} {{connectors.c1.first.zipcode}} {{connectors.c1.first.country}}

The screenshot below captures the aforementioned interaction flow.

Testing and Validation

  1. Click on the Test button next to the Flow Editor button on the interaction builder platform. 

2. In the Tests pop-up window that appears click the + button on its top right-hand corner. 

3. Fill the Name field of the Test Response window that shows up.
4. In the Conversation section of the Test Response, Where am I located intent through which this interaction flow has been initiated will be auto-generated in the User invokes field.

5. Navigate further down and check the checkmark box of Geolocation under the User Permissions section

6. Then input the Latitude and Longitude coordinates under the Geolocation section.

7. Finally, click the Save button to save the input and perform the test.
8. To validate the Test Response, click on the lightning symbol on the left-hand side of the test case. 

9. On the resultant Test Response window, the blue chat bubble will present the previously input message within the Response component. The lightning bolt symbol in yellow represents the Geocoder connector instance. 

10. Click on the chat bubble to see the details of the response. To take a detailed look at the data fetching part of the connector instance, click on the respective lightning bolt icon highlighted in yellow. 

Congratulations! You have successfully created two interaction flows to convert location based information by implementing the Geocoding and Reverse Geocoding process  within a custom interaction model.

👍 Note: To test the functioning of the interactions on your device you have to deploy the custom skill to facilitate the skill with the new edits. To accomplish this, click on the Deploy button seen at the bottom of the Skill Settings pop-up window.

To know how to deploy a custom skill visit https://university.vogovoice.com/kb/deploying-a-skill/

To learn about Geocoder connector, click here.

Tags:
Was this article helpful?
Dislike 0
Previous: Every nth Time (Using MOD feature)
Next: Fibonacci