Introduction
If you've done any development work with APIs chances are that the output you received was a JSON file. JSON stands for JavaScript Object Notation, and is an open standard file format that uses human-readable text to store and transmit data objects.
It is a language independent data format that was originally derived from JavaScript but is readily parsed by most modern programming languages (Python included). The data inside a JSON file are represented by key:value pairs which aligns itself nicely to the Python dictionary object. JSON files use the extension .json.
In this tutorial we are going to look more closely at how to parse data from a JSON file using the json module and work with four methods to read from and write to JSON.
The JSON module ships with a clean Python install and is accessed in a script by an import.
import json
JSON Format Syntax
The JSON format is similar to that of a Javascript object or a Python dictionary where the data is represented by key:value pairs. An example showing the information of a student at a school is shown below.
{
"Name": "Susan Studywell",
"Contact Number": 1165988741,
"Email": "susan.studywell@school.com",
"Subjects": [
"Math",
"Science",
"Biology",
"Geography",
"Art",
"Computers"
],
"Detention": null
}
JSON files are quite particular as to what data types are acceptable and so you should always follow the rules set out below when creating your own.
- JSON files accept data as either an object or an array.
- Curly braces
{}denote an object. - Square brackets
[]denote an array.
- Curly braces
- All keys and strings must be written with double quotation marks
"". Single quotation marks are not allowed. - The key must be unique and written in double quotation marks e.g.:
"mykey". - Every key:value pair is terminated with a comma, except the last item which has no comma.
JSON to Python Conversion
JSON data types are converted into the following Python equivalents when using the json module.
| JSON | Python |
|---|---|
| object | dict |
| array | list |
| string | str |
| integer | int |
| real number | float |
| true | True |
| false | False |
| null | None |
Reading JSON
The json module provides two methods for reading JSON.
- Use
json.load(filepath)to load an external JSON file. - Use
json.loads(string)to load JSON from a string.
Let's go over both methods with a couple of examples.
Load an External File with json.load()
The json.load() method takes a file path as a required attribute and returns a Python dictionary where the keys in the JSON file correspond to the keys in the dictionary, and values in the JSON file are converted to values in the dictionary according to the conversion table above.
We'll use an example from a set of general aviation aircraft where the JSON key is the aircraft model, and a few key attributes of the aircraft are given as a nested object (to be returned as a dictionary in Python).
{
"Cessna 172S": {
"seats":4,
"engines":1,
"wingspan":10.9,
"wingarea":16.2,
"Vcruise":122,
"MTOW":1157
},
"Cessna 210": {
"seats":6,
"engines":1,
"wingspan":11.2,
"wingarea":16.2,
"Vcruise":193,
"MTOW":1814
},
"Baron 55": {
"seats":6,
"engines":2,
"wingspan":11.5,
"wingarea":18.5,
"Vcruise":180,
"MTOW":2213
},
"Kingair B200": {
"seats":10,
"engines":2,
"wingspan":16.6,
"wingarea":28.2,
"Vcruise":289,
"MTOW":5670
}
}
Note the absense of trailing commas at the end of each final value in the JSON object.
To open and close the file we make use of the with open() syntax. Take a look at our tutorial on reading and writes text files if you need a quick refresher of how it works.
import json
json_file = 'ga-aircraft.json'
with open(json_file) as input_file:
aircraft_dict = json.load(input_file)
aircraft_dict is a Python dictionary which is created from the JSON file and can be accessed and used the same way as any Python dictionary.
{
'Cessna 172S': {
'seats': 4,
'engines': 1,
'wingspan': 10.9,
'wingarea': 16.2,
'Vcruise': 122,
'MTOW': 1157
},
'Cessna 210': {
'seats': 6,
'engines': 1,
'wingspan': 11.2,
'wingarea': 16.2,
'Vcruise': 193,
'MTOW': 1814
},
'Baron 55': {
'seats': 6,
'engines': 2,
'wingspan': 11.5,
'wingarea': 18.5,
'Vcruise': 180,
'MTOW': 2213
},
'Kingair B200': {
'seats': 10,
'engines': 2,
'wingspan': 16.6,
'wingarea': 28.2,
'Vcruise': 289,
'MTOW': 5670
}
}
# Number of seats in the Cessna 210
>>> print(aircraft_dict['Cessna 210']['seats'])
6
Read JSON from a String using json.loads()
A string of JSON can be read into a Python dictionary using the json.loads(str) method. The 's' in .loads refers to the fact that the dictionary is being created from a string. In the following example the captured information on two students is converted from a string of JSON to a Python dictionary using the json.loads() method.
classinfo = """{
"001":{
"Name": "Susan Studywell",
"Contact Number": 1165988741,
"Email": "susan.studywell@school.com",
"Subjects":["Math", "Science", "Biology","Geography","Art", "Computers"]
},
"002":{
"Name": "Steve Slacker",
"Contact Number": 1255699874,
"Email": "steve.slacker@school.com",
"Subjects":["English", "Art", "Computers","Math"]
}
}"""
# parse data:
import json
student_info = json.loads(classinfo) # returns a Python dictionary
The values in the newly created dictionary can be accessed to extract the required information.
for student in student_info:
print(f"{student_info[student]['Name']} is taking
{len(student_info[student]['Subjects'])}
subjects this year.")
Output
'Susan Studywell is taking 6 subjects this year.'
'Steve Slacker is taking 4 subjects this year.'
Writing JSON
The methods for writing JSON are similar to the reading methods in the sense that two methods are available, one to write to a file and one to write to a string.
- Use
json.dump(dictionary,filepath,*,indent=None)to write out to an external JSON file. - Use
json.dumps(dictionary,*,indent=None)to write JSON to a string.
Write Python Dictionary to a JSON File
To write an external JSON file from a Python dictionary use json.dump(). In the example below we use the dictionary student_info created in the previous section from the classinfo string.
import json
outputfile = 'Student_DataDump.json'
with open(outputfile, "w" ) as f:
json.dump(student_info , f, indent=4)
Specifying the indent attribute adds indentation to the resulting file which makes the JSON output easier to read. The output is still completely valid if the indent is left at the default None.
The resulting JSON file:
{
"001": {
"Name": "Susan Studywell",
"Number": 1165988741,
"Email": "susan.studywell@school.com",
"Subjects": [
"Math",
"Science",
"Biology",
"Geography",
"Art",
"Computers"
]
},
"002": {
"Name": "Steve Slacker",
"Contact Number": 1255699874,
"Email": "steve.slacker@school.com",
"Subjects": [
"English",
"Art",
"Computers",
"Math"
]
}
}
Write a Dictionary to a JSON String
The final method we'll cover is json.dumps() where the 's' referrs to a string output. This method allows us to write a dictionary out to a string of JSON.
Again we'll use the dictionary student_info created in the previous section, and write this out to a JSON string.
import json
outputstr = json.dumps(student_info)
print(outputstr)
print(f"The output is a {type(outputstr)}.")
The resulting Output:
'{"001": {"Name": "Susan Studywell", "Contact Number": 1165988741,
"Email": "susan.studywell@school.com",
"Subjects": ["Math", "Science", "Biology", "Geography", "Art", "Computers"]},
"002": {"Name": "Steve Slacker", "Contact Number": 1255699874,
"Email": "steve.slacker@school.com",
"Subjects": ["English", "Art", "Computers", "Math"]}}'
"The output is a <class 'str'>."
Wrapping Up
- There are four methods in the
jsonmodule that are used to read and write JSON. - Python converts a JSON object to a dictionary.
json.load(filepath)to load a JSON file into Python as a dictionary.json.loads(string)to load a string of JSON as a dictionary.json.dump(dict,outputfile)to convert a dictionary into a JSON file.json.dumps(dict)to convert a dictionary into a string of JSON.
