Recently my parents bought themselves a shiny new laptop. They got it home, sat it on their desk and realized that the only display port on the laptop was HDMI. This unfortunately would not work with their external monitor which only had VGA and DVI ports. As the resident family IT guy they called me.
I could have ordered the adapter, but I figured going local would be a faster way to solve their problem. I searched for the part on Best Buy’s website and found a generic HDMI to DVI cable which would work perfectly for them.
Now I’ve been burned in the past by seeing something online and rushing out to the local store only to find out its not actually in stock, so this time I picked up the phone and called my local Best Buy and had a conversation that went a bit like this:
BB: Hello, Best Buy, how can I help you
Me: Ya, I’m looking to see if you have a whatsihoozits in stock. The part number is 123456789.
BB: One moment sir, let me check. It doesn’t look like we have that in stock, but I am showing the Flooverville store has 4.
Me: Flooverville, eh? I’m not quite sure where that is.
BB: Oh, that store is located just outside of the Flooverville Mall.
Me: I’ve never been there. Can you give me an idea of how to get there?
BB: Sure. Hop on Route 345 for a few miles. Left at a gas station, I think it might be a Gas-O-Rama, but maybe not. Go for a few miles and look for the next big road. Not sure what its called, but it eventually becomes Flooverville Road. I think you turn right. You’ll see a McRonalds. When you do start……..[lots more vague directions go here]….and then you’ll see the sign for Best Buy.
Needless to say, the instructions were less than helpful. Here is how I wish that conversation had gone:
BB: Oh, well that store is located just outside of the Flooverville Mall.
Me: I’ve never been there. Can you give me an idea of how to get there?
BB: Sure. If you give me your address and phone number I’ll be happy to send you a map with driving directions directly to your phone.
Me: Awesome! I live at 123 Main Street Cityton and my phone number is 555-555-5555.
BB: The map should arrive at your phone momentarily. Is there anything else I can do for you today?
This post will show you how to build that experience. By combining the Best Buy API, Bing Maps and a bit of Twilio with some basic web development using JavaScript and ASP.NET MVC, we’ll create a website that can locate a product at a Best Buy near you and then send a customized driving route map directly to your phone as an MMS message. Let’s get building!
Gathering Your Materials
Like any building project, we’ll need some materials to get started. In this case we’ll leverage a number of different APIs including:
Best Buy API – Gives us product availability and store location information. Sign up for free access to the Best Buy API
Bing Maps REST API – Lets us generate a static map image with a driving route overlayed. Access to the Bing Maps REST API is also free
Twilio API – Using a US or Canadian MMS enabled phone number, lets us send the generated map image to a phone via an MMS message. Sign up for your free Twilio account
Of course if you’re not interested in writing the code yourself and just want to deploy a completed app, you can do that as well. All of the code shown in this post is available as a completed website in GitHub.
Where Can I Find A Whatsihoozits?
The first problem we need to tackle is locating products at a local Best Buy. To do that we’ll build a simple web page that a store employee could use to check for product availability in a location. The page uses Bootstrap to display a nicely designed HTML form that lets the employee enter a product SKU, a zipcode and a search distance:
When the Search button is clicked, the web page uses jQuery to send the form values as an AJAX request to the Best Buy API. The API endpoint we are using will take those values and locate any Best Buy stores within the specified distance that has the product SKU in stock, returning to us a list of those store locations formatted as JSON.
Because this request comes directly from the web page, jQuery needs to be configured to make the request using JSONP, which the Best Buy API supports. To do this set the dataType parameter to jsonp and the jsonpCallback parameter to a function named listProducts which you can add to your page.
Once the Best Buy API is successfully returning results to the web app, we’ll need to display them. To do this I chose to use Mustache templates, and created a simple template to show the address of each store returned from the Best Buy API:
With the template defined, you merge it and the results from the Best Buy API together by calling Mustaches To_Html function:
Fantastic! You’ve just built a product availablity search web page. Go ahead and run it and try to find some products near you. Need some ideas to search for? Try some of these favorites of the Twilio Devangel crew: 1307700488, 5143501 or 5568321.
Which Way Do You Go?
Now that we’re finding stores with products, let’s move on to taking the store data and sending a map with driving directions to a phone.
To provide those instructions we’ll need to have a start point and an end point. The end point will be a Best Buy address which we received from the Best Buy API. The start point will be the customers address. We also need to know the customers phone number so that we can send the map to the phone. To get that additional customer data we’ll need another form in the web page. Since the app already uses Bootstrap, we can leverage its Modal dialog to display this form:
Once we have the start and end address and a phone number, we are ready to generate and send the map which we’ll do on the server. Triggered by the closing of the Modal dialog, the .ajax function from jQuery is used to send the addresses and phone number to the server.
Notice that the AJAX request is being made to the route /Home/SendMap. This will be the code that actually generates the map and sends the MMS. Let’s head over to the server side, create that new route and generate a new map.
Generating Static Maps with Bing
Before we write any code on the server, let’s look at how to use the Bing Maps REST API to generate our map. The Bing Maps REST API includes a resource which accepts a series of addresses or landmarks known as Waypoints. Based on the provided Waypoints, Bing will calculate the best driving route and return a map with that route overlayed.
For example, to generate a map that shows how to drive from Twilio’s headquarters in downtown San Francisco to the Golden Gate Bridge, you would create a URL with two Waypoints:
Dropping this URL into a browser with your own Bing Maps REST API key will return a map with the best driving route:
There are many options available in the Bing Maps REST API, such as showing satellite imagery, telling Bing to to avoid highways or even choosing a different travel mode like walking or public transit. Check out the Bing Maps documentation to learn about all those options.
Putting All Of the Pieces Together
Finally, let’s finish this app by putting the whole thing together and sending a Bing Map containing the route from the customer address to the Best Buy location as an MMS.
Start by creating a new method named SendMap in your ASP.NET MVC controller and define three method parameters, one for the start address, one for the end address and one for the phone number.
We will let ASP.NET MVC’s model binding handle mapping the values coming from the AJAX request into the method parameters.
To send the MMS we’ll use the Twilio .NET Helper Library, which you can install via Nuget.
Start by creating a new instance of the TwilioRestClient object, passing in your Twilio account credentials. You can find your account credentials on your account dashboard.
Next, using the object instance call the SendMessage method. This triggers an HTTP request to the Messages resource in Twilio REST API, telling Twilio that we want to have it send a new MMS message for us. The SendMessage method accepts several parameters including:
From – the Twilio phone number you want this MMS message to come from. You can see what phone numbers you own, or buy new numbers by logging into your Twilio dashboard and selecting the Numbers tab.
To – the phone number you want the MMS message to go to. In our application this is the customer who we want to send the map to.
Body – a string containing a message you want to include in the MMS message.
MediaUrls – an array of strings, where each string is a URL that points to an image you want to include in the MMS message. In our application we’ll be including the Bing Maps URL in this array.
Now, putting the code together the SendMap method looks like this:
After the call to SendMessage is made, we use the RestException property to see if anything bad happened during the request to the Twilio REST API. If an exception occurs we return the details of that exception to the web page in the form of a JSON object.
This check will not tell us if Twilio was able to successfully retrieve the map from Bing. If Twilio encounters a problem getting the map image, it will set the MMS messages status to Failed.
To check the message status we could go back at a later time and use the Twilio REST API to query for messages whose Status is Failed. Another option would be to provide the StatusCallback parameter to the SendMessage method. This gives Twilio a URL to request when the message status changes.
Awesome! You should now be able to give the entire site a whirl. Load up the web page, drop in a product SKU, zip code and distance to find the product in a Best Buy near you. When you do, click the Send Map button, enter an address and phone number and voila, a beautifully rendered map with the driving route will soon show up on your phone.
Conclusion
By combining a few easy to use APIs and a little bit of code we’ve created an app that makes it much easier for businesses to communicate with their customers. Build it yourself or just grab the code off of GitHub and deploy.
The road need not stop here however. There are a bunch of really cool places you could take this app, including:
Allow the user to retrieve text-based driving instructions along with the map or
Include a link in the MMS message which deep links your customers directly to a maps application they have installed on their phone
What other ideas do you have for how this kind of application can work? I’d love to hear them. Reach out to me on twitter @devinrader or via email devin@twilio.com.
Send Driving Directions Using Bing Maps and Twilio MMS