When a weather app asks a server for today's forecast, or a payment page talks to a bank's API, the data usually travels in one format: JSON. It's also used for config files, saving app data, and storing data in many databases.
Python has a built-in json module that converts Python objects to JSON text and back. In this chapter you'll learn how to use it and avoid the common traps.
What is JSON?
JSON (JavaScript Object Notation) is a lightweight, text-based format for storing and exchanging data. It is language-independent, so Python, Java, JavaScript and almost every other language can read and write it.
Here is a small JSON document:
{
"name": "Riya",
"age": 21,
"is_student": true,
"skills": ["Python", "SQL"],
"address": {"city": "Pune", "pin": "411001"},
"mentor": null
}It looks a lot like a Python dictionary, but the rules are stricter:
Strings and keys must use double quotes (
"name", not'name').Object keys must always be strings.
It uses
true,falseandnull(lowercase) instead ofTrue,FalseandNone.No trailing commas and no comments are allowed.
Python and JSON Types
The json module converts types like this:
Python | JSON |
|---|---|
| object |
| array |
| string |
| number |
|
|
|
|
When reading JSON back, objects become dict and arrays become list.
Python to JSON: json.dumps()
dumps() means "dump to string". It converts a Python object into a JSON-formatted string.
import json
student = {
"name": "Riya",
"age": 21,
"is_student": True,
"skills": ["Python", "SQL"],
"mentor": None,
}
text = json.dumps(student)
print(text)
print(type(text))Output:
{"name": "Riya", "age": 21, "is_student": true, "skills": ["Python", "SQL"], "mentor": null}
<class 'str'>Notice how True became true and None became null.
Pretty Printing
Use indent to make the output readable, and sort_keys to sort the keys alphabetically.
import json
student = {"name": "Riya", "age": 21, "skills": ["Python", "SQL"]}
print(json.dumps(student, indent=2, sort_keys=True))Output:
{
"age": 21,
"name": "Riya",
"skills": [
"Python",
"SQL"
]
}Non-English Characters
By default, dumps() escapes every non-ASCII character. Pass ensure_ascii=False to keep characters like ₹ or Hindi text as they are.
import json
data = {"city": "पुणे", "price": "₹499"}
print(json.dumps(data))
print(json.dumps(data, ensure_ascii=False))Output:
{"city": "\u092a\u0941\u0923\u0947", "price": "\u20b9499"}
{"city": "पुणे", "price": "₹499"}Both are valid JSON and mean the same thing; the second is just easier for humans to read.
JSON to Python: json.loads()
loads() means "load from string". It parses a JSON string and gives back Python objects.
import json
response = '{"id": 7, "title": "Learn JSON", "done": false, "tags": ["python", "api"]}'
task = json.loads(response)
print(type(task))
print(task["title"])
print(task["done"])
print(task["tags"][1])Output:
<class 'dict'>
Learn JSON
False
apiOnce loaded, it is a normal dictionary, so everything from the dictionaries chapter applies.
Working with JSON Files
For files, use the versions without the "s": json.dump() writes to a file and json.load() reads from a file. Open files with with and encoding="utf-8", as you learned in the file handling chapter.
import json
settings = {"theme": "dark", "font_size": 14, "languages": ["en", "hi"]}
with open("settings.json", "w", encoding="utf-8") as f:
json.dump(settings, f, indent=2)
with open("settings.json", "r", encoding="utf-8") as f:
loaded = json.load(f)
print(loaded)
print(loaded == settings)Output:
{'theme': 'dark', 'font_size': 14, 'languages': ['en', 'hi']}
TrueAn easy way to remember the four functions:
Function | Direction | Works with |
|---|---|---|
| Python to JSON | String |
| JSON to Python | String |
| Python to JSON | File |
| JSON to Python | File |
The "s" stands for string.
Handling Invalid JSON
If the text is not valid JSON, loads() raises json.JSONDecodeError (a subclass of ValueError). Always handle it when the data comes from a user or the internet.
import json
bad = "{'name': 'Riya'}" # single quotes are not valid JSON
try:
data = json.loads(bad)
except json.JSONDecodeError as e:
print("Invalid JSON:", e)Output:
Invalid JSON: Expecting property name enclosed in double quotes: line 1 column 2 (char 1)The error even tells you the line and column where parsing failed.
Things That Change in a Round Trip
Converting to JSON and back does not always give you exactly what you started with.
import json
original = {1: "one", "point": (3, 4)}
back = json.loads(json.dumps(original))
print(back)Output:
{'1': 'one', 'point': [3, 4]}Integer keys become strings, because JSON keys must be strings.
Tuples become lists, because JSON only has arrays.
Types JSON Cannot Store
Sets, dates, and your own class objects are not supported directly.
import json
try:
json.dumps({"tags": {"a", "b"}})
except TypeError as e:
print("Error:", e)Output:
Error: Object of type set is not JSON serializableYou can pass a default function that converts unsupported objects into something JSON understands:
import json
class Student:
def __init__(self, name, marks):
self.name = name
self.marks = marks
def to_json(obj):
if isinstance(obj, set):
return sorted(obj)
if isinstance(obj, Student):
return {"name": obj.name, "marks": obj.marks}
raise TypeError(f"Cannot serialize {type(obj).__name__}")
data = {"topper": Student("Aman", 95), "subjects": {"Maths", "CS"}}
print(json.dumps(data, default=to_json))Output:
{"topper": {"name": "Aman", "marks": 95}, "subjects": ["CS", "Maths"]}json calls default only for objects it doesn't know how to convert.
Practical Example: Reading an API Response
Real API responses are often nested. Use .get() to avoid a KeyError when a field may be missing.
import json
response = """
{
"status": "ok",
"results": [
{"name": "Asha", "score": 88, "city": "Delhi"},
{"name": "Vikram", "score": 92},
{"name": "Neha", "score": 79, "city": "Chennai"}
]
}
"""
data = json.loads(response)
for user in data["results"]:
city = user.get("city", "Unknown")
print(f"{user['name']:<8} {user['score']:>3} {city}")
best = max(data["results"], key=lambda u: u["score"])
print("Top scorer:", best["name"])Output:
Asha 88 Delhi
Vikram 92 Unknown
Neha 79 Chennai
Top scorer: VikramCommon Mistakes
Mixing up
loadandloads-json.load()needs a file object;json.loads()needs a string.Writing JSON by hand with single quotes -
str(my_dict)is not JSON. Always usejson.dumps().Expecting
True/Nonein the JSON text - JSON usestrueandnull.Forgetting integer keys turn into strings - after a round trip,
data[1]fails butdata["1"]works.Not handling
JSONDecodeErrorfor data from outside your program.
Interview Tips
Difference between
dumpanddumps?dumpsreturns a string;dumpwrites to a file. Same forload/loads.JSON vs Python dict? A dict is an in-memory Python object; JSON is text. JSON needs double quotes, string keys, and uses
true/false/null.How do you serialize a custom object? Pass a
defaultfunction (or subclassjson.JSONEncoder), or convert the object to a dict first.Practice: save a list of to-do items to
todo.jsonand load it back; count how many users in a JSON response live in each city.
Summary
JSON is a text format for exchanging data, used by almost every web API.
dumps/loadswork with strings;dump/loadwork with files.Use
indentfor readable output andensure_ascii=Falseto keep non-English characters.Tuples become lists, integer keys become strings, and sets/custom objects need a
defaultfunction.Catch
json.JSONDecodeErrorwhen parsing untrusted text.
dumps turns Python into JSON text; loads turns JSON text back into Python. The "s" is for string.