Skip to content

mdsabo/fred-rs

master
Switch branches/tags
Code

Latest commit

 

Git stats

Files

Permalink
Failed to load latest commit information.
Type
Name
Latest commit message
Commit time
 
 
src
 
 
 
 
 
 
 
 
 
 

fred-rs

fred-rs is a simple interface for accessing the Federal Reserve Bank of St. Louis's FRED API.


[dependencies]
fred_rs = "0.1.1"

Useful Links

fred-rs Documentation
FRED API Documentaion
FRED API Key Information


FRED (Federal Reserve Economic Data)

FRED is a large online database of economic data hosted by the Federal Reserve Bank of St. Louis. The website currently hosts approximately "672,000 US and international time series from 89 sources" including the the graph of unemployment rate shown below.

Unemployment Graph
U.S. Bureau of Labor Statistics, Unemployment Rate [UNRATE], retrieved from FRED, Federal Reserve Bank of St. Louis; https://fred.stlouisfed.org/series/UNRATE, February 20, 2020.

Access to the raw data is available through the FRED API. fred-rs is an intermediate layer between the HTTPS client and the user application. Requests to the FRED API are made through structured calls to the fred_rs::FredClient and data is returned as usable data objects (structs).

fred-rs Overview

fred-rs acts as a middleman to facilitate requests to the FRED API. The user application creates and manages a FredClient, which manages the HTTPS client and parses incoming data. Currently the client uses the reqwest::blocking::client, but if there exists a need for an async version then that can be explored. The diagram below shows the general architecture from an application standpoint.

architecture

Usage

Below is an example of the general usage for accessing an observation or data series.

use fred_rs::client::FredClient;
use fred_rs::series::observation::{Builder, Units, Frequency, Response};

// Create the client object
let mut c = match FredClient::new() {
    Ok(c) => c,
    Err(msg) => {
        println!("{}", msg);
        return
    },
};

// Create the argument builder
let mut builder = Builder::new();

// Set the arguments for the builder
builder
    .observation_start("2000-01-01")
    .units(Units::PCH)
    .frequency(Frequency::M);

// Make the request and pass in the builder to apply the arguments
let resp: Response = match c.series_observation("GNPCA", Some(builder)) {
    Ok(resp) => resp,
    Err(msg) => {
        println!("{}", msg);
        return
    },
};

Request Parameters

All endpoints use the builder approach to construct the API URL. Each builder method corresponds to a parameter that can be added to the API request.

In the example above, three parameters are added to the request, observation_start, units and frequency. The FRED API Documentation explains the possible parameters for each endpoint. Required paramters (except the tag_names paramter) are passed to the client function itself. In the example, series_id is a required paramter and is passed directly to the client function as "GNPCA". The tag_names parameter available on some endpoints accepts a list of arguments, so it is easier to pass this argument to the builder.

API Key

Developers need to request an API Key in order to access FRED. This can be done at https://research.stlouisfed.org/docs/api/api_key.html.

fred-rs looks for the FRED_API_KEY environment variable by default. The variable can be set with the following line in Bash.

export FRED_API_KEY=abcdefghijklmnopqrstuvwxyz123456

Alternatively, the FredClient.with_key() function allows the key to be set from a string reference.

use fred_rs::client::FredClient;

let mut client = match FredClient::new() {
    Ok(c) => c,
    Err(msg) => {
        println!("{}", msg);
        return
    },
};

client.with_key("abcdefghijklmnopqrstuvwxyz123456");

Issues/Bugs/Improvments/Help/Questions

If you discover any issues or bugs, want to suggest any improvements, or have questions about the crate, feel free to open a GitHub issue or email me directly at matthewdsabo@gmail.com with fred-rs in the subject line.

License

Licensed under either of Apache License, Version 2.0 or MIT license at your option.
Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in this crate by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

About

A Rust crate for accessing the Federal Reserve Bank of St. Louis FRED API.

Resources

License

Apache-2.0, MIT licenses found

Licenses found

Apache-2.0
LICENSE-APACHE
MIT
LICENSE-MIT

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published

Languages