Manipulating JSON with jq

Setting up jq

The jq command-line program lets us format and manipulate JSON data. It’s perfect when exploring APIs from the command line. We provide jq with some JSON data to process and a filter to apply. It transforms the JSON data and displays the results.

We install jq from the package manager. On Ubuntu, we use apt:

sudo apt install jq

On macOS, we use brew:

brew install jq

One of the most common uses is to pretty print JSON results from curl.

Open Notify has several free APIs we can query to find information about the International Space Station (ISS). If we use curl to request data from this endpoint, which displays the current location of the ISS, the output might not be very readable:

curl http://api.open-notify.org/iss-now.json

Use the terminal below to practice this command.

Using jq

We can use jq to format the output. We take the output from curl and pipe it to the jq command, applying the dot (.) filter, which doesn’t do any processing:

curl http://api.open-notify.org/iss-now.json | jq '.'

Use the terminal below to practice these commands.

That by itself is incredibly helpful, but it’s not very nice to repeatedly hit an external API when we’re testing something. We should make a local cache of this data if we want to play with it more. When we make that local cache, we can format the text too. If we combine the previous command with output redirection, we can save this nicely formatted output to a local file:

curl http://api.open-notify.org/iss-now.json | jq '.' > space.json

Now, we can use ...