13.7 - Using Application Programming Interfaces

So now we’re going to sort of change our perspective a little bit. We’ve been looking at sort of both sides of this data interchange, and now we’re going to look from sort of the producer and the consumer. And we’re going to be the consumer of this. There’s this thing called an application programming interface or API. And if you’re going to work and talk to this application, and you want to talk to it, we’re going to write our own application that’s going to make use of the services of another application, we want to know what the API is for that. The API is the specification for what the URL patterns are, what the syntax of the data we’re supposed to send, what the syntax of data we can expect to get back. And so the implementation is who we’re going to communicate with and we’re going to be the consumer. So I’d like to think of them as the producer of the API is the one that has the data and exports the API and defines the API. And then the consumer is the one that reads the documentation of the API, writes some code, and then complies with the rules of the API. And so here is, and it turns out it’s more common to be the consumer of the API than to be the provider of the API, or the producer of the API. So here’s an API that you can use, and we will use this in a couple of little assignments, called the Google Geocoding API. And so you’re like oh, I’ve got a bunch of addresses. And so a long time ago we did a survey where we took the addresses of all the people in the class and we just let them type that in, and those addresses are imperfect data and we could have hand-coded it. But it turns out that Google, because Google has Google Maps, they have an API that will take a rough approximation of an address like The Jerk Pit, Ann Arbor, Michigan. And it will clean that up and give you back details of what the formal name of that address, and what the exact GPS coordinates of that address are, etc., etc., etc. And that’s called geocoding. So Google exports that to us and there’s lots of data, and lots of computing, and lots of research, and lots of all kinds of things that make this geocoding API make our lives really simple because we just have to hit it and give it some data. And so the way this works if you were to read that documentation, is that you hit a URL, mapsgoogleapis.com and all the stuff is in the URL is in the documentation, and then you give it a parameter after this question mark, address equals, and then there’s a way that you encode these parameters. The plus is a space, Ann Arbor, and then the %2C is a comma, and that’s another space. So this is as if you typed this into a Google search box, Ann space Arbor, comma Michigan, that would be in the search box and then you hit the search button, right? But we’re going to do that search by talking to an API. And so we hit this URL and you can actually take this particular URL and you can type it into a browser. And when you type it into a browser you will get back some JSON, and if you look at the documentation it will tell you what the JSON is. And we’ve got a bit of code that you can play with, geojson.py, that has this in it. And then you have to do all the stuff, you’ve gotta do json.loads and all the things that we’ve been talking about in order to talk about this. And so here is a bit of code that does that. And so now we’re going to see, for the first time, the entire application. So we’re going to use urllib and we’re going to use JSON. And so it has this url as a string and then it’s going to read and ask for a location with an input. And then the address is what we type right here, so that goes into the string address. We make it so if we hit Enter by itself it breaks, then we’re going to make a URL by concatenating this URL. This urlencode address equals address, that’s the thing that turns this into the plus and this into the %2C, and this into the comma, right? And so this bit right here, that’s a concatenation. This bit right here, you don’t have to know what those rules are for putting those parameters on, but that’s what happens. And so this ends up being the URL, and then we print that out so that says retrieving the URL. We do a urlopen and then we get a handle back, remember the handle doesn’t actually pull the data down. But if I call the read method, uh.read, that does pull the entire document, all that text from that previous page, curly braces, square braces, etc. And remember that we have to decode it, because it’s probably UTF-8 out there. So we probably are going to hit Google and they’re going to give us UTF-8 data back. And so that’s like a string that’s coming from the outside world to the inside world, and now inside data we have a Python Unicode string. And now we just have a string, so it’s how much data. Now here we now have this loads, json.loads, which parses that data that we got back from Google. It came into this variable data, we’re going to parse it, and we’re going to get back, well let’s take a look. We’re getting back an object. So the outer thing, that’s what I was looking at, the outer thing is an object with curly braces, so that means it’s a Python dictionary that we end up getting. So that means that this thing that we get, js, is a dictionary. Now we have to have a, so there might be a failure or there’s other things, there might be a thing, so we’ve got to check a few things. If we’re looking for, if the js is a false or if the status key is not in that, that’s not in is Python, status is not one of the keys that is in the dictionary, or the status is not equal to OK. And so one of the things you’ll notice if you look at the specs, that status OK is part of the response if it worked. And so that’s a way for you to know that you didn’t get any good data, so the rest of the code actually doesn’t blow up. So that just is sort of I’m going to skip and print out a nasty message and print this data out. And then what I’m going to do is I’m going to walk my way down the tree. And so it’s got a dictionary, js sub results, and then it’s got a list, sub 0, which is the first result, and then that is a dictionary. And then I want to go geometry, location, and then latitude. So that’s sort of walking down the tree, and if you look at the data it’s the results. Geometry, results sub 0 which, because this is a list, sub 0, geometry, location, latitude. And so we basically extracted that little number, 422008, we extracted that right here. And again, it takes you a while to get these expressions right, and you test this code for a while, and I don’t write these all out. Maybe you can, but I tend to write this much and print that out, and then add another thing, and then add another thing, and say oh I got my 42 point whatever, and I’m happy. But, and I’m not giving you this one in XML, this would be a lot harder in XML because you’re doing gets, and gets, and finds, and gets, and finds. And now we’ve got a dictionary that contains a list, a list of dictionaries, and dictionary within dictionary within dictionary. And so that’s what this is, the outer bit is a dictionary. And within one key there’s a list, and within that the first item has another dictionary that has then another dictionary inside of it, right? So a dictionary that contains a list, that contains dictionaries, and each of those contains a dictionary. And so that’s, I mean, we didn’t make up this format, I mean, Google told us what the rules were and so we’re like oh thank you Google. And you can complain about that, but hey, Google just says you want to use our thing, learn this syntax, write this code. And so you can sort of cruise through there and print all that stuff out. So up next we’re going to talk about a Twitter API, which is a little bit more complex than the Google API.