3.4jq -- Parse JSON

jq is a command-line JSON processor. Most APIs return JSON, and jq lets you extract, filter, and transform that data.

Basic Usage

# Pretty-print JSON
curl -s https://api.example.com/users | jq .

# Extract a specific field
curl -s https://api.example.com/users/1 | jq '.name'
# Output: "John Doe"

# Extract a nested field
curl -s https://api.example.com/users/1 | jq '.address.city'
# Output: "New York"

# Extract from an array
curl -s https://api.example.com/users | jq '.[0].name'
# Output: "John Doe" (first user's name)

# Get all names from an array
curl -s https://api.example.com/users | jq '.[].name'
# Output:
# "John Doe"
# "Jane Smith"
# "Bob Wilson"

Filtering and Selecting

# Filter array elements
curl -s https://api.example.com/users | jq '.[] | select(.role == "admin")'

# Filter by numeric comparison
curl -s https://api.example.com/orders | jq '.[] | select(.total > 100)'

# Filter by string content
curl -s https://api.example.com/users | jq '.[] | select(.email | contains("@example.com"))'

# Multiple conditions
curl -s https://api.example.com/users | jq '.[] | select(.role == "admin" and .active == true)'

Transforming Data

# Count items in an array
curl -s https://api.example.com/users | jq length
# Output: 42

# Create a new object shape
curl -s https://api.example.com/users | jq '.[] | {name: .name, email: .email}'

# Extract specific fields into CSV-like format
curl -s https://api.example.com/users | jq -r '.[] | [.id, .name, .email] | @csv'
# Output:
# 1,"John Doe","john@example.com"
# 2,"Jane Smith","jane@example.com"

# Sort by field
curl -s https://api.example.com/users | jq 'sort_by(.created_at) | reverse'

# Group by field
curl -s https://api.example.com/users | jq 'group_by(.role) | .[] | {role: .[0].role, count: length}'

Working with Local Files

# Parse a local JSON file
jq '.dependencies' package.json

# Extract test configuration
jq '.scripts | to_entries | .[] | select(.key | startswith("test"))' package.json

# Modify JSON (useful for test data)
jq '.baseURL = "https://staging.example.com"' config.json > config-staging.json