FRED API Library and Command Line
This gem provides both a Ruby library and a command line interface for the FRED data service.
$ gem install fredric
Or with bundler:
- Easy to use interface.
- Use as a library or through the command line.
- Access any FRED endpoint and option directly.
- Display output as JSON, XML or CSV.
- Save output to a file as JSON, XML or CSV.
- Includes a built in file cache (disabled by default).
First, require and initialize with your FRED API Key.
require 'fredric' fredric = Fredric::API.new 'your-api-key'
Now, you can access any FRED endpoint with any optional parameter, like this:
result = fredric.get "series/observations", series_id: 'GNPCA'
In addition, for convenience, you can use the first part of the endpoint as a method name, like this:
result = fredric.series 'observations', series_id: 'GNPCA'
In other words, these calls are the same:
fredric.get 'endpoint', param: value fredric.endpoint, param: value
as well as these two:
fredric.get 'endpoint/sub', param: value fredric.endpoint 'sub', param: value
By default, you will get a ruby hash in return. If you wish to have more
control over the response, use the
get! method instead:
result = fredric.get! "series/ovservations", series_id: 'GNPCA' # Request Object p payload.request.class # => HTTParty::Request # Response Object p payload.response.class # => Net::HTTPOK p payload.response.body # => JSON string p payload.response.code # => 200 p payload.response.msg # => OK # Headers Object p payload.headers # => Hash with headers # Parsed Response Object p payload.parsed_response # => Hash with HTTParty parsed response # (this is the content returned with #get)
You can get the response as CSV by calling
result = fredric.get_csv "series/overvations", series_id: 'GNPCA' # => CSV string
Fredric automatically decides which part of the data to convert to CSV.
When there is an array in the response (for example, in the case of
observations), it will be used as the CSV data. Otherwise, the entire
response will be treated as a single-row CSV.
To save the output directly to a file, use the
fredric.save "filename.json", "series/overvations", series_id: 'GNPCA'
Or, to save CSV, use the
fredric.save_csv "filename.csv", "series/overvations", series_id: 'GNPCA'
The command line utility
fred acts in a similar way. To set your
FRED API Key, simply set it in the environment variable
$ export FRED_KEY=y0urAP1k3y
These commands are available:
$ fred get [--csv] PATH [PARAMS...] - print the output.
$ fred pretty PATH [PARAMS...] - print a pretty JSON.
$ fred see PATH [PARAMS...] - print a colored output.
$ fred url PATH [PARAMS...] - show the constructed URL.
$ fred save [--csv] FILE PATH [PARAMS...] - save the output to a file.
fred --help for more information, or view the full usage help.
# Shows details about a data series $ fred see series series_id:GNPCA # Shows data as CSV $ fred get --csv series/observations series_id:GNPCA # Pass arguments that require spaces $ fred see series/search "search_text:consumer price index" limit:3 # Saves a file $ fred save --csv result.csv series/search search_text:cpi limit:3 # Shows the URL that Fredric has constructed, good for debugging $ fred url series/observations query:interest limit:5 # => https://api.stlouisfed.org/fred/series/observations?api_key=ce1e45e6551de5db555a09b88d23682f&file_type=json&query=interest&limit=5
We are using the Lightly gem for automatic HTTP caching. To take the path of least surprises, caching is disabled by default.
You can enable and customize it by either passing options on
initialization, or by accessing the
Lightly object directly at
a later stage.
fredric = Fredric::API.new 'apikey', use_cache: true fredric = Fredric::API.new 'apikey', use_cache: true, cache_dir: 'tmp' fredric = Fredric::API.new 'apikey', use_cache: true, cache_life: 120 # or fredric = Fredric::API.new 'apikey' fredric.cache.enable fredric.cache.dir = 'tmp/cache' # Change cache folder fredric.cache.life = 120 # Change cache life to 2 minutes
To enable caching for the command line, simply set one or both of these environment variables:
$ export FRED_CACHE_DIR=cache # default: 'cache' $ export FRED_CACHE_LIFE=120 # default: 3600 (1 hour) $ fred see category/children # => This call will be cached