#Day21 - How to use requests to interact with APIs in Python
Want a list of cool APIs to use for your next project?
Today we will be working with the requests libraries and use it to make requests to some public APIS. I have also included a few resources that have a list of cool APIs. This article will not talk about what an API is or the different status codes. Some familiarity with APIs is expected. We will be discussing the following
- Making a simple GET Request
- The Response Object
- Making a Request with parameters
- Make a GET Request to a secured endpoint
- Making a POST Request
- APIs you can use for your next project
Make a GET Request
Starting off with the basics, we will try to make a request to the publicly available Cat Facts API
We will be making a request to the following endpoint
https://cat-fact.herokuapp.com
The following code-snippet makes a request to the endpoint
import requests
url = "https://cat-fact.herokuapp.com"
response = requests.get(url)
print(response)
print(type(response))
You should see the following output
<Response [200]>
<class 'requests.models.Response'>
The get() function returned a Response Object. We will talk about the response object in the next section.
Let's try making another GET request. This time we will make a request to the Dog Facts API. This is the endpoint we will making the request to
https://dog-facts-api.herokuapp.com/api/v1/resources/dogs/all
Below is the code snippet
url = "https://dog-facts-api.herokuapp.com/api/v1/resources/dogs/all"
response = requests.get(url)
print(response)
print(type(response))
You should see a similar output as the previous output. So how do we use the Response Object to access the data we need?
Response Object
Let's continue working with Dog Facts API. The following snippet of code will help us introspect the returned Response object
print(dir(response))
You will see a list with a bunch of stuff. Focus on the last few.
status_code
This contains the status code of our request. For a successful GET request, it should be 200.
print(response.status_code)
'''
OUTPUT
200
'''
url
This contains the URL of the response.
print(response.url)
'''
OUTPUT
https://dog-facts-api.herokuapp.com/api/v1/resources/dogs/all
'''
ok
This is true if the status code is less than 400
print(response.ok)
'''
OUTPUT
True
'''
json
This returns a JSON object of the result. Basically the data we want to access. If the data returned by the endpoint is not in a JSON format, it will raise an error. Most API endpoints usually return data in a JSON format, it's good practice.
print(response.json()[0])
'''
OUTPUT
{'fact': 'All dogs can be traced back 40 million years ago to a weasel-like animal called the Miacis which dwelled in trees and dens. The Miacis later evolved into the Tomarctus, a direct forbear of the genus Canis, which includes the wolf and jackal as well as the dog.'}
'''
I am only displaying the first fact in the list but you can try it out on your own without the indexing.
text
This contains the result in Unicode format, i.e a string object. The output might look similar to the one returned by json() but if you use type() to inspect the type of the returned data, you'll notice it is a string
print(response.text)
print(type(response.text))
'''
OUTPUT
{
"fact": "Fifty-eight percent of people put pets in family and holiday portraits."
},
{
"fact": "There are only 350 Cisky Terriers in the world, possibly making it the rarest breed."
},
.............
<class 'str'>
'''
I have truncated the output since it was too long.
Making a Request with parameters
Some endpoints accept parameters. The Dog Facts API accepts a couple of parameters
- num: to specify the number of facts you want to receive
- index: to specify the index of the fact you are targeting There are a couple of ways to include parameters in your request
Including parameter in URL
You can include the parameter in your URL with a ""?parameter=value"". Be careful to use the base URL. In our case, the base URL is the following
https://dog-facts-api.herokuapp.com/api/v1/resources/dogs
Our URL with the parameter included would be the following
https://dog-facts-api.herokuapp.com/api/v1/resources/dogs?number=2
Below is the code to make a request to get 2 facts.
url = "https://dog-facts-api.herokuapp.com/api/v1/resources/dogs?number=2"
response = requests.get(url)
print(len(response.json()))
'''
OUTPUT
2
'''
Including a parameters object in the get request
Another way would be to set the "params" argument in the get() function to our parameter. Below is the code
import requests
url = "https://dog-facts-api.herokuapp.com/api/v1/resources/dogs"
param_obj = {"number" : 2}
response = requests.get(url, params=param_obj)
print(len(response.json()))
print(response.url)
'''
OUTPUT
2
https://dog-facts-api.herokuapp.com/api/v1/resources/dogs?number=2
'''
As you can see, "response.url" contains the URL with the parameter included.
Make a GET Request to a secured endpoint
Most APIs are secured to prevent malicious requests. An API key is needed whenever you make a request to the API. We will be working with Cats API. This is different from the first Cat Facts API we used, this is secured. Before proceeding, get your API key from here.
We should follow best practices when dealing with API keys. The API key must not directly be used in your python file. It must either be used as an environment variable or stored in a .env file. The API key must be loaded in the Python file, so as to hide it from others.
- Create a file named ".env" in the same folder as your python file and paste the following
Add your API Key as the stringAPI_KEY = "YOUR API KEY HERE"
- Install the following library
pip install python-dotenv
- Load the API Key
import os
import dotenv
dotenv.load_dotenv()
API_KEY = os.getenv("API_KEY")
print(API_KEY)
Now let's add the API key while making the requests. Some API let you add it as a parameter (refer to the specific API's documentation for more instructions. Another way is to include it as a header while using the get() function
import requests
import os
import dotenv
dotenv.load_dotenv()
API_KEY = os.getenv("API_KEY")
headers = {'x-api-key': API_KEY}
url = "https://thecatapi.com/v1/images"
response = requests.get(url, headers = headers)
print(response.status_code)
Again, the key in the header's object can vary from one API to another. But the general format of making a request to a secured endpoint remains the same.
Making a POST Request
Making a Post request is similar to making a get request. Instead of the get() method, we used the post() method. We will make a POST request to the following API. The following endpoint supports a POST Request
https://jsonplaceholder.typicode.com/posts
A post request requires some payload/data to be included in the request. The post() method has a parameter called "data" and our object can be passed as an argument to that.
import requests
url = "https://jsonplaceholder.typicode.com/posts"
data = {
"userId": 1,
"title": "#DAY21",
"body": "Today is #DAY21 of #100daysofcode"
}
response = requests.post(url)
print(response.status_code)
- If the POST request was successful, you should get a status_code of 201
- Ensure your data object follows the proper documentation as provided in the documentation.
APIs you can use for your next project
Below is a list of resources with a list of APIs (A list of lists)