I just spent a few hours connecting our directions and traffic APIs to Alexa. Here is step by step how this works:

Decide on the intents

For most bots, the first thing you need to decide is the intents that you want to support, actions or skills you want your bot to do. I just wanted Alexa to respond to the following questions:

  • Alexa, ask Mapbox how long is my commute.
  • Alexa, ask Mapbox how far is <address>.
  • Alexa, ask Mapbox what’s popular nearby.
  • Alexa, ask Mapbox what’s new.

Since IoT bots like Alexa can be anywhere, I also let the user set where they live and work, so Alexa can give me directions from my home to anywhere:

  • Alexa, tell Mapbox that my address is <address>.
  • Alexa, tell Mapbox that my office address is <address>.

We defined each of these intents in a IntentSchema.json file (this is the one we used). An intent definitions can be just one line:

{ "intent": "CommuteIntent" }

If they take an address, you need to explicitly set a parameter:

{ "intent": "DirectionsIntent",
  "slots": [ {
        "name": "PostalAddress",
        "type": "AMAZON.PostalAddress" } ] }

In this case, we’re using the built-in slot AMAZON.PostalAddress which is useful for a street address as it includes the building number and the street name.

Translate intents into utterances

Next, I wrote sentences that specify the different ways that users can invoke the intents. These sample utterances are associated to intents and become the core interaction model for the skill.

For example, for the CommuteIntent defined above, these are a few possibilities:

CommuteIntent how long is my commute
CommuteIntent how is the traffic today
CommuteIntent how is driving to work

This lets me ask in different ways about my commute to work. These are three ways someone could ask for an address:

DirectionsIntent how far is {PostalAddress}
DirectionsIntent how do i get to {PostalAddress}
DirectionsIntent directions to {PostalAddress}

Java SDK for Mapbox Services

At the core of the Mapbox Android Services SDK is a pure Java library that has no Android dependencies. That means you can use it in any Java project, including a cloud app like this one, to access Mapbox APIs.

If you use Gradle, just include the following line in your build.gradle (all of our artifacts are available on Maven Central):

compile 'com.mapbox.mapboxsdk:mapbox-java-services:2.1.1'

It lets you query our APIs to get traffic information in one statement:

MapboxDirections client = new MapboxDirections.Builder()
	.setAccessToken(Constants.MAPBOX_ACCESS_TOKEN)
	.setOrigin(origin)
	.setDestination(destination)
	.setProfile(DirectionsCriteria.PROFILE_DRIVING_TRAFFIC)
	.build();

If you prefer other languages, we have libraries available for Python, Javascript, Objective-C, and Swift. Use the SDK that best suits your needs and infrastructure.

Upload code to Lambda

I’m hosting the skill on AWS Lambda because we love its simplicity, and because it’s well integrated with Alexa Skills. This is how it works:

  1. Build a .zip file that contains the deployment package with ./gradlew clean build.
  2. Verify the file is on skill/build/distributions/alexa-skill-0.1.zip.
  3. Upload it through the AWS Console to your Lambda: AWS services -> Lambda -> Create or choose a Lambda -> Upload -> Save and test.

Putting it all together

The final step I made was to go to the Alexa Developer Portal to edit the settings of the skill. Through this page, I set the intents and utterances, linked the Lambda function, and chose the skill invocation name (the name that identifies the skill). For this example, I picked Mapbox— short and sweet.

Here are the detailed instructions I used from the official AWS documentation.

Check out the code

I put this code in a repo on GitHub. Feel free to reuse any part of it in your project. Hit me up on Twitter @zugaldia with any questions, and post videos ;) of skills and bots that you build.