Parse JSON APIs in Linux with jq Command

The jq command-line tool in Linux provides a lightweight, flexible, and powerful way to slice, filter, and transform JSON data returned by web APIs. This article explains how Linux environments combine jq with standard networking tools like curl to streamline REST API parsing, detailing essential techniques for payload extraction, data filtering, and shell script automation.

Fetching and Pretty-Printing API Responses

Modern web APIs communicate predominantly using JSON. When interacting with these endpoints on Linux, standard tools like curl or wget retrieve raw strings that are often minified, making them difficult to read. Piping the output directly into jq formats and colorizes the JSON:

curl -s https://api.example.com/users | jq .

The simple identity filter (.) parses the incoming stream, validates its syntax, and outputs properly indented JSON to the standard output (stdout).

Extracting Specific Fields and Arrays

Linux administrators and developers use jq filters to isolate specific key-value pairs without relying on brittle text-processing tools like grep, sed, or awk.

To retrieve a nested value:

curl -s https://api.example.com/status | jq '.server.database.uptime'

When dealing with JSON arrays, jq provides bracket notation to iterate over elements or extract specific indices:

Extract all elements in an array: jq '.items[]'
Target a specific index: jq '.items[0]'
Extract a single attribute from all objects in an array: jq '.items[].name'

Filtering and Querying Data

The built-in functions in jq enable complex data interrogation directly from the terminal.

Conditional filtering: Use select() to return only elements that match defined criteria, such as finding users with an active status:
```
curl -s https://api.example.com/users | jq '.[] | select(.isActive == true)'
```

Array transformations: Use map() to apply transformations to entire lists:

curl -s https://api.example.com/products | jq 'map({product_name: .title, cost: .price})'

Exporting Formatted and Raw Output

When feeding parsed API values into subsequent Linux commands, the default JSON string quoting can interfere with shell logic. Using the -r (raw-output) flag instructs jq to strip enclosing quotes from string values:

USER_TOKEN=$(curl -s https://api.example.com/auth | jq -r '.token')

For non-JSON exports, jq can convert arrays into Delimiter-Separated Values like CSV or TSV using built-in formatters:

curl -s https://api.example.com/metrics | jq -r '.[] | [.timestamp, .cpu_usage] | @csv'

Automation in Shell Scripts

Within Linux shell scripts, jq eliminates the need for heavyweight runtime environments such as Python or Node.js just to process network payloads. By handling error checking (with flags like -e to set exit statuses) and restructuring dynamic payloads, jq serves as a core pipeline component in automated backups, alerting systems, and CI/CD pipelines communicating with external cloud APIs.