According to US Vice President Kamala Harris, most US citizens would run out of money if faced by only $400 of unexpected costs. Since hearing this, I have made it my job to check every day whether I still have sufficient financial reserves. This includes tracking the current share price performance of some well-known companies. While there are many apps with portfolio settings that monitor a number of selected shares, I prefer to use command-line tools written in Go that run in a terminal window.

Figure 1 shows the output of the Go Pofo program (Pofo stands for portfolio). The Pofo program's output displays in six tiles (three at the bottom and three at the top), with each tile containing a bar chart to illustrate the share price performance of Apple, Netflix, Meta, Amazon, Tesla, and Google over the past six weeks. The program grabs the current and historical share price data from the data dealer Twelve Data [1] in a fraction of a second shortly after launching. Twelve Data offers a free basic plan for hobbyists that allows up to eight requests per minute and up to 800 per day before a limit kicks in.

Figure 1: Terminal with the Go Pofo program in action.

The program fetches the closing prices in US dollars of the six monitored shares on the New York Stock Exchange for the past 45 business days. It does so in one fell swoop with a single request to the server. Figure 2 shows the data for the hyper-nervous Netflix stock in the period between June 16 and July 31, 2023. In this time frame, the value of the share fluctuated wildly between $413.17 and $477.59. Alas, in a graph of absolute values, it is still more or less impossible to see any fluctuations, because, after all, the difference only accounts for around 15 percent of the total value.

Figure 2: Share price development of Netflix stock from JSON data.

This is why the massive price jumps that typical chart apps show (Figure 3) do not reflect absolute values – otherwise you would end up with very static blocks that would not impress anybody. To counteract this, typical chart applications transform the fluctuations into relative values so that a change of a few dollars is displayed over the entire chart height.

Figure 3: An iPhone's stock portfolio app shows relative changes.

Free After Registering

Twelve Data only provides the current price data for selected shares after you register with your email address. If you are successful, you will be given an API key (Figure 4) that must accompany each request you submit. The free trial account covers the entire US stock market; you only need a credit card for any endpoints purchased separately.

Figure 4: The free API key for share price data on the Twelve Data website.

If you wanted to follow stocks on a foreign exchange, on the other hand, such as the current price of the Volkswagen share on Germany's Xetra market (symbol VOW3:XETR), there's a substantial monthly fee. Ever since Yahoo shut down its financial API more than five years ago, free access to foreign stocks has been tricky. Twelve Data, as well as all of other providers' APIs that I researched, only supports the US market with its free tier.

Listing 1 shows the Go code that retrieves the historical prices of the comma-separated ticker symbols stored in symbols from data broker Twelve Data. The fetchQ() function starting in line 9 returns a hashmap of results if successful. It contains an array slice of dateVal structures under each ticker symbol (e.g., aapl for Apple). These structures each assign a date (e.g, 10-01-2023) to a share price (e.g., 123.45678).

To do this, the code puts together a request to the Twelve Data website, appending the symbol (the desired ticker symbols) and interval (time interval, one day in the example) parameters to the base URL, and adds the API key I obtained previously. Line 22 uses Get() to retrieve the response from the web. The parse() function called in line 32 grabs the blob of JSON that is returned (Figure 5) and fills the Go hashmap data structure mentioned earlier.

Figure 5: The JSON blob after querying the share prices from Twelve Data.

Digging into JSON

The result is a dictionary with the stock ticker symbols as keys, with an array slice under each symbol. The array's individual elements each assign a share price to a date. I am only interested in the close values here (i.e., the daily closing price). You could now tackle pulling the relevant parts out of the JSON blob without any trouble using a conventional approach where the developer defines appropriate Go data structures mapping the JSON in minute detail, which the JSON unmarshaler built into Go then imports from JSON into Go.

Instead, Listing 2 uses the handy gjson package from GitHub to elegantly disable Go's strict type checking before running JQuery-style queries to dig the nuggets out of the JSON. The resulting data structure, a hashmap with entries from ticker symbols, in turn points to array slices with tuples of timestamps and price values. Line 12 defines this result type and creates an instance in qMap. As the result, the parse() function, starting in line 14, returns a variable of this data type to the caller.

The gjson package offers a Get() function which in line 15 runs the @this query to parse the top level of the data, which is the ticker symbols included in the web result. Map(), also courtesy of the gjson package, immediately makes a Go map from this. The for loop in line 18 can then iterate across all the ticker symbols. Inside the loop, the query, [symbol].values.#.datetime, then extracts all the timestamps from the available data points. Array() makes a Go array from this. Same goes for the closing prices, listed under close in the JSON blob. The for loop starting in line 23 zips the two arrays into a new array of dateVal types – this completes the entry for each ticker symbol currently being processed.

Laying Tiles

Now the main program in Listing 3 needs to glue together the individual parts from Listing 1 and Listing 2 and set up the GUI. Like in previous Snapshots, I'm using the indestructible termui as the graphics package for the terminal; the components I need this time are the BarChart widget and the grid tile arranger. As you can see from Figure 1, a total of six tiles extend across the entire width and height of the terminal, sharing the space equally.

Instead of computing the X/Y coordinates of each widget, Listing 3 relies on the grid tiler that comes courtesy of termui. The tiler's Set() function in line 31 takes two rows, each with three BarChart widgets, all of which are arranged side by side in the charts array created previously. The call to the termui Render() function in line 44 expects the grid container widget as its only parameter and autonomously computes where to put the individual tiles.