How to parse JSON in command line using jq

jq is an exceptional tool to parse JSON in command line. In this post, we will go through some of its basic options and usages.

Installation

If you are on Ubuntu or Debian, you can install jq using apt.

sudo apt-get install jq

On macOS, you can install it using Homebrew.

brew install jq

Usage

To demonstrate the usage of jq, we will use the sample JSON data provided by jsonplaceholder.typicode.com. Its /users endpoint lists 10 sample users in the following format.

$ curl -s https://jsonplaceholder.typicode.com/users
[
  {
    "id": 1,
    "name": "Leanne Graham",
    "username": "Bret",
    "email": "[email protected]",
    "address": {
      "street": "Kulas Light",
      "suite": "Apt. 556",
      "city": "Gwenborough",
      "zipcode": "92998-3874",
      "geo": {
        "lat": "-37.3159",
        "lng": "81.1496"
      }
    },
    "phone": "1-770-736-8031 x56442",
    "website": "hildegard.org",
    "company": {
      "name": "Romaguera-Crona",
      "catchPhrase": "Multi-layered client-server neural-net",
      "bs": "harness real-time e-markets"
    }
  },
.....

💡 curl -s runs curl in quiet mode and hides the request progress meter.

1. Extract the name from the first user.

$ curl -s https://jsonplaceholder.typicode.com/users | \
    jq '.[0] .name'
"Leanne Graham"

'.' refers to the entire JSON object.

'.[0]' refers to the first object in the JSON array.

'.[0] .name' refers to the name attribute in the first object in the JSON array.

We can use -r switch in jq to remove the quotes from the output.

$ curl -s https://jsonplaceholder.typicode.com/users | \
    jq -r '.[0] .name'
Leanne Graham

2. Extract the names of all users.

$ curl -s https://jsonplaceholder.typicode.com/users | \
    jq -r '.[] .name'
Leanne Graham
Ervin Howell
Clementine Bauch
Patricia Lebsack
Chelsey Dietrich
.....

'.[]' refers to all objects in the JSON array.

3. Extract selected attributes.

$ curl -s https://jsonplaceholder.typicode.com/users | \
    jq '.[0] | { name: .name, city: .address.city}'
{
  "name": "Leanne Graham",
  "city": "Gwenborough"
}

Notice how we extract city field using .address.city expression. It looks inside address object to fetch the city attribute of the user.

4. Extract selected attributes of all users.

$ curl -s https://jsonplaceholder.typicode.com/users | \
    jq '[.[] | { name: .name, city: .address.city}]'
[
  {
    "name": "Leanne Graham",
    "city": "Gwenborough"
  },
  {
    "name": "Ervin Howell",
    "city": "Wisokyburgh"
  },
.....
]

Wrapping the expression inside [] encloses the result in an array.

5. Conditionally extract attributes of users.

$ curl -s https://jsonplaceholder.typicode.com/users | \
    jq -r '.[] | select(.address.zipcode == "92998-3874") | .name'
Leanne Graham

Using select function, we can filter through the JSON objects based on a boolean expression. In this example, we are parsing the names of all users with zipcode 92998-3874.

jq is quite useful in shell scripts that process JSON data. It has many other features and they all are documented in its manual.