# Transform REST API Responses into Readable ASCII Tables with CLI Tools

![banner](https://articles.aux4.blog/data/posts/aux4/transform-rest-api-into-ascii-tables/banner.png)

## Introduction

Ever fetched data from a REST API only to get buried in nested JSON that's hard to scan quickly in the terminal? Whether you're debugging an endpoint, building a script, or just exploring data, you need a way to simplify and visualize it without firing up a full IDE or scripting language.

In this post, we'll pull country details from the REST Countries API, strip it down to essentials like flags, names, and populations, and pipe it straight into a clean ASCII table — all from the command line.

You'll end up with a pipeline that's fast, repeatable, and perfect for one-off queries or automation.

## Install the packages

```bash
aux4 aux4 pkger install aux4/adapter aux4/2table
```

## Fetching Country Data from the API

Start with the basics: grabbing the raw data. The REST Countries API gives you a massive JSON array with details on every country. We'll focus on key fields like codes, names, flags, capitals, languages, populations, timezones, and continents.

Run this to see the structure:

```bash
curl 'https://restcountries.com/v3.1/all?fields=cca3,name,flag,capital,languages,population,timezones,continents' \
  --silent | head -c 1000
```

The output looks something like this:

```json
[{"name":{"common":"Lithuania","official":"Republic of Lithuania","nativeName":{"lit":{"official":"Lietuvos Respublikos","common":"Lietuva"}}},"cca3":"LTU","capital":["Vilnius"],"languages":{"lit":"Lithuanian"},"flag":"🇱🇹","population":2794700,"timezones":["UTC+02:00"],"continents":["Europe"]}]
```

It's a lot — over 250 countries with nested objects everywhere. Languages are key-value pairs (e.g., `{"lit": "Lithuanian"}`), capitals and continents are arrays, and you just want the essentials.

## Simplifying the JSON Response

Now, transform that raw mess into something usable. Create a `countries.yaml` config file to define exactly what to extract:

```yaml
config:
  countries:
    format: json
    mapping:
      flag: $.flag
      cca3: $.cca3
      name: $.name.common
      capital: $.capital[0]
      continent: $.continents[0]
      languages: $.languages
      timezones: $.timezones
      population: $.population
```

This grabs the flag emoji, country code, common name, first capital (handling multiples like South Africa's), first continent, the full languages object, timezones array, and population.

Pipe the API response through it:

```bash
curl 'https://restcountries.com/v3.1/all?fields=cca3,name,flag,capital,languages,population,timezones,continents' \
  --silent \
  | aux4 adapter map --configFile countries.yaml --config countries \
  | head -c 2000
```

Here's a snippet of the cleaned-up JSON:

```json
[
  {
    "flag": "🇱🇹",
    "cca3": "LTU",
    "name": "Lithuania",
    "capital": "Vilnius",
    "continent": "Europe",
    "languages": {
      "lit": "Lithuanian"
    },
    "timezones": "UTC+02:00",
    "population": 2794700
  },
  {
    "flag": "🇨🇱",
    "cca3": "CHL",
    "name": "Chile",
    "capital": "Santiago",
    "continent": "South America",
    "languages": {
      "spa": "Spanish"
    },
    "timezones": "UTC-06:00, UTC-04:00",
    "population": 19116209
  }
]
```

Notice how capitals and continents take the first item, timezones join into a string, and languages stay as an object for now (we'll handle display next).

For multi-language countries like Bolivia:

```json
{
  "cca3": "BOL",
  "name": "Bolivia",
  "capital": "Sucre",
  "continent": "South America",
  "languages": {
    "aym": "Aymara",
    "grn": "Guaraní",
    "que": "Quechua",
    "spa": "Spanish"
  },
  "timezones": "UTC-04:00"
}
```

And for multi-capital countries like South Africa, `$.capital[0]` picks the first one:

```json
{
  "cca3": "ZAF",
  "name": "South Africa",
  "capital": "Pretoria",
  "continent": "Africa"
}
```

This keeps things simple — no more deep nesting, just the fields you need.

## Rendering Data as an ASCII Table

With the JSON streamlined, pipe it to `aux4 2table`. Specify columns and let it handle alignment, even for objects and arrays:

```bash
curl 'https://restcountries.com/v3.1/all?fields=cca3,name,flag,capital,languages,population,timezones,continents' \
  --silent \
  | aux4 adapter map --configFile countries.yaml --config countries \
  | aux4 2table flag,cca3,name,capital,continent,languages,timezones,population
```

The result is a neat ASCII table:

```text
 flag  cca3  name        capital     continent      languages         timezones             population
 🇱🇹   LTU   Lithuania   Vilnius     Europe         lit: Lithuanian   UTC+02:00             2794700
 🇨🇱   CHL   Chile       Santiago    South America  spa: Spanish      UTC-06:00, UTC-04:00  19116209
 🇧🇯   BEN   Benin       Porto-Novo  Africa         fra: French       UTC+01:00             12123198
 🇫🇰   FLK   Falkland    Stanley     South America  eng: English      UTC-04:00             2563
 🇬🇪   GEO   Georgia     Tbilisi     Asia           kat: Georgian     UTC+04:00             3714000
 ...
```

Languages show as `lit: Lithuanian` (key-value pairs flattened), timezones as comma-separated, and populations right-aligned.

For better labels, rename columns using the `field:"Label"` syntax:

```bash
curl 'https://restcountries.com/v3.1/all?fields=cca3,name,flag,capital,languages,population,timezones,continents' \
  --silent \
  | aux4 adapter map --configFile countries.yaml --config countries \
  | aux4 2table flag,cca3:"Code",name:"Country",capital:"Capital",continent:"Region",languages:"Languages",timezones:"Time Zones",population:"Pop."
```

Output:

```text
 flag  Code  Country     Capital     Region         Languages         Time Zones            Pop.
 🇱🇹   LTU   Lithuania   Vilnius     Europe         lit: Lithuanian   UTC+02:00             2794700
 🇨🇱   CHL   Chile       Santiago    South America  spa: Spanish      UTC-06:00, UTC-04:00  19116209
 🇧🇯   BEN   Benin       Porto-Novo  Africa         fra: French       UTC+01:00             12123198
 ...
```

Want Markdown output instead? Swap the format:

```bash
curl 'https://restcountries.com/v3.1/all?fields=cca3,name,flag,capital,languages,population,timezones,continents' \
  --silent \
  | aux4 adapter map --configFile countries.yaml --config countries \
  | aux4 2table --format md flag,cca3,name,capital,continent,languages,timezones,population
```

| flag | cca3 | name | capital | continent | languages | timezones | population |
| --- | --- | --- | --- | --- | --- | --- | --- |
| 🇱🇹 | LTU | Lithuania | Vilnius | Europe | lit: Lithuanian | UTC+02:00 | 2794700 |
| 🇨🇱 | CHL | Chile | Santiago | South America | spa: Spanish | UTC-06:00, UTC-04:00 | 19116209 |
| 🇧🇯 | BEN | Benin | Porto-Novo | Africa | fra: French | UTC+01:00 | 12123198 |

Perfect for pasting into READMEs or pull request descriptions.

## Conclusion

With two aux4 packages and a YAML config, you get a dead-simple CLI pipeline to fetch API data, transform it with precise mappings, and view it as a table — all without leaving your terminal.

The key idea: **aux4/adapter** handles the data shaping (flattening nested JSON, picking array elements, joining values), and **aux4/2table** handles the presentation. You can swap the API, change the mapping, or pipe the output into other tools.

## See Also

* [aux4/adapter](https://hub.aux4.io/r/public/packages/aux4/adapter)
* [aux4/2table](https://hub.aux4.io/r/public/packages/aux4/2table)
* [aux4 Package Hub](https://hub.aux4.io)