Velamuvi AIAcademy

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.

  • 8 min read
  • Intermediate
  • Reviewed
In this lesson you will learn
  • 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".

Try it yourselfPython
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.

Try it yourselfPython
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.

Try it yourselfPython
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.

Try it yourselfPython
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.

Try it yourselfPython
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.

Try it yourselfPython
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.

Try it yourselfPython
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.

Try it yourselfPython
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

Practice exercise

Read a nested JSON string and pull out the values you need.

Your solutionPython
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
Knowledge check

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, False and None.
  • json.dumps() and json.loads() convert to and from strings. json.dump() and json.load() work with files.
  • indent=2 makes JSON readable, and ensure_ascii=False keeps non-English characters as they are.
  • Read nested data step by step, use .get() for keys that might be missing, and catch json.JSONDecodeError.

Next: CSV files, the most common format for tables of data.

Finished reading? Tick it off to track your progress.