JRL About

Batch Geocoding a List of Addresses with Google Maps

March 11, 2017
Updated: November 30, 2021

Twitter Hacker News Reddit LinkedIn
Article Header Image

ecently I needed to convert a few thousand store locations to their geographical coordinates, formal address, and find the distance separating them. Leveraging the power of the Google Maps API Libraries, this becomes a relatively simple endeavor and you can see the outcome in the box below. If it's not working the key is likely over its daily limit, open dev tools (F12) and check the console for errors.

If you're not a programmer and don't care about implementation, check out the "Non-Programmers" section.

Getting an API Key

API stands for Application Programming Interface - it is Google's JS client library for Maps Services that lets us access Google's data and algorithms for finding all this geocoding stuff. We could set up a system to scrap the addresses off of Google Search results, but then Google would get mad for stealing their server time without permission and block you. An API Key is a secret password to let Google keep track of all your API calls, and apply a limit once you've reached the max (and give you the option to pay for more). To get one, log into your Google account, visit the Get a Key site, and click the blue button that says "Get A Key".

Create a New Project
Once you click the button, create a new project
Name the Project
Name your project...
save key value
Now you have the key! Save the value that appears in the black box

Restricting the API Key

Our key is going to live on the client, which will enable all users to read it and potentially use it. To stop that, log into console.developers.google.com, navigate to "Credentials", open up your project, and modify your key restrictions. This enables Google to block requests that originate from unauthorized sources, and prevents others from stealing your API uses.

Restrict key access
Restrict key access

How to get those addresses

Now that we have the key, let's check out the code.

Look at the code itself and its comments to learn more, but to summarize, we first load jQuery and the Google Maps JS library (be sure to replace the key). Callbacks are setup for each button with its two corresponding functions to (1) parse text and return request objects and (2) use those objects to query Google Maps Services. Each query returns a Promise, which is essentially a placeholder for the asynchronous search to finish. After all searches are started, we wait for all the promises to complete with Promise.all. Then the results are printed to the screen. You can also view this file on GitHub.

One very important thing to note is that this code does not return/print all the data made available in this API. If you want more, you can open the console to view the complete result or check out the Google APIs for full documentation.

Using the Web API instead of the Places Library

If you want to run this in a production environment, instead of a one-off query for a project, you might not want to load the Map's JS library. In that case, you can use the Rest API and ajax requests. This is not possible to do from a file on your machine (localhost/filesystem), as CORS issues will block a simple JSON request, and the web API is not set up for JSONP. Thus, you need your own server that accepts CORS requests from the Google maps service.

If you didn't understand what that meant, then just use my example/the Maps library. I still don't really understand what it means, but I know it has caused me to lose many hours trying to figure out implementation details.

The code would be pretty much the same, except no need to load the Maps library in the head. Then, we would need to stop usign the services library to search (e.g. service.textSearch(query,callback)) and instead use an ajax request:

//use jQuery's ajax command to hit Google's REST API. If you want to be even more spartan, use JS's XMLHttpRequest instead of ajax. You do you!
const query = 'https://maps.googleapis.com/maps/api/place/textsearch/json?query=' + place + '&key=' + key;
  url: query,
  type: "GET",
  crossDomain: true,
  dataType: "json",
  success: function(response) {
  error: function(xhr, status) {

From there you can modify the success callback to use the response as you please.


Nothing here is too crazy Computer Science-wise, but it can be very difficult to navigate Google's extensive documentation and sift through what is and is not relevant. So hopefully this guide is useful to programmers too.

For non-programmers this difficulty increases exponentially. People like scientists, students, business people, etc need to use this data for their own good reasons. If that's you, feel free to just use the online example and ignore the code. If it's not working, try getting your own API key (see first section), right click this link, choose "Save as …", download the file, open it in Notepad, and search for this text: "key=". Replace the long text following it with your own key.

If the output is not enough info for you and you need more, you'll unfortunately have to get your hands dirty and modify the code (or bribe a friend with some pizza or something). For that, I'd first settle on what your exact needs are, then read the Google API documentation starting from their GitHub Repo, and finally come back to this tutorial's code.

Good luck everyone!