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