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.

Add this line to your application's Gemfile:

gem 'cpiu', '~> 0.2'

And then execute:

bundle

Or install it yourself as:

gem install cpiu

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"
              }
            }
          },
          ...
        ]
      }
    ]
  }
}

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.

• Handle API errors

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

Copyright © 2017 Cody Logan

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/.