Lesson 10 of 16 · Working With Text and Data
Working With JSON
Learn to read and write JSON in Python: convert between JSON text and dictionaries, pretty-print, save to files, navigate nested API responses and handle bad JSON.
- 9 min read
- Intermediate
- Reviewed
- What JSON is and why it is everywhere
- How to turn Python data into JSON text and back
- How to save JSON to a file and load it again
- How to read nested data from an API response safely
What is JSON?
JSON (JavaScript Object Notation) is a text format for structured data. It is how websites, apps and APIs send data to each other. It looks almost exactly like Python dictionaries and lists:
{
"name": "Ada",
"age": 36,
"skills": ["Python", "SQL"],
"remote": true,
"manager": null
}There are a few small differences from Python. JSON uses true, false and null where Python uses True, False and None, and JSON text always uses double quotes.
Python's built-in json module converts between the two.
From Python to JSON text: dumps
json.dumps() turns Python data into a JSON string. The s at the end stands for "string".
import json
person = {"name": "Ada", "age": 36, "skills": ["Python", "SQL"], "remote": True, "manager": None}
text = json.dumps(person)
print(text)
print(type(text))Notice how True became true and None became null.
Making it readable
Add indent to pretty-print, and sort_keys=True to order the keys alphabetically.
import json
settings = {"model": "small", "temperature": 0.7, "stop": ["\n\n"], "stream": False}
print(json.dumps(settings, indent=2, sort_keys=True))If your data contains accented or non-English characters, add ensure_ascii=False to keep them readable instead of turning them into codes.
import json
greeting = {"en": "Hello", "fr": "Bonjour, ça va ?", "es": "¿Qué tal?"}
print(json.dumps(greeting))
print(json.dumps(greeting, ensure_ascii=False))From JSON text to Python: loads
json.loads() does the reverse. It reads a JSON string and gives you normal Python dictionaries and lists.
import json
response_text = '{"id": 42, "status": "done", "scores": [0.91, 0.87], "error": null}'
data = json.loads(response_text)
print(data["status"])
print(data["scores"][0])
print(data["error"] is None)Saving to and loading from a file
Without the s, json.dump() writes straight into a file and json.load() reads from one.
import json
progress = {"course": "python-intermediate", "completed": ["list-comprehensions"], "streak": 3}
with open("progress.json", "w", encoding="utf-8") as file:
json.dump(progress, file, indent=2)
with open("progress.json", encoding="utf-8") as file:
loaded = json.load(file)
print(loaded)
print(loaded == progress)An easy way to remember: dumps and loads work with strings, dump and load work with files.
Reading nested data
Real API responses are nested: dictionaries inside lists inside dictionaries. Read them one step at a time.
import json
response = json.loads("""
{
"model": "demo-1",
"choices": [
{"index": 0, "message": {"role": "assistant", "content": "Paris is the capital of France."}}
],
"usage": {"input_tokens": 12, "output_tokens": 9}
}
""")
answer = response["choices"][0]["message"]["content"]
total_tokens = response["usage"]["input_tokens"] + response["usage"]["output_tokens"]
print(answer)
print(total_tokens)Work out the path by reading the structure from the outside in: the choices list, its first item, that item's message, and its content.
When a key might be missing, use .get() with a default instead of square brackets.
response = {"usage": {"input_tokens": 12}}
print(response.get("usage", {}).get("output_tokens", 0))
print(response.get("warnings", []))Handling bad JSON
If the text is not valid JSON, json.loads() raises a json.JSONDecodeError. Catch it when the text comes from outside your program.
import json
replies = ['{"ok": true}', "{'ok': true}", "not json at all"]
for reply in replies:
try:
print(json.loads(reply))
except json.JSONDecodeError as error:
print("Could not read:", reply, "|", error.msg)The second reply fails because JSON requires double quotes. That is a common surprise when people write JSON by hand.
Common mistakes
Read a nested JSON string and pull out the values you need.
import json
raw = '{"user": {"name": "Priya", "plan": "free"}, "courses": [{"title": "Python for Beginners", "done": true}, {"title": "SQL for Beginners", "done": false}]}'
# 1. Load the JSON text
# 2. Print the user's name
# 3. Print the titles of the finished courses only, one per line
# Output must be exactly:
# Priya
# Python for Beginners
Which function turns a Python dictionary into JSON text?
Summary
- JSON is the text format APIs use. It maps to Python dictionaries, lists, strings, numbers,
True,FalseandNone. json.dumps()andjson.loads()convert to and from strings.json.dump()andjson.load()work with files.indent=2makes JSON readable, andensure_ascii=Falsekeeps non-English characters as they are.- Read nested data step by step, use
.get()for keys that might be missing, and catchjson.JSONDecodeError.
Next: CSV files, the most common format for tables of data.
Finished reading? Tick it off to track your progress.