CPIU

CPIU is a Ruby interface for CPI-U data provided by the U.S. Bureau of Labor Statistics. CPI-U data are commonly used for calculating inflation. More info on the BLS Public Data API is available here.

Neither I nor BLS.gov can vouch for the data or analyses derived from these data after the data have been retrieved from BLS.gov.

Installation

Add this line to your application's Gemfile:

gem 'cpiu', '~> 0.2'

And then execute:

bundle

Or install it yourself as:

gem install cpiu

Usage

Add the following to your program:

require 'cpiu'

In order to get the most out of the BLS API, you will need a registration key, which can be obtained here. Create a file named .env in the root of your project folder with the contents BLS_API_KEY=<your key here>. The API can still be queried without a key, but there are restrictions on what data will be returned.

The following methods will retrieve JSON objects containing CPI-U data:

CPIU::Data.single_year(year) - data for a single year
CPIU::Data.year_range(startyear, endyear) - data for a year range no greater than 20 years

The data is returned in an array of hashes:

[
  {
    "year" => "1913",
    "period" => "M12",
    "periodName" => "December",
    "value" => "10.0",
    "footnotes" => [{}]
  },
  ...
]

If you just want CPI-U values:

CPIU::Data.cpiu_year(year) - the annual average CPI value for a year
CPIU::Data.cpiu_month(year, month) - the CPI value for a particular month

A raw API call method is available too:

CPIU::API.request_data(startyear, endyear, ann_avg, calcs)

If set to true, ann_avg will return the average CPI value for each year, and calcs will return net and percent changes in CPI. This method returns all response data in the form of a hash:

{
  "status" => "REQUEST_SUCCEEDED",
  "responseTime" => 34,
  "message" => [],
  "Results" => {
    "series" => [
      {
        "seriesID" => "CUUR0000SA0",
        "data" => [
          {
            "year" => "1913",
            "period" => "M13",
            "periodName" => "Annual",
            "value" => "9.9",
            "footnotes" => [{}],
            "calculations" => {
              "net_changes" => {},
              "pct_changes" => {
                "1" => "-1.0",
                "3" => "-1.0",
                "6" => "0.0"
              }
            }
          },
          ...
        ]
      }
    ]
  }
}

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the .gem file to rubygems.org.

TODO

Handle API errors

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/clpo13/ruby_cpiu.

License

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

A copy of the GNU General Public License can be found in LICENSE.txt and at http://www.gnu.org/licenses/.

clpo13 / cpiu-ruby