3MW (Making authenticated API calls)

Guten Tag!

Many greetings from Munich, Germany. Remember our goal from last week? You know, building a dashboard disguised as a weather app? I mean this one here:

Last week, we learned a bit about APIs and how to call the API of the US National Weather Service with {httr2}. All we had to do was know the coordinates of the location we want to check the weather for. So this bears the question: How do we get coordinates in the first place?

This requires hitting the API of a geocoding service like the one from Google Maps. Unfortunately for us, Google requires us to make an authenticated call. Thus, calling the API becomes a bit more tricky. And that’s what we’ll learn today. But before we do that, time for my usual announcement.

Correlation Heat Maps

Correlation heat maps are a great tool to visualize association between variables in your data. But they also require some work because there are some things that can easily go wrong. My newest video shows you how to avoid these pitfalls:

Like every week, the code that you see in the code chunks can be found on GitHub.

Creating a Geocode API

Essentially what we want to do this week is to send addresses like “1900 E Kenwood Blvd, Milwaukee, WI 53211, USA” to Google and get coordinates back. (Fun fact: this address refers to the Physics building of UW-Milwaukee where many of the math TAs have their office. At least it was like that when I was a math TA there.)

If you look at the Get Started Page of Google’s geocoding API, you will find a URL that looks like this:

https://maps.googleapis.com/maps/api/geocode/json?address=1600+Amphitheatre+Parkway,+Mountain+View,+CA&key=

If you inspect this closely, you will find

  • a question mark ? followed by

  • address=,

  • some stuff that looks like the address “1600 Amphitheatre Parkway, Mountain View, CA” encoded into a URL, and

  • key= 

And if you follow the link you will get an error message like this:

Authenticate!

Aha! The video game player in me has found enough evidence that tells me that we must find a key that we can fit into key=. And just like in a video game, this might entail a whole different quest first.

In this case, we will have to take a good look at the getting started guide again (get used to reading API docs to find out how to operate them 😭). This will reveal a crucial hint:

So I guess we follow the link into the Cloud Console which leads us into yet another doc page:

So we follow the big blue button and do all the steps to create a new project. Unfortunately, this will require us to also put in some billing information and we cannot get around that. Don’t worry the geocoding service has a generous free tier and you will not actually get billed until you manually upgrade to a paid tier.

A project is nothing without an API

Nice, we’ve is set up a new Google project. Inside of these projects we can use different APIs such as the geocoding API. The easiest way to enable that for our project is to follow the big blue button from the docs:

This is where we can acquire an API key for our project and for security we can enable that the geocoding API shall be the only API the key can unlock.

Once that is done, you’re on your project dashboard and you can head to the Credentials page. There, the “Show Key” link will lead you to your API key.

API Key Security

I’m not a security expert but here’s a word of caution for you: ⚠️ DO NOT SHARE YOUR API KEY WITH ANYONE. ⚠️ 

This includes not putting your API code into your R script or any other type of script. Why? Because you might want to put your code into a public repo on GitHub long after you have forgotten that you put your API key in a script file.

Same thing goes for the R console. You might share your console history as part of a repo by accident. Then, someone could just look up your API key in your R console history.

So what to do instead? It’s simple really. It’s called using “environment variables”. Usually, what you do is store an .env file (the dot is important) inside your project repository. (Put that file into .gitignore immediately!)

With dotenv::load_dot_env() you can then enable access to your .env file such that Sys.getenv('<Variable_name>') can access your API key. For example, if your API-key is 123, you could store API KEYS in the .env file as

Then, Sys.getenv('GEOCODE_API_KEY') would return the API key 123. But you don’t want to execute this code directly! What you want to do instead is use that inside of functions that need the API key like this one here:

Using query parameters

This code uses the URL that we have seen earlier. You know, the one that was followed by a ?, address=... and key.... In this scenario, everything that comes before the ? is the base URL for our API call. And everything after the question mark is the query to the API.

As we know, this query need to have an address and a key. Luckily for us {httr2} makes it easy to append that stuff to the URL via req_url_query(). Once the new URL is assembled, we just have to perform the request.

Fun fact: These queries are everywhere. For example, just click on any link in this newsletter. Your browser will lead you to the desired website but the URL will also contain something like ?utm_source=3mw.albert-rapp.de.

Congrats, you now know how tracking for marketing works. That’s the exact same technique how, say, my YouTube analytics dashboard knows how many people headed from my newsletter to my videos.

Getting the coordinates

Anyway, we can evaluate our API response just like we learned last week. Here’s how it looks.

And by drilling down into the right parts with pluck() we find our desired coordinates:

Hooray! We can now find the coordinates for any address in the US. If that’s not cause for celebration, then I don’t know what is. Have fun celebrating and see you next week 🥳 And as always, if you want to reach out to me, just reply to this mail or find me on LinkedIn.

See you next week,
Albert 👋

Enjoyed this newsletter and found something helpful? Here are other ways I can help you:

Reply

or to participate.