Gọi Web API bằng requests: GET, POST, JSON, timeout, thử lại
Lấy dữ liệu từ Web API bằng requests: GET, POST, params, header, JSON, timeout, raise_for_status, Session, thử lại và giữ API key.
Học xong bài này, bạn sẽ
- Hiểu request, response, mã trạng thái, JSON
- Gửi GET, POST có tham số, header, timeout
- Xử lý lỗi mạng, thử lại và giữ bí mật API key
Nên học trước: Công cụ dòng lệnh với argparse và Typer
Nội dung bài viết
Tỷ giá, thời tiết, đơn hàng trên sàn thương mại điện tử, tin nhắn Telegram, dữ liệu từ hệ thống nội bộ của công ty: gần như mọi dữ liệu ngày nay đều lấy được qua Web API. Gọi API là kỹ năng hằng ngày của Python Developer, dù bạn làm tự động hóa hay backend. Bài này dùng thư viện requests, cách gọi HTTP phổ biến nhất trong Python, với các API công khai miễn phí không cần đăng ký.
1. Request và response
Chương trình của bạn gửi một request (yêu cầu) tới máy chủ gồm: phương thức (GET để lấy dữ liệu, POST để gửi dữ liệu...), URL, header và có thể có body. Máy chủ trả về response: mã trạng thái, header và body, thường là JSON. Chặng 9 sẽ đi sâu vào HTTP khi bạn tự viết API; ở đây chỉ cần biết các mã trạng thái chính:
| Mã | Ý nghĩa |
|---|---|
| 200, 201 | Thành công, đã tạo mới |
| 400, 422 | Request sai (thiếu tham số, dữ liệu không hợp lệ) |
| 401, 403 | Chưa đăng nhập, không có quyền |
| 404 | Không tìm thấy |
| 429 | Gọi quá nhiều, bị giới hạn tần suất |
| 500, 502, 503 | Lỗi phía máy chủ |
2. GET đầu tiên
Cài: uv add requests. Lấy dự báo nhiệt độ Hà Nội từ Open-Meteo (miễn phí cho mục đích phi thương mại, không cần key):
import requests
URL = "https://api.open-meteo.com/v1/forecast"
tham_so = {
"latitude": 21.03,
"longitude": 105.85,
"daily": "temperature_2m_max,temperature_2m_min",
"timezone": "Asia/Ho_Chi_Minh",
"forecast_days": 3,
}
r = requests.get(URL, params=tham_so, timeout=10) # kết quả thay đổi theo ngày
print(r.status_code, r.headers["Content-Type"])
du_lieu = r.json() # JSON → dict
ngay = du_lieu["daily"]
for d, cao, thap in zip(ngay["time"], ngay["temperature_2m_max"], ngay["temperature_2m_min"]):
print(f"{d}: {thap:.0f}–{cao:.0f}°C")
200 application/json; charset=utf-8
2026-10-29: 24–31°C
2026-10-30: 24–30°C
2026-10-31: 25–30°C
params=nhận dict và tự ghép thành chuỗi truy vấn?latitude=21.03&..., tự mã hóa ký tự đặc biệt. Đừng tự nối chuỗi URL.r.json()chuyển body JSON thành dict, list.r.textlà body dạng chuỗi.timeout=10là bắt buộc. Mặc định requests chờ vô hạn; máy chủ treo là chương trình của bạn treo theo.
Mẹo khi làm việc với API lạ: in du_lieu ra (hoặc mở URL trong trình duyệt) để xem cấu trúc JSON trước, rồi mới viết code lấy trường cần dùng.
3. Kiểm tra lỗi
import requests
r = requests.get("https://api.open-meteo.com/v1/forecast", params={"latitude": 999, "longitude": 105.85}, timeout=10)
print(r.status_code, r.json())
try:
r.raise_for_status() # ném HTTPError nếu mã 4xx, 5xx
except requests.HTTPError as loi:
print("Lỗi:", loi)
400 {'error': True, 'reason': 'Latitude must be in range of -90 to 90°. Given: 999.0.'}
Lỗi: 400 Client Error: Bad Request for url: https://api.open-meteo.com/v1/forecast?latitude=999&longitude=105.85
requests không tự ném lỗi khi máy chủ trả 4xx, 5xx: r.json() vẫn chạy và bạn có thể vô tình xử lý một thông báo lỗi như dữ liệu thật. Luôn gọi r.raise_for_status() (hoặc kiểm tra r.ok) trước khi dùng dữ liệu. Nhiều API giải thích lỗi trong body như ví dụ trên: hãy ghi nó vào log.
Ngoài lỗi HTTP còn có lỗi mạng: mất kết nối (requests.ConnectionError), hết thời gian chờ (requests.Timeout). Mọi lỗi của requests đều kế thừa requests.RequestException.
4. POST, header và JSON body
httpbin.org là dịch vụ trả lại đúng những gì bạn gửi, tiện để thử:
import requests
don_hang = {"khach": "An", "mat_hang": [{"ma": "SP1", "so_luong": 2}]}
r = requests.post(
"https://httpbin.org/post",
json=don_hang, # tự chuyển dict → JSON, đặt Content-Type
headers={"User-Agent": "hoc-python/1.0", "X-Ma-Yeu-Cau": "abc123"},
timeout=10,
)
r.raise_for_status()
nhan = r.json()
print(nhan["json"] == don_hang, nhan["headers"]["Content-Type"], nhan["headers"]["X-Ma-Yeu-Cau"])
True application/json abc123
json= dùng khi API nhận JSON (đa số API hiện đại); data= dùng cho form truyền thống. Header là cặp khóa – giá trị đi kèm request: loại nội dung, ngôn ngữ, và quan trọng nhất là thông tin xác thực.
5. API key và bí mật
Đa số API thật yêu cầu key, thường gửi qua header:
# (minh họa) đọc key từ biến môi trường, không viết thẳng vào code
import os
import requests
api_key = os.environ["TEN_DICH_VU_API_KEY"] # thiếu thì KeyError ngay: dễ phát hiện
r = requests.get("https://api.vi-du.vn/v1/don-hang",
headers={"Authorization": f"Bearer {api_key}"}, timeout=10)
Đặt key trong file .env (đã có trong .gitignore) và nạp vào biến môi trường, hoặc dùng thư viện python-dotenv. Không bao giờ viết key trong code, không in key ra log.
6. Session, thử lại và giới hạn tần suất
import requests
from requests.adapters import HTTPAdapter
from urllib3.util.retry import Retry
def tao_session() -> requests.Session:
s = requests.Session()
thu_lai = Retry(
total=3, # tối đa 3 lần thử lại
backoff_factor=0.5, # chờ tăng dần giữa các lần
status_forcelist=[429, 500, 502, 503, 504],
allowed_methods=["GET"], # chỉ tự thử lại request an toàn
)
s.mount("https://", HTTPAdapter(max_retries=thu_lai))
s.headers["User-Agent"] = "hoc-python/1.0"
return s
with tao_session() as s: # kết quả thay đổi theo ngày
for tp, (lat, lon) in {"Hà Nội": (21.03, 105.85), "TP.HCM": (10.82, 106.63)}.items():
r = s.get("https://api.open-meteo.com/v1/forecast",
params={"latitude": lat, "longitude": lon, "current": "temperature_2m"}, timeout=10)
r.raise_for_status()
print(tp, r.json()["current"]["temperature_2m"], "°C")
Hà Nội 27.4 °C
TP.HCM 29.8 °C
- Session giữ kết nối TCP để dùng lại giữa các request (nhanh hơn nhiều khi gọi liên tục tới cùng máy chủ), và giữ header, cookie chung.
- Retry tự thử lại khi gặp lỗi tạm thời, chờ tăng dần (0,5 s, 1 s, 2 s...) để không dội thêm tải vào máy chủ đang quá tải. Chỉ tự thử lại
GET;POSTtạo đơn hàng mà thử lại có thể tạo đơn trùng. - Tôn trọng giới hạn tần suất của API (thường ghi trong tài liệu): thêm
time.sleep()giữa các lần gọi khi duyệt nhiều trang.
httpx có giao diện gần như giống hệt requests (httpx.get(url, params=..., timeout=...)) và hỗ trợ thêm gọi bất đồng bộ với async/await, HTTP/2. Bạn sẽ dùng httpx ở bài asyncio (chặng 10) và trong test FastAPI (chặng 9).Tóm tắt
requests.get(url, params=..., timeout=...),requests.post(url, json=..., headers=...).- Luôn có
timeout; luônraise_for_status()trước khi dùngr.json(). - Bắt
requests.RequestExceptioncho lỗi mạng; key đọc từ biến môi trường. Session+Retrycho gọi nhiều lần, thử lại lỗi tạm thời (chỉ với GET).
Bài tập
Bài 1. Dự báo 7 ngày
Gọi Open-Meteo lấy nhiệt độ cao nhất, thấp nhất và tổng lượng mưa (precipitation_sum) 7 ngày tới ở Hà Nội, in bảng ngày (dd/mm) – thấp – cao – mưa.
Xem đáp án
from datetime import date
import requests
r = requests.get(
"https://api.open-meteo.com/v1/forecast",
params={"latitude": 21.03, "longitude": 105.85, "timezone": "Asia/Ho_Chi_Minh",
"daily": "temperature_2m_max,temperature_2m_min,precipitation_sum", "forecast_days": 7},
timeout=10,
)
r.raise_for_status()
d = r.json()["daily"]
print(f"{'Ngày':<7}{'Thấp':>6}{'Cao':>6}{'Mưa':>8}")
for ngay, thap, cao, mua in zip(d["time"], d["temperature_2m_min"], d["temperature_2m_max"],
d["precipitation_sum"]):
print(f"{date.fromisoformat(ngay):%d/%m}{thap:>7.0f}{cao:>6.0f}{mua:>6.1f}mm") # kết quả thay đổi theo ngày
Ngày Thấp Cao Mưa
29/10 24 31 0.0mm
30/10 24 30 1.2mm
...
Bài 2. Hàm lấy JSON chịu lỗi
Viết lay_json(url, params=None, so_lan_thu=3): có timeout, thử lại khi lỗi mạng hoặc mã 5xx (chờ 1 s, 2 s...), không thử lại với 4xx, hết lượt thì ném lỗi cuối.
Xem đáp án
import time
import requests
def lay_json(url: str, params: dict | None = None, so_lan_thu: int = 3, cho: float = 1.0):
for lan in range(1, so_lan_thu + 1):
try:
r = requests.get(url, params=params, timeout=10)
if r.status_code < 500:
r.raise_for_status() # 4xx: lỗi của mình, ném ngay
return r.json()
loi = requests.HTTPError(f"{r.status_code} từ máy chủ")
except (requests.ConnectionError, requests.Timeout) as e:
loi = e
if lan == so_lan_thu:
raise loi
time.sleep(cho * 2 ** (lan - 1)) # 1 s, 2 s, 4 s...
print(lay_json("https://httpbin.org/json")["slideshow"]["title"])
try:
lay_json("https://httpbin.org/status/503", so_lan_thu=2, cho=0.1)
except requests.HTTPError as e:
print("Bỏ cuộc:", e)
Sample Slide Show
Bỏ cuộc: 503 từ máy chủ
Đây chính là decorator thu_lai ở chặng 5 được viết thẳng vào hàm. Trong dự án thật, dùng Session + Retry như mục 6 hoặc thư viện chuyên dụng như tenacity thay vì tự viết.
Nguồn tham khảo: Requests: Quickstart; Requests: Advanced Usage; Open-Meteo API docs; urllib3 Retry.
Bài tập thực hành
- Gọi API thời tiết Open-Meteo lấy nhiệt độ 7 ngày tới ở Hà Nội, in bảng ngày – cao nhất – thấp nhất.
- Viết hàm lay_json(url, so_lan_thu=3) có timeout, thử lại khi lỗi 5xx hoặc mất kết nối.
Làm xong bài tập mới chuyển sang bài tiếp theo: tự viết code là cách duy nhất để nhớ lâu.


