JQ Command: Parsing JSON for Dynamic Conky Widgets

When building Mimosa Amethyst, one of the biggest challenges I faced was integrating live data from APIs into a Conky interface — especially weather data from OpenWeatherMap. Most APIs return information in JSON format, which is structured but not directly readable or usable in Conky scripts.

This is where jq becomes essential. It's a lightweight command-line tool designed to read, parse, and manipulate JSON data — exactly what we need when transforming complex API outputs into clean Conky displays.

---

What is jq?

jq is like sed or awk, but for JSON. It allows you to navigate through JSON objects, extract values, format them, and even transform or filter data. It works extremely well in Bash scripts, making it ideal for minimal desktop setups using Conky.

Main features:

• Extract specific fields from JSON files
• Filter arrays, access nested objects
• Chain queries using pipes
• Works well with tools like curl, awk, xargs, etc.

---

Installing jq

Ubuntu / Debian:

sudo apt install jq

Arch / Manjaro:

sudo pacman -S jq

Fedora:

sudo dnf install jq

openSUSE:

sudo zypper install jq

Void Linux:

sudo xbps-install -S jq

Nix / NixOS:

nix-env -iA nixpkgs.jq

To Uninstall:

sudo apt remove jq  # Ubuntu/Debian

---

Using jq in a Conky Weather Script

In Mimosa Amethyst, I use a custom Bash script to fetch weather data from OpenWeatherMap. This script saves the JSON response locally. Then, jq is used to extract values like temperature, humidity, and weather description.

Example: extract city name

jq -r '.name' ~/.cache/weather.json

Extract temperature:

jq '.main.temp' ~/.cache/weather.json

Extract weather condition:

jq -r '.weather[0].main' ~/.cache/weather.json

Convert UNIX timestamp (sunrise) into readable time:

jq '.sys.sunrise' ~/.cache/weather.json | xargs -I{} date -d @{} +"%H:%M"

All of these are then inserted into Conky via ${exec} like so:

${exec ~/.config/conky/scripts/weather.sh -t}
${exec ~/.config/conky/scripts/weather.sh -m}

---

Real-World Snippet from Weather Script

Here’s how I used jq in my Bash fetcher:

# Get weather description (capitalized)
jq -r '.weather[0].description' "$weather_file" | sed "s|\<.|\\U&|g"

Extract wind direction degrees:

jq '.wind.deg' "$weather_file"

Extract visibility, trimmed from meters to kilometers:

jq '.visibility' "$weather_file" | sed 's/...$//'

This makes jq not just a parser, but a vital building block for readable, real-time widgets.

---

Why Use jq in Conky Themes?

• Minimal & Fast: Doesn't rely on bloated GUI libraries.
• Scriptable: Integrates smoothly with Bash or Lua scripts.
• Powerful: Supports deep querying of nested data.
• Reliable: Works well with any API returning JSON.

Especially in Conky setups where each CPU cycle counts, jq is perfect for parsing only what you need — and nothing more.

---

Final Thoughts

For anyone building advanced Conky themes with API integration — like Mimosa Amethyst — jq is a must-have utility. It turns unreadable JSON into clean, usable values that can be styled, animated, or conditionally displayed on your desktop.

Whether you’re fetching weather, stock prices, system stats, or even RSS feeds, jq gives you full control over your data pipelines.

Give it a try — and see how clean JSON parsing can empower your next Conky masterpiece.