A Starter Guide to Google Maps API
There’s a natural instinct, as a new developer, to reach for the features that are visually impressive or instantly recognizable, and almost nothing satisfies that itch quicker than those little red markers on a green map… You know it and love it — Google Maps! When planning out features for my latest project, a simple hiking app, I knew this API was a feature I wanted to incorporate.
While there’s lots of helpful documentation on how to work with this feature, I wanted to distill map functionality down to its simplest form and to help anyone looking to use this API in a React project get their feature off the ground quickly.
Basics before the basics
I won’t be going into detail on how to get an API key for Google Maps since it’s very easy and Google does a great job of walking you through it already: https://developers.google.com/maps/documentation/javascript/get-api-key. I also won’t be going over how to hide your API keys, but if you’re curious on the best way to do this there are several helpful blogs on the subject. From this point forward I’ll assume you’ve got your key, hidden it, and are ready to start mapping.
Finding the best library
It sounds like a minor detail but take a little time to figure out which library or package seems like a good fit for your project. The documentation for the Maps JS API directs you to @googlemaps/js-api-loader to get started. I’m sure this one is great! But I‘m working with React for my front-end so the documentation was a little clunky and there are other libraries that have made use of React Hooks for working with the API. To make this as easy as possible I went in search of a Maps/React specific library.
Next, I found a useful blog tutorial that recommended the google-map-react package. Better! But when I went to install this I ran into another issue — this library didn’t seem to like that I had a version of React that was newer than 16.6. After a little more research I finally found @react-google-maps/api which perfectly fit the bill. As an aside to anyone interested in the petty details, this library is a rewrite of react-google-maps, a once-popular library that seems to have been gradually abandoned as it became less-and-less maintained.
You’ll notice a lot of these have extremely similar names, sometimes just with the words in a different order. It might seem odd that I’ve started our tutorial out here but this can be a surprising bump if you’re not careful. So let’s go ahead and install.
The bare minimum
Usually when implementing Google Maps on a site we’re looking for a map and a marker at the very least. To do this, you’ll need to import GoogleMap, useJsApiLoader, and Marker to your app. We’ll deal with the map first, and the marker in a minute.
At minimum we’ll need to establish four props that will get passed to our map: 1) a container, so that the map has some parameters on our page, 2) a center, so that the map knows how to orient itself, 3) zoom level, or how much area you’d initially like displayed on your map, and 4) a flag that tells us when the API has successfully loaded.
The first element, a container, is pretty simple — how do you want your map to appear on the page? In my case I wanted my map to appear as a kind of banner on the page, spanning the width. For one of my map views I wanted the map to center on a specific trailhead depending on the trail being displayed, so I passed down coordinates from the trail as props and plugged those into my center component. Here’s what we have so far:
Halfway there for our map component! For zoom, this is something that will depend on the scope of your map. Google gives some general guidelines for zoom level — a 1 is world level view, 5 a continent level view, 10 at city level, 15 shows you specific streets, while 20 would display details at the building level. I ended up choosing 11 as most hikes can be a little remote, so showing at least the city and surrounding towns was helpful.
The last element, which is React specific, is the hook we imported earlier, useJSApiLoader. This hook loads the Google Maps API and returns a flag, isLoaded, that will indicate when the API has successfully loaded, preventing any render errors. The hook has one required argument, your API key!
I’m also going to go ahead and create an options variable where I’ll remove the default UI from the map. The default includes features like the Pegman, options for satellite view, and a fullscreen button. None of these were very relevant for my use and make for a much cleaner map. Here’s what it looks like once we have all of our basic elements and how we pass these props to the GoogleMap component.
You can see in our return statement how we’re using the flag isLoaded from the useJsApiLoader hook to render the map once we’ve successfully connected to the API. And here’s what the map itself looks like:
Nice!
Marker… and action!
It’s looking great, but is it a Google Map if we don’t have a marker?? We’re in luck because it takes very little to make a marker happen. Our Marker component gets passed in as a child of the map and the only thing it needs is a position prop. Here, I’ll be using the same coordinates for the position that I used for our center prop.
And… voila!
Extra credit
I wanted to have a little fun with my marker and used a hiking boot for the icon since I’m building a hiking app. We can do this by utilizing the icon prop on our Marker component, and passing in a url link to whatever image we want to use. There will be a few other elements to specify, like scaledSize which sets how big the image is and anchor (the position at which to anchor an image in correspondence to the location of the marker on the map). Here’s what the final looks like on the app.
And the final code in React.
So there you have it!
Not all APIs are created equal and, all things considered, Google Maps is pretty user friendly, with many different user guides available. But it can time take to wade through all of the documentation and some of it can obfuscate more than it clarifies. This outlines the minimum requirements for getting a map up and running. If you’re curious about more advanced features for maps take a look at the official documentation. And if you want the functionality of this API with some added flare, head on over to Snazzy Maps which provides tons of free custom styles for Google Maps.
Links:
