Python API tutorial – An Introduction to using APIs
Application Program Interfaces, or APIs, are commonly used to retrieve data from remote websites. Sites like Reddit, Twitter, and Facebook all suggest certain data through their APIs. To use an API, you make a request to a remote web server, and retrieve the data you need.
But why use an API instead of a static dataset you can download? APIs are useful in the following cases:
- The data is switching quickly. An example of this is stock price data. It doesnвЂ™t truly make sense to regenerate a dataset and download it every minute вЂ“ this will take a lot of bandwidth, and be pretty slow.
- You want a petite chunk of a much larger set of data. Reddit comments are one example. What if you want to just pull your own comments on Reddit? It doesnвЂ™t make much sense to download the entire Reddit database, then filter just your own comments.
- There is repeated computation involved. Spotify has an API that can tell you the genre of a chunk of music. You could theoretically create your own classifier, and use it to categorize music, but youвЂ™ll never have as much data as Spotify does.
In cases like the ones above, an API is the right solution. In this blog post, weвЂ™ll be querying a elementary API to retrieve data about the International Space Station (ISS). Using an API will save us time and effort over doing all the computation ourselves.
The International Space Station.
APIs are hosted on web servers. When you type www.google.com in your browserвЂ™s address bar, your computer is actually asking the www.google.com server for a webpage, which it then comebacks to your browser.
APIs work much the same way, except instead of your web browser asking for a webpage, your program asks for data. This data is usually returned in JSON format (for more on this, checkout our tutorial on working with JSON data).
In order to get the data, we make a request to a webserver. The server then replies with our data. In Python, weвЂ™ll use the requests library to do this. In this Python API tutorial weвЂ™ll be using Python Trio.Four for all of our examples.
Type of requests
There are many different types of requests. The most commonly used one, a GET request, is used to retrieve data.
We can use a plain GET request to retrieve information from the OpenNotify API.
OpenNotify has several API endpoints. An endpoint is a server route that is used to retrieve different data from the API. For example, the /comments endpoint on the Reddit API might retrieve information about comments, whereas the /users endpoint might retrieve data about users. To access them, you would add the endpoint to the base url of the API.
The very first endpoint weвЂ™ll look at on OpenNotify is the iss-now.json endpoint. This endpoint gets the current latitude and longitude of the International Space Station. As you can see, retrieving this data isnвЂ™t a excellent fit for a dataset, because it involves some calculation on the server, and switches quickly.
You can see a listing of all the endpoints on OpenNotify here.
The base url for the OpenNotify API is http://api.open-notify.org , so weвЂ™ll add this to the beginning of all of our endpoints.
The request we just made had a status code of 200 . Status codes are returned with every request that is made to a web server. Status codes indicate information about what happened with a request. Here are some codes that are relevant to GET requests:
- 200 вЂ“ everything went okay, and the result has been returned (if any)
- 301 вЂ“ the server is redirecting you to a different endpoint. This can happen when a company switches domain names, or an endpoint name is switched.
- 401 вЂ“ the server thinks youвЂ™re not authenticated. This happens when you donвЂ™t send the right credentials to access an API (weвЂ™ll talk about authentication in a later post).
- 400 вЂ“ the server thinks you made a bad request. This can happen when you donвЂ™t send along the right data, among other things.
- 403 вЂ“ the resource youвЂ™re attempting to access is prohibited вЂ“ you donвЂ™t have the right permissions to see it.
- 404 вЂ“ the resource you attempted to access wasnвЂ™t found on the server.
WeвЂ™ll now make a GET request to http://api.open-notify.org/iss-pass , an endpoint that doesnвЂ™t exist, per the API documentation.
Hitting the right endpoint
iss-pass wasnвЂ™t a valid endpoint, so we got a 404 status code in response. We left behind to add .json at the end, as the API documentation states.
WeвЂ™ll now make a GET request to http://api.open-notify.org/iss-pass.json .
YouвЂ™ll see that in the last example, we got a 400 status code, which indicates a bad request. If you look at the documentation for the OpenNotify API, we see that the ISS Pass endpoint requires two parameters.
The ISS Pass endpoint comebacks when the ISS will next pass over a given location on earth. In order to compute this, we need to pass the coordinates of the location to the API. We do this by passing two parameters вЂ“ latitude and longitude.
We can do this by adding an optional keyword argument, params , to our request. In this case, there are two parameters we need to pass:
- lat вЂ“ The latitude of the location we want.
- lon вЂ“ The longitude of the location we want.
We can make a dictionary with these parameters, and then pass them into the requests.get function.
We can also do the same thing directly by adding the query parameters to the url, like this: http://api.open-notify.org/iss-pass.json?lat=40.71&,lon=-74 .
ItвЂ™s almost always preferable to setup the parameters as a dictionary, because requests takes care of some things that come up, like decently formatting the query parameters.
WeвЂ™ll make a request using the coordinates of Fresh York City, and see what response we get.
The ISS over Fresh York.
Loving this post? Learn data science with Dataquest!
- Learn from the convenience of your browser.
- Work with real-life data sets.
- Build a portfolio of projects.
Working with JSON data
You may have noticed that the content of the response earlier was a string (albeit it was shown as a bytes object, we can lightly convert the content to a string using response.content.decode(“utf-8”) ).
Strings are the way that we pass information back and forward to APIs, but itвЂ™s hard to get the information we want out of them. How do we know how to decode the string that we get back and work with it in Python? How do we figure out the altitude of the ISS from the string response?
Python has excellent JSON support, with the json package. The json package is part of the standard library, so we donвЂ™t have to install anything to use it. We can both convert lists and dictionaries to JSON, and convert strings to lists and dictionaries. In the case of our ISS Pass data, it is a dictionary encoded to a string in JSON format.
The json library has two main methods:
- dumps вЂ“ Takes in a Python object, and converts it to a string.
- geysers вЂ“ Takes a JSON string, and converts it to a Python object.
Getting JSON from an API request
You can get the content of a response as a python object by using the .json() method on the response.
The server doesnвЂ™t just send a status code and the data when it generates a response. It also sends metadata containing information on how the data was generated and how to decode it. This is stored in the response headers. In Python, we can access this with the headers property of a response object.
The headers will be shown as a dictionary. Within the headers, content-type is the most significant key for now. It tells us the format of the response, and how to decode it. For the OpenNotify API, the format is JSON, which is why we could decode it with the json package earlier.
Finding the number of people in space
OpenNotify has one more API endpoint, astros.json . It tells you how many people are presently in space. The format of the responses can be found here.
Python API tutorial: Next steps
Now youвЂ™ve finished our Python API tutorial, you now should be able to access a plain API and make get requests. There are a few other types of requests , which you can learn more about, along with working with API authentication, in our dataquest APIs and scraping course.
Other recommended next steps are reading the requests documentation, and working with the Reddit API. ThereвЂ™s a package called PRAW that makes working with the Reddit API lighter in Python, but itвЂ™s recommended to just use requests at very first to learn how everything works.
Pic Credit: Web API by Jonathan CoutiГ±o from the Noun Project.