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
- 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 requestsIn this course's browser examples, requests is already set up for you.
Sending a GET request
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
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 method | What it gives you |
|---|---|
response.status_code | the status code as a number, such as 200 |
response.reason | the reason phrase, such as "OK" (it can be empty, for example when the code runs in a browser) |
response.ok | True if the status code is below 400 |
response.headers | the response headers, in a dictionary that ignores case |
response.text | the body as text |
response.json() | the body parsed from JSON into Python data |
response.url | the final URL, including the encoded query string |
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:
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
Summarise an API response the way you would after a real requests.get().
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
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()anddelete()send each kind of request.- Use
params=for query parameters,json=for a JSON body,headers=for headers and alwaystimeout=. - The Response object gives you
status_code,ok,headers,text,json()andurl. - 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.