Let’s pretend the year is 2007 and I have a close “friend” who is really excited about the upcoming 2010 World Cup. My friend is not too naive and realizes that airfare to Africa, lodging, tickets to the games, and Safaris are all very expensive. My friend has a little extra cash to save each month and with a three year time horizon he figures he can stow away a little money in a moderately aggressive mutual fund in order to take advantage of some growth opportunities.

Unfortunately for my friend the next two years would be some of the worst the world economy has ever seen. Like many people, my friend took a bath on his investments and his hopes and dreams of going to the World Cup went down the drain along with his money.

It’s too bad my friend didn’t keep better track of his investments. Perhaps if he had he could have pulled his money out of the stock market and salvaged his vacation. Since my friend is an avid Ruby lover I figured I’d help make sure he doesn’t end up in this situation ever again. That’s why I wrote GMoney, a RubyGem for interacting with the Google Finance API.

Background

The Google Finance API allows users to interact with Google Finance and can help developers programmatically “request a list of a user’s portfolios, retrieve performance and return statistics on an existing portfolio, query the positions and transactions in a portfolio, and create new portfolios and transactions.”

GMoney is a wrapper for this API and allows developers to take advantage of the API’s functionality using the Ruby programming language. To minimize the learning curve I tried to give GMoney an interface similar to that of ActiveRecord so that developers would have a familiar starting point.

Google Finance Model

The Google Finance model is pretty simple. It is made up of the following three entities:

Portfolios

Positions

Transactions

Installation

To install GMoney simply run the following command:

gem install gmoney

Login

You will need a Google account in order to use the Google Finance API. Once you have obtained an account you can login via GMoney using the following code:

require 'rubygems'
require 'gmoney'

GMoney::GFSession.login('<YOUR GOOGLE USER ID>','<YOUR GOOGLE PASSWORD>')

Create a portfolio

If you were to login to Google Finance for the first time using a browser you would see the following screen showing the default Google Finance Portfolio called “My Portfolio”:

To create your own Portfolio using GMoney use the following code:

portfolio = GMoney::Portfolio.new
portfolio.title = "My New Ruby Portfolio"
portfolio.save

After executing the code and refreshing the browser you should see that the “My New Ruby Portfolio” has been created.

Create a transaction(s)

As mentioned above transactions are used to buy and sell stocks within a given portfolio. The positions within your portfolio will be based on the transaction information. Running the following code will buy shares of Apple, Red Hat, Google, and Microsoft and place them into your portfolio:

stocks = {"NASDAQ:GOOG" => 529.00, 
          "NASDAQ:AAPL" => 192.00, 
          "NYSE:RHT" => 27.00, 
          "NASDAQ:MSFT" => 28.00}
 
stocks.each do |symbol, price| 
  transaction = GMoney::Transaction.new
  #pid is the human readable id of the portfolio created above
  transaction.portfolio = portfolio.pid
  transaction.type = GMoney::BUY
  transaction.shares = 50
  transaction.ticker = symbol
  transaction.price = price  
  transaction.save
end

The result of running the code is as follows:

Update Transaction

If you actually meant to buy 100 shares of Goolge instead of 50 you can update the transaction using the following code:

#I know the transaction id is '4'
transaction = GMoney::Transaction.find "#{portfolio.pid}/NASDAQ:GOOG/4"
transaction.shares = 100
transaction.save

The result:

Delete Transaction

We can delete a transaction like so:

GMoney::Position.find("#{portfolio.pid}/NASDAQ:MSFT").delete

Now we have no more MSFT stock:

Reading all the Positions in a Porfolio

If we’d like to see all of the positions within our portfolio we can execute this code:

portfolio.positions.each do |position| 
  puts position.title
end

Output:

Red Hat, Inc.
Apple Inc.
Google Inc.

Gotcha

There is a bit of a “gotcha” right now with the Google Finance API. For whatever reason, stock returns information is not being sent by Google. I figured it was something I was doing wrong in my code, but then I used Google’s official API client and was still unable to retrieve the returns data. I’ll be sure to file a bug report with Google over the next few days.

Conclusion

GMoney offers a lot more features than what has been written about here. Be sure to check out the documentation and the source code on Github. The full script of the code used for this blog entry can also be found on Github.

Overall building GMoney was an incredible learning experience. It was my first significant Ruby project and also my first Open Source project. As of today GMoney has been downloaded almost 200 times. I’ve tested GMoney on Windows and Linux using Ruby versions 1.8.6, 1.8.7, and 1.9.1 (via RVM). Feedback and bug reports are more than welcome.

With GMoney in place my friend will be sure to keep much better track of his investments and is looking forward to the 2014 World Cup in Brazil.

Disclaimer: I am in no way endorsing any of the companies mentioned in this blog entry and all company references are for example purposes only.