Python requests Response Object Explained

In this tutorial, you’ll learn how to use the Response object from the Python requests library. When you make a request using the Python requests library, a Response object is returned. This is true, regardless if it’s a GET, POST, PUT, or another type of request.

Knowing how to work with the Response object from the requests library is an important skill. The object has many helpful attributes and methods you can use to learn more about the request.

By the end of this tutorial, you’ll have learned

• What the Python requests.Response object is
• How to check whether a request was successful or not using the Response object
• What attributes and methods are available to learn more about the Response object from the requests library

What is a Python requests Response Object?

The Python requests library returns a Response object when any type of request is made, including POST and GET requests. The Response object contains useful attributes and methods that help in understand the response.

Before diving further, let’s see how we can create a Response object and verify its type:

# Getting a requests Response Object
import requests

resp = requests.get('https://reqres.in/api/users')
print(type(resp))

# Returns: <class 'requests.models.Response'>

We can see that when we make a request, in this case a GET request, a Response object is returned. We can see what methods and attributes are available by using the dir() function, which creates a list of attributes and methods.

Let’s pass Response object into the Python dir() function:

# Returning a List of Methods and Attributes
import requests

resp = requests.get('https://reqres.in/api/users')
print(dir(resp))

# Returns: 
# ['__attrs__', '__bool__', '__class__', '__delattr__', '__dict__', '__dir__', '__doc__', '__enter__', '__eq__', '__exit__', '__format__', '__ge__', '__getattribute__', '__getstate__', '__gt__', '__hash__', '__init__', '__init_subclass__', '__iter__', '__le__', '__lt__', '__module__', '__ne__', '__new__', '__nonzero__', '__reduce__', '__reduce_ex__', '__repr__', '__setattr__', '__setstate__', '__sizeof__', '__str__', '__subclasshook__', '__weakref__', '_content', '_content_consumed', '_next', 'apparent_encoding', 'close', 'connection', 'content', 'cookies', 'elapsed', 'encoding', 'headers', 'history', 'is_permanent_redirect', 'is_redirect', 'iter_content', 'iter_lines', 'json', 'links', 'next', 'ok', 'raise_for_status', 'raw', 'reason', 'request', 'status_code', 'text', 'url']

In the following section, you’ll learn how to use the most important attributes and methods of the Response object.

Checking the Status of a Python requests Response Object

Understanding whether or not a request was successful is, of course, a very important part of understanding a response. The requests.Response object provides a number of different ways to do this. Let’s explore two key attributes:

1. Response.status_code returns an integer value representing the status of the response
2. Response.ok returns a boolean value indicating success

Let’s see how we can use both of these attributes to check the status of a request:

# Checking the Status of a requests.Response Object
import requests

resp = requests.get('https://reqres.in/api/users')
status_code = resp.status_code
status_ok = resp.ok

print(f'The status code is {status_code}.')
print(f'The response is {status_ok}.')

# Returns: 
# The status code is 200.
# The response is True.

Let’s break down what we did in the code above:

1. We created a Response object by using the get() function
2. We then created two variables accessing the status code and status, respectively

The .ok attribute will return True if the status code returned is less than 400.

We can use these attributes to build a conditional flow in our program. Let’s see how we can do this:

# Building an if-else Block Using a Response's status
import requests
resp = requests.get('https://reqres.in/api/users')

if resp.status_code < 400:
    print('Response is ok!')
else:
    print("Response isn't ok!")

# Returns: Response is ok!

While the code above works, it’s not the most Pythonic. One of the nice features of the requests library is that it actually returns an intrinsic boolean value.

We can simplify the code above by writing:

# Simplifying Our Check if a Response Was Successful
import requests
resp = requests.get('https://reqres.in/api/users')

if resp:
    print('Response is ok!')
else:
    print("Response isn't ok!")

# Returns: Response is ok!

The code above checks the truthy-ness of the Response object itself. This makes the code significantly cleaner and easier to follow.

In the following sections, you’ll learn how to use others attributes to access the data in the response.

Checking the Body of a Python requests Response Object

A common task you’ll want to take on is seeing the body of a response that gets returned when a request is made. There are a number of simple ways in which we can do this:

1. .content returns the actual content in bytes
2. .text returns the content converted to a string, using a character encoding such as UTF-8

Both of these methods work well for accessing the content of the response. Using the .text attribute simply converts the values to a string for easier access.

Let’s see how we can use the .text attribute to access the string of the content:

# Accessing the Body of a Response Object
import requests
resp = requests.get('https://reqres.in/api/users')

print(resp.text)

# Returns: 
# {"page":1,"per_page":6,"total":12,"total_pages":2,"data":[{"id":1,"email":"[email protected]","first_name":"George","last_name":"Bluth","avatar":"https://reqres.in/img/faces/1-image.jpg"},{"id":2,"email":"[email protected]","first_name":"Janet","last_name":"Weaver","avatar":"https://reqres.in/img/faces/2-image.jpg"},{"id":3,"email":"[email protected]","first_name":"Emma","last_name":"Wong","avatar":"https://reqres.in/img/faces/3-image.jpg"},{"id":4,"email":"[email protected]","first_name":"Eve","last_name":"Holt","avatar":"https://reqres.in/img/faces/4-image.jpg"},{"id":5,"email":"[email protected]","first_name":"Charles","last_name":"Morris","avatar":"https://reqres.in/img/faces/5-image.jpg"},{"id":6,"email":"[email protected]","first_name":"Tracey","last_name":"Ramos","avatar":"https://reqres.in/img/faces/6-image.jpg"}],"support":{"url":"https://reqres.in/#support-heading","text":"To keep ReqRes free, contributions towards server costs are appreciated!"}}

