Your programs have read from files. Now they'll read from the internet.

An API (Application Programming Interface) is a service that returns data instead of a web page — usually JSON, which you already know from Module 6.

requests is the standard library for this. It's third-party, so you install it first (lesson 7.4):

pip install requests

About the exercises in this module: these lessons run Python inside your browser, which can't open network connections. So the code samples show real requests usage — copy them to your own machine and they'll work — while the runnable exercises use a small FakeResponse stand-in that behaves like a real response object. Everything you learn about parsing, status codes, and error handling transfers exactly; only the network hop is simulated.

A GET request

GET means "give me data." It's what your browser does when you visit a page.

import requests

response = requests.get("https://api.github.com/users/python")

print(response.status_code)
print(response.json()["name"])

requests.get(url) sends the request and returns a Response object holding everything the server sent back.

The Response object

| Attribute | Contains | | --- | --- | | .status_code | the HTTP code, e.g. 200 | | .text | the body as a string | | .json() | the body parsed from JSON into Python | | .headers | response headers, as a dictionary | | .ok | True when the status is below 400 | | .url | the final URL, after any redirects |

Status codes

The number tells you what happened, and the first digit tells you the category:

| Code | Meaning | | --- | --- | | 200 OK | success | | 201 Created | something was created (see lesson 8.4) | | 301 / 302 | redirect — requests follows these automatically | | 400 Bad Request | your request was malformed | | 401 Unauthorized | missing or bad credentials | | 403 Forbidden | authenticated, but not allowed | | 404 Not Found | no such resource | | 429 Too Many Requests | you're being rate-limited | | 500 / 503 | the server broke, not you |

Roughly: 2xx worked, 4xx is your fault, 5xx is theirs.

A failed request does not raise an exception. requests.get() returns normally with a 404; if you don't check the status you'll happily parse an error page as if it were data. Always check:

import requests

response = requests.get("https://api.github.com/users/python")

if response.status_code == 200:
    print(response.json()["name"])
else:
    print(f"Request failed: {response.status_code}")

response.ok is a shorthand for "status is under 400", and lesson 8.5 covers raise_for_status().

Try it yourself

Here's the FakeResponse stand-in. Note how the code that uses it is identical to what you'd write against the real thing.

Checkpoint

• An API returns data (usually JSON) rather than a web page.
• pip install requests, then requests.get(url) returns a Response.
• Use .status_code, .text, .json(), and .ok.
• 2xx succeeded, 4xx is your mistake, 5xx is the server's.
• A 404 does not raise — always check the status before using the body.