Salesforce Maps: Enhance Your Salesforce Maps Distance Matrix Apex Customizations with TSSMaps

This is the final video in our four-part series on implementing and optimizing Salesforce Maps.

  • View Part 1 (Augment Salesforce Objects with Geolocation Data) here
  • View Part II (Use Salesforce Maps and a Distance Matrix to Calculate Drive Times Between Locations) here
  • View Part III (Implement Both Simple or Bulk Drive Time and Driving Distance Lookups with Salesforce Maps) here

In this final installment of our Salesforce Developer Deep Dive series into Salesforce Maps, Senior Salesforce Developer Mike Chandler shows you how to use a freely available open source Apex utility to power through distance matrix queries using Salesforce Maps. Check it out, then head on over to the TruSummit Solutions GitHub page to get your hands on this Apex class for your own implementations!


Hi, I’m Mike, a Salesforce developer with TruSummit Solutions. In this video, I’ll show you how to use a freely available open source Apex utility to power through distance matrix queries using Salesforce Maps. This video is part four in a series of development focused Salesforce maps tutorials. In our previous video in the series, we looked at two possible ways to provide solutions for calculating distances and drive times using a distance matrix query. In this video, we’ll dive deeper into the open source apex utility I used in my implementations and share details on how you can use it in your solutions as well.

At TruSummit Solutions, we manage an internal library of code and metadata to help facilitate and expedite our custom software builds. Our hope is that by providing these utilities, we enable our entire staff to solve complex problems after only one or just a few of our staff solves them for the first time. It allows us to add measurable value to our client engagement by expediting builds and avoiding resource bottlenecks. In this example, the utility class was so easy to write while having some notable valuable for me as a developer that we just wanted to share this with the entire community and promote Salesforce Maps as the highly capable and customizable tool that we believe that it is to better understand how our apex utility helps you.

Let’s dig into this application. It’s a very simple app. It accepts a single location entry. I’ll go ahead and punch one in select Holiday Inn in Anaheim, and then when you submit it, it queries for a distance matrix from Salesforce Maps, and then it uses the data within that matrix response to display driving distance and driving times to two amusement park destinations. Let’s look at the Apex controller to better understand how we’re retrieving that data from our distance matrix query.

Our work begins in the search lame version controller method. We’re focusing on our distance matrix in this demonstration, so I’ll gloss over some of the data set up that we’re doing here. We know we have a source account and our destinations are preset to be two amusement parks that I have in our org. Our source account and our destination amusement parks represent all of the accounts that we need to include in our distance matrix query. Of course, all locations are formatted the way that the distance matrix API requires, which I’ll show you here, just like before in our previous videos, if you looked at how we were formatting the payload, we submit locations as a location ID with the latitude and the longitude. Okay, and back to the implementation right here, we invoke the Salesforce Maps API to request a distance matrix, and when we get our response, we’re starting the process of parsing through the data.
We’re getting back a map of data, so the next several lines involve us drilling down to the data that we need. We’ll eventually get to our location node, which gives us the ability to look at the key set in that map and retrieve the location IDs for all of our destinations. Let’s scroll down a little bit here.

As we iterate over our destinations, we need to conduct calculations. Our app requires distance to be represented in miles and our travel time to be represented in minutes. We need to do these conversions since we’re getting our distance return to us in meters and our time return to us in seconds. Scroll down just a bit more, and then finally, once our work is done, we can format a response that can be consumed by our lightning web component and rendered in the data table that you saw in the browser.

Okay, so this implementation works, but what inspired the creation of the TSS Maps open source utility for managing distance matrix queries was the desire for a series of classes and methods to more easily get to the data that you care about while leaving behind code that’s tight, clean and a lot easier to read. The TSS Maps utility attempts to reconfigure the distance matrix data in memory and serve it to your implementation in a way that’s very expressive while eliminating the need for data conversion formulas and iterating over data structure key sets. So let’s cover these concepts a bit more.

