Chapter 52 of 54

Working with JSON in Python

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, false and null (lowercase) instead of True, False and None.

  • No trailing commas and no comments are allowed.


Python and JSON Types

The json module converts types like this:

Python

JSON

dict

object { }

list, tuple

array [ ]

str

string

int, float

number

True / False

true / false

None

null

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
api

Once 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']}
True

An easy way to remember the four functions:

Function

Direction

Works with

json.dumps(obj)

Python to JSON

String

json.loads(text)

JSON to Python

String

json.dump(obj, file)

Python to JSON

File

json.load(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 serializable

You 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: Vikram

Common Mistakes

  • Mixing up load and loads - 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 use json.dumps().

  • Expecting True/None in the JSON text - JSON uses true and null.

  • Forgetting integer keys turn into strings - after a round trip, data[1] fails but data["1"] works.

  • Not handling JSONDecodeError for data from outside your program.


Interview Tips

  • Difference between dump and dumps? dumps returns a string; dump writes to a file. Same for load/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 default function (or subclass json.JSONEncoder), or convert the object to a dict first.

  • Practice: save a list of to-do items to todo.json and 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/loads work with strings; dump/load work with files.

  • Use indent for readable output and ensure_ascii=False to keep non-English characters.

  • Tuples become lists, integer keys become strings, and sets/custom objects need a default function.

  • Catch json.JSONDecodeError when parsing untrusted text.

dumps turns Python into JSON text; loads turns JSON text back into Python. The "s" is for string.