Consume API data
Parse a JSON API response into dictionaries, lists, or scalar Python values.
Requests · Function
json
Response.json() decodes a response body as JSON and returns the corresponding Python object, such as a dictionary or list. It raises an exception when decoding fails.
How it works
Call this method on a Response to decode its body as JSON. The result is whichever Python value the JSON represents, such as a dictionary or list; decoding failures raise an exception.
Syntax
Response.json(**kwargs) → AnyParameters
| Name | Type | Description |
|---|---|---|
**kwargs | Any | Optional keyword arguments accepted by the JSON decoder. |
Returns
Any
Key points
- Response.json() transforms the response body into a native Python value.
- Use json() with parentheses; accessing json without calling it is not the documented operation.
- The JSON decoder belongs to the Response API exposed by Requests.
Common mistakes
- A successful HTTP response does not guarantee valid JSON; handle decoding failures when the body may be empty or malformed.
Example: Decode a JSON response
import requests
response = requests.get("https://api.github.com/events")
response.raise_for_status()
events = response.json()
print(type(events).__name__)Fetches JSON from an endpoint, verifies the HTTP status, and converts the response body into a Python object.
When to use it
Validate then parse
Decode a response after checking its HTTP status.
Detect decoding failures
Handle malformed or non-JSON bodies from an endpoint.
Interview questions
QWhat does Response.json() do?
Response.json() parses the response body and returns the corresponding Python object. The returned value can be a dictionary, list, or another JSON-supported value.
Follow-up: What happens when the body is not valid JSON? The call raises an exception rather than returning a partially decoded value.
QHow do you use the JSON decoder on a response?
It is a method, so it must be invoked with parentheses. The documentation specifically distinguishes the callable form from the older property-style form.
Follow-up: How would you avoid treating an error page as JSON? Check the HTTP status first, then call json() and handle decoding errors.
QDoes calling json() validate the HTTP status?
The method decodes the response body; it does not itself establish that the HTTP request succeeded. Status handling should therefore be performed separately when success is required.
Follow-up: What should a client do before decoding an API response? Raise for an unsuccessful status or otherwise inspect the status code, then decode the body.
Related
requests.getrequests.postrequests.Responserequests.exceptions.JSONDecodeError