Pull Google Maps traffic data into AdWords with this script library

San Francisco is the third-worst city in the United States for traffic congestion, according to a study by the 2015 Urban Mobility Scorecard. Commuters in San Francisco spend an extra 78 hours a year delayed in traffic, and as far as I can tell, it won’t be getting better any time soon.

Now that traffic information is so easy to access from any smartphone, your customers are likely checking and changing their behavior because of it. And when your customers change their behavior, you should be able to react.

Today, I’m happy to share a library I wrote to access Google Maps traffic data to determine commute times. By entering an origin, destination and departure time, you can quickly see how long a normal drive takes and how long the drive takes with traffic. Using that data, you can change your bids and Ad schedules or enable a set of Ads targeted directly toward those commuters.

Please note that I’m not advocating for you to advertise to commuters while they’re driving, but folks definitely use their phones while on public transport and as passengers in carpools and taxis. Additionally, people who deal with onerous commutes might have special needs, and you can use your ad creative at any hour to show you are aware of and feel their pain.

Introducing the Google Maps Distance Matrix API

Google Maps traffic information is available via the Distance Matrix API, and to access it, the only thing you need to do is to get a developer key from Google. You can call the service up to 2,500 times in a 24-hour period for free, which should be fine for most advertisers. (For all the details about quotas and the rate for additional calls, check out the usage limits page.)

Follow the instructions on the Google help page to generate a server key to use with this library. You can keep all the defaults, since the only thing that really matters is the final 40-character key. That’s what we will be using to call the library.

Don’t worry, I know a shortcut

Now that we have the server key, let’s take a look at the library I put together to access the API. As always, I’ll explain and give an example of how to use the code below.

The library is designed to work with all the parameters described in the documentation of the Distance Matrix API using the exact same names. The only required parameters are the key, the list of origins and the list of destinations, but if you want to get traffic estimates, you also need to pass in departure_time as per the documentation.

Keep in mind that you can add multiple origins or destinations, and Google will calculate the distances between each (hence the word “matrix” in the title). This is a good way to save on API calls. You can get the duration and the duration in traffic for any of the origins and destinations by using their index from the getOrigins and getDestinations function. Here’s an example of how to set up and use the library.

Accessing the Matrix

Here we are using multiple locations and accessing the results of Los Angeles, CA, to Palo Alto, CA, by passing in 1, 1 to the functions. If we wanted Los Angeles to Truckee, we would pass in 1, 0. Of course, if you are only passing in a single origin and destination, you can ignore those indices altogether, since they default to 0, 0. There is additional documentation in the library for each of the public functions.

Assuming you passed in a departure time, your response should have a duration and a duration in traffic, each with its own value. The difference between these two values indicates how delayed your customer is going to be on their way to or from their location.

Going further

Expanding on this example, you could start storing this data in a Google Sheet and use it to identify when the biggest traffic delays happen in the area you’re targeting. Each duration also returns a text field that you might be able to use in dynamic ad substitutions as well.

If you have some cool ideas of how you might use this information, make sure to let me know on Twitter. Happy commuting!