Build for free
Make Use of JSON With Python

Make Use of JSON With Python

• 10 min read
Jump to section
Author: Ben Lloyd Pearson
Ben Lloyd Pearson
Tags:
Featured articles
Nylas Ranks on the 2024 Deloitte Technology Fast 500™ for the Third Consecutive Year
• 5 min read
Read more
ExtractAI
Introducing Nylas ExtractAI: Sync, filter, and extract structured data from your user’s inbox
• 8 min read
Read more
API v3 Calendar API Scheduler
Introducing the new Nylas Scheduler: Experience the future of in-app scheduling
• 4 min read
Read more
Jump to section

Nearly every modern website and app is, at some level, driven by JavaScript Object Notation, otherwise known as JSON. When you build software in Python, you’ll find yourself interacting with APIs and data stores that often provide results in this format. In fact, the Nylas Communications Platform provides APIs that connect to every email, calendar, and contacts provider in the world. Our APIs return all data in JSON format, and make it easy for developers to quickly integrate communications and scheduling functionality into their app. 

In this post, we’ll look at what JSON is, how to consume it, and how to return your data in JSON format using Python.

What is JSON?

JavaScript Object Notation (JSON) is a lightweight data-interchange format that is designed to be easily consumable by both humans and computers. JSON is a data-interchange language that’s based on JavaScript, but it uses conventions that are similar to many programming languages like Python, C, Java, and of course JavaScript. It’s typically used to store information in databases and is the most common data type you’ll find when working with modern REST APIs.

All JSON data structures follow one of two main types:

  • Unordered name-value pairs: referred to as dictionaries, Hash tables, objects, or keyed lists, depending on the programming language.
  • Ordered list of values: referred to as arrays, lists, or vectors.

Unordered name value pairs are referred to as JSON objects. You might notice that they look very similar to Python dictionaries:

{ 
  “surname”: “Edison”,
  “given_name”: “Thomas”,
  "middle_name": "Alva",  
  “age”: 84
}

An ordered list of values can contain any number of JSON objects, and they look very similar to Python lists:

[
  { 
    “given_name”: “Katherine”,
    “surname”: “Johnson”,
    “age”: 101
  },
  {
    “given_name”: “Ada”, 
    “surname”: “Lovelace”,
    “age”: 37
  } 
]

Python’s json library has built in support for converting JSON components into native Python objects. For example, JSON objects are converted into dictionaries, arrays into lists or tuples, etc. The next table shows the conversion mapping between JSON and Python:

JSON Python
object dict
array list or tuple
string str
number int or float
true True
false False
null None

Parse and Return JSON

Python comes equipped with the JSON library, which makes it extremely easy to use JSON data. To us it, add ‘import json’ to the top of your script. The first thing you should familiarize yourself with are the two functions you’ll be using the most:

  • json.dumps(obj) – converts an object to a JSON formatted string using the conversion table above. You can also pass other parameters to format the resulting JSON data; more on these later.
  • json.loads(str) – converts a string containing JSON into a python object using the conversion table above.

Convert a Python Dictionary to JSON

The next example demonstrates how to create a dictionary in Python then convert it to JSON with the json.dumps(obj) function. Finally, it prints out the result to the console.

import json  
  
my_dictionary = {
    "name": "Alexander Graham Bell",
    "job_title": "CEO",
    "company_name": "Bell System",
    "age": 75,
    "emails": [{"email": "[email protected]", "type": "work"}],
    "my_neighbor": False
}
unformatted_json = json.dumps(my_dictionary)
print(unformatted_json)

Run this script, and you should get a result that looks like this:

{"name": "Alexander Graham Bell", "job_title": "CEO","company_name": "Bell System", "age": 75, "emails": [{"email": "[email protected]", "type": "work"}], "my_neighbor": False}

One of the primary value propositions for JSON is that it’s easy for both humans and computers to read, and the last example certainly isn’t very human-readable. The json.dumps() function supports arguments to adjust things like indentation, separators, and sorting to make it easier to read data that’s printed to the console:

formatted_json = json.dumps(
  pythonDict, 
  indent = 4, 
  separators = (“, ”, “ = “), 
  sort_keys = True
)
print(formatted_json)

This change will result in a print that is much easier to read:

{
    "age"= 75,
    "company_name" = "Bell System",
    "emails" = [
        {
        "email" = "[email protected]", 
        "type" = "work"
        }
    ],
    "job_title" = "CEO",
    "my_neighbor" = False,
    "name" = "Alexander Graham Bell"
}

Convert JSON to a Python Dictionary

It’s a good idea to convert JSON to a Python dictionary when you want to use the data in your code because this lets you access all of the supporting functions dictionary objects offer in Python. The next example uses json.loads() to convert the JSON from the examples above into a Python dictionary. It then uses a few of the built in functions of the dictionary object and prints the results to the console:

#convert JSON into a python dictionary
pythonDict2 = json.loads(unformattedJSON)

#print out the value for key "job_title"
print("Individual key: job_title , value: " + pythonDict2["job_title"] +"\n")

#print out all keys and values
print("All keys and values: \n")
for key,value in pythonDict2.items():
    print("key:", key,",", "value:", value)

When you run this code you will get this as a result:

Individual key: job_title , value: Chief Scientist

All keys and values:

key: name , value: Alexander Graham Bell
key: job_title , value: CEO
key: company_name , value: Bell System
key: age , value: 75
key: emails , value: [{'email': '[email protected]', 'type': 'work'}]
key: my_neighbor , value: False

Create JSON From Python Objects

Here are some examples of how to create JSON from Python dict, list, and str objects. In the next example, each of the my_data objects will convert cleanly to a json object.

# Dictionary
my_data = {“given_name”: “Thomas Edison”, “age”: 84}