A distance matrix gets returned to us in a map consisting of one or more locations. We’re representing one location on the screen right here, so in this example, let’s say our distance matrix provides distances and drive times for a total of four locations. In that case, this one location would have three destinations.
A distance matrix is going to provide distances and drive time data for all locations as starting points and all locations as destinations. But this utility easily allows us to specify which location we want to focus on as our starting point, which is important because we know that distances and drive times differ when driving from A to B versus B to a due to route differences in other factors. Each destination in the distance matrix will also have a distance and a time object that represents unique values related to the destination and starting location. We want distance and time represented as objects here to allow us to provide utility methods in the case of distance. We provide utility methods for converting the value to kilometers, miles, or the standard meters value return from the API. In the case of time, we provide utility methods for converting the value to hours, minutes, or the standard seconds value returned from the API as well.

So all of that said the class diagram to provide us with easy access to the structure I just described looks a little bit like this. Let’s go ahead and take a closer look toward the top of the diagram. We see that our utility class returns an object called matrix, which provides us with the ability to get a handle on a location by its location id. A location is represented here by a class called Matrix location. That class provides helpful methods for getting a handle on either a single destination specified by its location ID or a method for getting a collection of all destinations. A destination is represented by a class called Matrix destination, so let’s go ahead and look at that. The matrix destination class represents one of any possible number of destinations associated to a starting location. Once you have a handle on the matrix destination instance, you can invoke a get distance method to get a distance object instance or get traffic by window, which will return one of eight possible matrix time instances that are representative of the eight possible traffic windows we discussed in our previous video.

Lastly, the matrix distance object gives us the ability to retrieve a distance value in either kilometers, miles, or meters, while the matrix time object gives us the ability to retrieve a time value in either hours, minutes, or seconds. Let’s go back to the code and see this in action. I’m back in the Apex controller. This time I’m looking at a controller method called search awesome version, which does the same work that search lame version does, but using our utility class TSS Maps instead, all the data is set up and formatted the same to start the process, but things change a little right here where we request our distance matrix. This time we’re invoking a method on our class, and we’re getting back an instance of matrix, which is an inner class of TSS Maps. We’re able to proceed by validating our success with a very simple is successful method that we didn’t have before.

We quickly get a handle on our location using the get location by ID method. In doing so, we can now comfortably iterate over all of our destinations using the get all destinations method. And then scrolling down a little bit here, you can see that we’ve simplified the implementation when writing our output for the L WC to consume. We’re now able to chain together some method, invocations calling, get distance and miles, and then get traffic by window and minutes, avoiding inline formulas and the need to add a conversion method to your controllers. Looking at these two methods side by side, you can see that it’s not a monumental change, but the more brief version that you see on the right side of the screen is less code. It’s significantly more expressive and easy to read, and it lifts away the burden of having to traverse the various levels of embedded maps.

To get your hands on this Apex class for your own implementations, head on over to the TruSummit Solutions GitHub page. The URL for our GitHub page can be found in the video description below. At the time of this recording, you’ll find our lone open source repository called TSS Maps right here and there. You’ll be able to peruse the code, clone or fork the repository, but also view documentation or conveniently install the class directly into your org from an unmanaged package. The class is open source with the GNU General public license. We already know that there’s plenty of opportunities for improvement on the class, so it’s not only not going to bother us, but it’s actually truly going to delight us if you opt to participate in enhancing our work in some way. So feel free to do so and share it with us. That’s going to conclude this video today. Please be sure to subscribe to our channel for more content of this type, and please like this video if you got something out of it, especially if you think you may use our TSS Maps utility, and I’ll see all of you in the next video.

Need help leveraging the latest Salesforce features and functionalities? Our developers are here for you! You know where to find TruSummit Solutions.  

Featured Articles

Ready to Get the Conversation Started?

We're happy to learn more about you, your business, and how we can help. No pressure, no pitches, just perspective.