We can see that the response is actually serialized JSON content. While you could use the json library to convert the .text attribute to serialize the data, this can feel a bit clunky. In the following section, you’ll learn how to serialize a Response object using the .json() method.

Converting a Python requests Response Object to JSON

The requests library allows you to easily serialize the data using the .json() method. Let’s see how we can do this using the requests library:

# Serializing a Response Object
import requests
resp = requests.get('https://reqres.in/api/users')
response_dict = resp.json()
print(response_dict)

# Returns: 
# {'page': 1, 'per_page': 6, 'total': 12, 'total_pages': 2, 'data': [{'id': 1, 'email': '[email protected]', 'first_name': 'George', 'last_name': 'Bluth', 'avatar': 'https://reqres.in/img/faces/1-image.jpg'}, {'id': 2, 'email': '[email protected]', 'first_name': 'Janet', 'last_name': 'Weaver', 'avatar': 'https://reqres.in/img/faces/2-image.jpg'}, {'id': 3, 'email': '[email protected]', 'first_name': 'Emma', 'last_name': 'Wong', 'avatar': 'https://reqres.in/img/faces/3-image.jpg'}, {'id': 4, 'email': '[email protected]', 'first_name': 'Eve', 'last_name': 'Holt', 'avatar': 'https://reqres.in/img/faces/4-image.jpg'}, {'id': 5, 'email': '[email protected]', 'first_name': 'Charles', 'last_name': 'Morris', 'avatar': 'https://reqres.in/img/faces/5-image.jpg'}, {'id': 6, 'email': '[email protected]', 'first_name': 'Tracey', 'last_name': 'Ramos', 'avatar': 'https://reqres.in/img/faces/6-image.jpg'}], 'support': {'url': 'https://reqres.in/#support-heading', 'text': 'To keep ReqRes free, contributions towards server costs are appreciated!'}}

Now, we can access different items in the dictionary using its key. We can access the value for the 'page' key by using dictionary methods:

# Serializing a Response Object and Accessing an Item's Values
import requests
resp = requests.get('https://reqres.in/api/users')
response_dict = resp.json()
print(response_dict.get('page'))

# Returns: 1

In the code above, we first serialize the response using the .json() method. We can then use dictionary methods to access values in the resulting dictionary.

In the following section, you’ll learn how to access and understand the headers of a Python Response object using the requests library.

Checking the Headers of a Python requests Response Object

In the previous sections, you learned how to access the content of the Response object. There are times, however, when you may want to access the metadata of the request. This can be done using the headers of the Response object.

The headers of a response can give us a lot of useful information, including the content type of the payload. Let’s see how we can use the .headers attribute to access information about the response’s headers:

# Checking the Response Headers
import requests
resp = requests.get('https://reqres.in/api/users')
print(resp.headers)

# Returns: 
# {'Date': 'Tue, 26 Jul 2022 11:53:27 GMT', 'Content-Type': 'application/json; charset=utf-8', 'Transfer-Encoding': 'chunked', 'Connection': 'keep-alive', 'X-Powered-By': 'Express', 'Access-Control-Allow-Origin': '*', 'Etag': 'W/"3e4-2RLXvr5wTg9YQ6aH95CkYoFNuO8"', 'Via': '1.1 vegur', 'Cache-Control': 'max-age=14400', 'CF-Cache-Status': 'HIT', 'Age': '653', 'Expect-CT': 'max-age=604800, report-uri="https://report-uri.cloudflare.com/cdn-cgi/beacon/expect-ct"', 'Report-To': '{"endpoints":[{"url":"https:\\/\\/a.nel.cloudflare.com\\/report\\/v3?s=bEedVN1Nw6iyrHYXZ9VB2hHG6hvJeLpb7Sz4BNVwKer6MiTaxoyh7aylVh8K%2B%2BI2DkqziNH8LiOfTwTfS4bEYOYXiMAOw3aRYnSfpt23oS5ZdJ5GZrZ%2BU0v5UQ%3D%3D"}],"group":"cf-nel","max_age":604800}', 'NEL': '{"success_fraction":0,"report_to":"cf-nel","max_age":604800}', 'Vary': 'Accept-Encoding', 'Server': 'cloudflare', 'CF-RAY': '730cef5aac3a810e-ORD', 'Content-Encoding': 'br'}

Because the .headers attribute returns a dictionary, we can access items in the dictionary. Furthermore, what’s special about this dictionary is that it’s case-insensitive.

This means that we can query for items in a way that’s different from normal dictionaries. Let’s see how we can search for the 'Content-Type' key while ignoring case:

# Keys in the Response Headers are Case-Insensitive
import requests
resp = requests.get('https://reqres.in/api/users')
headers = resp.headers
print(headers['content-type'])

# Returns: application/json; charset=utf-8

Conclusion

In this tutorial, you learned how to use and understand the Response object that gets returned from any request made via the Python requests library. Understanding the Reponse object allows you to better understand the request that you made. You first learned how to understand the status of a request that was made. Then, you learned how to access the content of the response and how to serialize the response into a Python dictionary. Finally, you learned how to access the headers of the response.

Additional Resources

To learn more about related topics, check out the tutorials below:

• Python requests: POST Request Explained
• Python requests: GET Request Explained
• How to Install requests Package in Python – Windows, macOS, and Linux