Summary

The article provides a concise guide on using the Google Maps Places API in R, demonstrating how to retrieve point of interest data with minimal code by leveraging the googleway R package.

Abstract

The Google Maps Places API allows users to programmatically access information from Google Maps, such as locations of Mexican food restaurants in downtown Raleigh, NC. The article explains that while the API doesn't return all visible results, it provides a sampling based on relevance, location, and paid advertisements, with a maximum of 60 results per search. The googleway R package simplifies the API interaction, requiring only an API key and a few lines of code to perform searches and access detailed place information, including coordinates, ratings, and categories. The author emphasizes the need for targeted searches, the use of next_page_token to retrieve up to 60 total results in batches of 20, and encourages experimentation within the $200 monthly free credits provided by Google Cloud. The article also touches on the importance of understanding the API's Terms of Service and the broader capabilities of the googleway package for various geospatial analyses.

Opinions

The author finds the Google Maps Places API exciting for its potential to unlock point of interest data but initially found the documentation challenging to navigate as a non-software developer.
The author believes that the implementation of the API in R is even easier than in Python, thanks to the googleway R package.
The author suggests that the API's search results are influenced by the center point and zoom radius of the map, similar to the Google Maps interface, and advises users to be specific with their searches.
The author appreciates the wealth of information provided by the API for each place and acknowledges the need for additional code to access some of the data.
The author encourages users to take advantage of the free credits offered by Google Cloud to explore and learn how the API returns results, suggesting that smaller search radiuses can improve result precision.
The author highlights the ease of use and extensive functionality of the googleway R package, praising the developer for making API access more approachable and unlocking more interesting use cases and applications.

How to Use the Google Maps Places API in R

Unlock point of interest data using 2 lines of code in R

When I learned about the Google Maps Places API, I was excited by the possibilities that the API unlocks, but left confused as a non-software developer trying to decipher the documentation. So, I wrote up an article to give a step-by-step guide on how to use it in Python for others facing the same challenge.

I mentioned in the article that the code could easily be transitioned to R, but left it at that. I’ve found myself using R recently, and it turns out the implementation of the API in R is even easier than Python.

What is the Google Maps Places API?

Simply put, the Google Maps Places API is a way to access information you’d find when searching Google Maps. If I want to find Mexican food in downtown Raleigh, NC, I’d search on Google Maps and see what pops up. The Places API is a way to programmatically source the results that pop up.

An open ended search for Mexican food in Raleigh, NC on Google Maps; Image by Author

A point to note, though, is that the results will not return every result in view. Consider how the results on your screen change depending on the center point of your map and zoom radius.

An example of the same search with two zoom levels. Note how on the left, there are only 4 locations in the bottom right of the map, but in the right-side image, there are 10 locations in that same area when zoomed in. Your zoom level affects your results, just as it will in the API call.

Google provides a sampling of the results depending on its relevance, location, paid advertisements, etc. It’s easy to think that you can just input a wide search radius and get all results, but no such luck. Plus, each search is limited to a maximum of 60 results.

So, be targeted and specific with your searches when using the API.

How to Use the Google Maps Places API

The googleway R package dramatically simplifies the process of accessing the Places (and other Google Maps) API’s, in addition to preparing the data in an easy-to-use format.

Install the package just as you would any other with install.packages('googleway') and load the package with library(googleway).

To use the package — and any Google API — you’ll need to set up a Google Cloud account and generate an API key. Here are instructions on how to do that. You’ll get $200 in free credits per month for Maps-related API billing, which is the equivalent of about 11,750 searches, so you’d have to work pretty hard to exceed the free limit.

When you have your API key, you’re ready to access the point of interest data in as little as 2 lines of code:

Line 1: Use the google_places function to make a call to the API and save the results

Line 2: Access the search results

To work most effectively, the google_places function takes a search string, location, radius, and your API key.

google_places(search_string = 'mexican food', location=c(35.77936902425637, -78.63995745574967), radius=3218, key=gmaps_key)

The search_string is simply the search we want to execute.
The location is the latitude and longitude of the center point for our search (here, downtown Raleigh) inputted as a vector. I usually just right click on the place I want to search in Google Maps and it will generate the coordinates as the first menu result.
The radius is the distance in meters that we want to search. Here, I converted 2 miles to meters for about 3,218 meters
The key is the API key. I’ve saved it as a separate variables, gmaps_key, but you could input it directly (in quotes) if you were only doing one search.

When you run the code, you’ll see two boxes pop up in R Studio. First is a “response” page and second are the results.

The response page provides you with the next_page_token (more on that later), the status of your request (“OK” means good to go, otherwise problems), and your results.

Example response page for the above search; Image by Author

To access the data, either click into the data frame as the second popup, or — assuming you’ve saved your search — access it by running variable_name$results. I’ve saved my results to the variable search_str so I call the results with search_str$results.

Example to access just the data frame of your results

The data frame will give you a wealth of information about each place, including its address, latitude & longitude coordinates, price level, star rating, number of ratings, categories, and more. Some of these are readily available, and some of them you’ll need to write a bit more code to access.

To get the latitude and longitude coordinates, for example, you need to access the data frame within each value in the geometry row above, then within location. Use the code variable_name$results$geometry$location to access the coordinates.

If you want to bind them back to your original data frame, just run the code:

variable_name$results %>%
 cbind(., variable_name$results$geometry$location)

This will add the latitude and longitude as columns to your search results. Likewise, if you want to access the types, use the dollar sign notation for the types column to access that information.

You may have noticed there were only 20 results even though I said it returns up to 60. This could mean there were only 20 total results, but usually it means something else.

Each API call returns up to 20 results, and a search can return up to 60 total places. This effectively means that to access all 60 results, you need to execute 3 calls to the API. The next_page_token that I mentioned above is how we’ll access the next (up to) 20 results.

To do this, run another search using the same search criteria, but this time add one more parameter to the function, the page_token.

google_places(search_string = 'mexican food', location=c(35.77936902425637, -78.63995745574967), radius=3218, key=gmaps_key, page_token = search_str$next_page_token)

The page_token is the way to tell Google to return the next 20 results in the search instead of the first 20. If you’ve saved your initial search, you can add the next_page_token directly by calling variable_name$next_page_token.

If you want to return the last 20 results (places 40–60), you can access the next_page_token from your second search and insert it into the page_token parameter.

If there’s no next_page_token, then there either (1) weren’t more results than are already showing or (2) you’ve already maxed out your 60 results.

Other Things to Know

It’ll take a couple searches to get the hang of how the API returns results, but with $200 in free credits, I encourage you to test and learn early on.

Smaller search radiuses will give you more confidence that all your desired results are showing up, but if you’re trying to look in a wider region, you’ll have to execute more searches. It’ll take some iteration to find the trade off that’s right for your use case. (Run a couple test searches on Google Maps if this point is confusing and see how the results change based on your zoom level. The API acts the same way — some results will appear, others won’t, but at more zoomed in levels, your precision will improve.)

Be sure to understand how the Terms of Service affect your use case, particularly around licensing and use of the data.

The googleway R package has significantly more functionality than just the google_places function. If you want to geocode, find distances between points, get directions, or more, this is your place to go.

I can’t emphasize enough how much easier the developer made the process of accessing the Google Places APIs, and with easier access unlocks more interesting use cases and applications.

Want to talk more location analytics? Connect with me on LinkedIn.