Velamuvi AIAcademy

Lesson 9 of 12 · Calling APIs From Python

The requests Library

Learn the Python requests library step by step: installing it, GET and POST requests, params, json, headers and timeout, and everything inside the Response object.

  • 8 min read
  • Beginner
  • Reviewed
In this lesson you will learn
  • What the requests library is and how to install it
  • How to send GET and POST requests with params, json, headers and timeout
  • What is inside a Response object
  • How to reuse settings across requests with a session

Why a library?

In the HTTP lesson you took a raw response apart by hand. Doing that for every request would be slow and easy to get wrong. A library does it for you.

It is not part of the standard library, so on your own computer you install it once, in a terminal:

pip install requests

In this course's browser examples, requests is already set up for you.

Sending a GET request

Try it yourselfPython
import requests

response = requests.get(
    "https://jsonplaceholder.typicode.com/posts",
    params={"userId": 1},
    timeout=10,
)

posts = response.json()
print("Status:", response.status_code)
print("Posts by user 1:", len(posts))
print("First title:", posts[0]["title"])

requests.get() takes the URL first, then optional keyword arguments. These are the four you will use most:

Sending a POST request

Try it yourselfPython
import requests

new_post = {"title": "Learning requests", "body": "It makes APIs easy.", "userId": 1}

response = requests.post(
    "https://jsonplaceholder.typicode.com/posts",
    json=new_post,
    headers={"Accept": "application/json"},
    timeout=10,
)

print(response.status_code)
print(response.json())

Status 201 (Created) and an id in the body mean the server accepted the new post.

The Response object

Attribute or methodWhat it gives you
response.status_codethe status code as a number, such as 200
response.reasonthe reason phrase, such as "OK" (it can be empty, for example when the code runs in a browser)
response.okTrue if the status code is below 400
response.headersthe response headers, in a dictionary that ignores case
response.textthe body as text
response.json()the body parsed from JSON into Python data
response.urlthe final URL, including the encoded query string
Try it yourselfPython
import requests

response = requests.get("https://jsonplaceholder.typicode.com/users/2", timeout=10)

print("status_code:", response.status_code)
print("ok:         ", response.ok)
print("url:        ", response.url)
print("headers:    ", response.headers["Content-Type"])
print("text:       ", response.text[:60].replace("\n", " "), "...")
print("json():     ", response.json()["name"])

Note that json is a method, so it needs brackets: response.json(). The others are plain attributes.

Reusing settings with a session

import requests

session = requests.Session()
session.headers.update({"Authorization": "Bearer YOUR_KEY", "Accept": "application/json"})

first = session.get("https://api.example.com/v1/items", timeout=10)
second = session.get("https://api.example.com/v1/items/42", timeout=10)

Both requests automatically carry the same headers. This is a pattern only, since api.example.com is not a real API, so it is not runnable here.

Working with a saved response

Real responses change all the time, so here is practice with a saved one. This is the kind of text response.text gives you:

Try it yourselfPython
import json

text = """[
  {"userId": 1, "id": 1, "title": "Getting started with APIs", "completed": true},
  {"userId": 1, "id": 2, "title": "Read the documentation", "completed": false},
  {"userId": 2, "id": 3, "title": "Write the first request", "completed": true}
]"""

todos = json.loads(text)        # the same thing response.json() does

done = 0
for todo in todos:
    mark = "x" if todo["completed"] else " "
    print(f"[{mark}] {todo['title']}")
    if todo["completed"]:
        done += 1

print(f"{done} of {len(todos)} done")

Common mistakes

Practice exercise

Summarise an API response the way you would after a real requests.get().

Your solutionPython
import json

# This is the text of a response from a posts API.
text = """[
  {"userId": 1, "id": 1, "title": "Hello"},
  {"userId": 2, "id": 2, "title": "APIs"},
  {"userId": 1, "id": 3, "title": "JSON"},
  {"userId": 3, "id": 4, "title": "Headers"},
  {"userId": 1, "id": 5, "title": "Requests"}
]"""

# 1. Parse the text, as response.json() would.
# 2. Count how many posts each userId has, using a dictionary.
# 3. Print one line per user, in the order they first appear.

# Output must be exactly:
# User 1: 3 posts
# User 2: 1 posts
# User 3: 1 posts
Knowledge check

Which argument should you use to send a dictionary as a JSON body with requests.post()?

Summary

  • requests is Python's most popular library for calling APIs. Install it with pip.
  • requests.get(), post(), put(), patch() and delete() send each kind of request.
  • Use params= for query parameters, json= for a JSON body, headers= for headers and always timeout=.
  • The Response object gives you status_code, ok, headers, text, json() and url.
  • A Session reuses headers and connections across many requests.

Next: what to do when a request goes wrong.

Finished reading? Tick it off to track your progress.