# List
my_data = [
 {“name”: “Thomas Edison”, “age”: 84},
 {“name”: “Ada Lovelace”, “age”: 37},
]

# String
my_data = "{'name': 'Ada Lovelace', 'age': 37}"

my_json = json.dumps(my_data)
print(my_json)

Convert CSV File to JSON

A common task is to convert a comma separated values (csv) file into JSON. For the next example, we’ll assume that we have a Contacts.csv file saved locally that contains the following data:

name company_name age
Ada Lovelace Algo Prime 37
Thomas Alva Edison Bright Idea Technologies 84

The script needs to import the csv library to read data from the local file. The next example uses the header row of the csv as the keys and the entries in each column as the values:

import csv
import json

#path to csv
contactsFile = r'Contacts.csv'

#Create an empty dictionary to collect values
contacts = {}
with open(contactsFile, encoding='utf-8') as csvFile:
    csvContent = csv.DictReader(csvFile)
    for row in csvContent:
        # Use the row that starts with name as the list of keys
        key = rows["name"]
        # Assign the all of the values in the row to the appropriate key
        contacts[key] = row
print(json.dumps(contacts, indent = 4)

Serialize Python Classes to JSON

Python makes it very easy to encode any type of Python object to JSON by extending the JSONEncoder object and including a cls argument to the json.dumps() function that indicates how to encode the object into JSON. The next example demonstrates how to do this for a custom Contact class.

from json import JSONEncoder
  
class ContactEncoder(JSONEncoder):
    def default(self, obj):
        return obj.__dict__

class Contact:
    def __init__(self, name, company_name, age):
        self.name = name
        self.company_name = company_name
        self.age = age

contact = Contact('Ada Lovelace', 'Algo Prime', 37)
contact_json = json.dumps(contact, indent = 4, sort_keys = True, cls=ContactEncoder)
print(contact_json)

Parse JSON From a REST API

One of the most common places you’ll encounter JSON data is when working with REST APIs. For the next examples, we’ll use the requests library to get JSON data from the Open Notify API which reports data about things that are happening in space. The requests library comes equipped with many features, but we will only need the GET request and the .json() formatter for these examples.  If you want to take a deeper dive into Python requests, check out our article on how to use Python requests with REST APIs to learn more about other functions this library provides and how to handle common situations like API authentication and errors.

The first step is to import the requests library with import requests. Then, create a GET request to the API endpoint that you want to access, the API will provide a response object that includes the JSON data, among other things like the headers, status code, cookies, and more. We’re only interested in the JSON data, which can be returned with the .json() function.

import requests

url = "http://api.open-notify.org/astros.json"
response = requests.get(url)
json = response.json()
print(json.dumps(json, indent = 2,))

This script should print out JSON data about the astronauts who are currently in space. At the time of this article there are three people on a historic trip to the International Space Station (ISS):

{
  "number": 3,
  "message": "success",
  "people": [
    {
      "craft": "ISS",
      "name": "Chris Cassidy"
    }, 
    {
      "craft": "ISS",
      "name": "Anatoly Ivanishin"
    }, 
    {
      "craft": "ISS",
      "name": "Ivan Vagner"
    }
  ]
}

Modify JSON Data

If you want to add additional data to a JSON object in Python, you should convert it to a dictionary first. Let’s do this with the JSON data we got from the Open Notify API in the previous example, but instead of printing the data to the console, let’s convert it to a Python dictionary so we can modify the contents of it.

import requests
import json

url = "http://api.open-notify.org/astros.json"

# Get the JSON response and store it as a Python dict
my_dictionary = requests.get(url).json()

# Create a new astronaut to add to the list
astronaut = {
  "name:": "Neil Armstrong",
  "craft": "Apollo 11"
}

my_dictionary["people"].append(astronaut)
my_dictionary["number"] += 1
print(json.dumps(my_dictionary, indent=2))

This example modifies the JSON data in two ways. First it appends a new astronaut to the list of people, then it increases the value for number by one. This results in:

{
  "number": 4,
  "message": "success",
  "people": [
    {
      "craft": "ISS",
      "name": "Chris Cassidy"
    }, 
    {
      "craft": "ISS",
      "name": "Anatoly Ivanishin"
    }, 
    {
      "craft": "ISS",
      "name": "Ivan Vagner"
    },
    {
      "name:": "Neil Armstrong",
      "craft": "Apollo 11"
    }
  ]
}

Save to and Read From JSON Files

The last thing this article will cover is how to write and read JSON files. To save JSON data to a file, open the file and write the JSON data to the file.

my_file = r'my_file.json'
with open(my_file, 'w', encoding='utf-8') as file:
    file.write(jsonResponse)

Here’s how to read JSON from a file and save it to a dictionary.

# Parse JSON from file and save it as a dictionary
with open(issFile, encoding = 'utf-8') as jsonFile:
    info = json.load(jsonFile)
    print(info)

Take Your Python Knowledge Further

This article has outline everything you need to know to get started working with JSON in Python. The Nylas Communications Platform is built on Python, so naturally, we have a lot of expertise to share about it. Take a look at some of the other content we’ve published about getting the most out of Python:

Related resources

Email API
How to Send Emails Using an API

Key Takeaways This post will provide a complete walkthrough for integrating an email API focused…

• 18 min read
Read more
CRM Platform
How to build a CRM in 3 sprints with Nylas

What is a CRM? CRM stands for Customer Relationship Management, and it’s basically a way…

• 13 min read
Read more
React Scheduling
How to create an appointment scheduler in your React app

Learn how to create an appointment scheduler in your React app using Nylas Scheduler. Streamline bookings and UX with step-by-step guidance.

• 13 min read
Read more