Matthew Lincoln, PhD Art History and Digital Research

Reshape JSON with jq: A Programming Historian Tutorial

My tutorial on the excellent command line tool jq for filtering, querying, and reshaping JSON is now live at The Programming Historian! From the lesson introduction:

JSON (JavaScript Object Notation) is a common data sharing format that can describe complex relationships. Many libraries, archives, museums, and social media sites expose their data through JSON-based APIs.

However, many tools for data analysis and visualization require input in flat tables (i.e. CSV), and because JSON is such a flexible data format, often with many nested levels of data, there is no one-size-fits-all graphical user interface for transforming JSON into other formats.

Working with data from an art museum API and from the Twitter API, this lesson teaches how to use the command-line utility jq to filter and parse complex JSON files into flat CSV files. This lesson will begin with an overview of the basic operators of the jq query syntax. Next, you will learn progressively more complex ways of connecting these operators together. By the end of the lesson, you will understand how to combine basic operators to create queries that can reshape many types of JSON data.

Happy data munging!

Cite this post:

Lincoln, Matthew D. "Reshape JSON with jq: A Programming Historian Tutorial." Matthew Lincoln, PhD (blog), 21 Jul 2016,

Tagged in: Data