An Elixir client for the FRED® (Federal Reserve Economic Data) API, powered by Req.

FRED® (Federal Reserve Economic Data) provides access to over 800,000 economic time series from 100+ sources including the Bureau of Labor Statistics, the Bureau of Economic Analysis, and the Federal Reserve Board. This library was written to allow readers of Elixir For Finance to collect, analyze and visualize economic data from Fred, but it is a complete Fred API client and can be used outside the context of the book.

To learn how you can analyze and visualize the financial markets using Livebook, Explorer, Scholar and Nx, be sure to pick up a copy of our book:

Contents

• Installation
• Configuration
• Level Up You Elixir Skills
• Quick Start
• API Coverage
• Livebook Notebooks
• Telemetry

Installation

Add fred to your list of dependencies in mix.exs:

def deps do
  [
    {:fred, "~> 0.5.0"}
  ]
end

Configuration

You'll need a free FRED API key. Register here.

# config/config.exs
config :fred, api_key: "your_api_key_here"

Or use an environment variable:

config :fred, api_key: System.fetch_env!("FRED_API_KEY")

Optional Settings

config :fred,
  api_key: System.fetch_env!("FRED_API_KEY"),
  recv_timeout: 30_000 # HTTP client timeout

Level Up Your Elixir Skills!

Everything I have learned building production Elixir systems ends up in one of two places: an open source library on Hex, or a book. The libraries are free and will stay that way. The books are what let me keep writing them.

If this library has been useful to you, picking up one of my books is the best way to support this library and the many others that I maintain. You'll also gain knowledge that took me years to attain!

Elixir For Finance — Learn how to navigate markets and trading without leaving the BEAM. Livebook for exploration, Explorer for dataframes, VegaLite for visualizations. This book goes through it all!

Elixir Patterns — The essential BEAM handbook for the busy developer. The patterns and mental models covered in this book teach you how to build scalable systems that can handle whatever production throw at them.

Programming Nerves — The best place to start if you are looking to get your own hardware projects up and running with Elixir and Nerves. I doubt you'll find a more fun and enjoyable hardware book out there!

Build a Weather Station with Elixir and Nerves — A project-based introduction to Nerves. Wire up the sensors, capture readings and then pipe the data into a time series database that can be visualized with Grafana.

Quick Start

Once you have the Fred library added to your mix.exs file, obtained a Fred API key and added the necessary configuration, you can start your project with FRED_API_KEY=YOUR_KEY_GOES_HERE iex -S mix and run queries like so:

iex(1)> ["GDP", "UNRATE", "CPIAUCSL"] |>
...(1)> Fred.Series.observations_as_data_frame(frequency: :a) |>
...(1)> Explorer.DataFrame.print(limit: 10, limit_dots: :bottom)
+---------------------------------------------------------------------+
|             Explorer DataFrame: [rows: 79, columns: 4]              |
+------------+------------------+------------------+------------------+
|    date    |     CPIAUCSL     |      UNRATE      |       GDP        |
|   <date>   | <decimal[38, 3]> | <decimal[38, 3]> | <decimal[38, 3]> |
+============+==================+==================+==================+
| 1947-01-01 | 22.332           | nil              | 249.616          |
| 1948-01-01 | 24.045           | 3.800            | 274.468          |
| 1949-01-01 | 23.809           | 6.100            | 272.475          |
| 1950-01-01 | 24.063           | 5.200            | 299.827          |
| 1951-01-01 | 25.973           | 3.300            | 346.913          |
| 1952-01-01 | 26.567           | 3.000            | 367.341          |
| 1953-01-01 | 26.768           | 2.900            | 389.218          |
| 1954-01-01 | 26.865           | 5.600            | 390.549          |
| 1955-01-01 | 26.796           | 4.400            | 425.480          |
| 1956-01-01 | 27.191           | 4.100            | 449.353          |
| …          | …                | …                | …                |
+------------+------------------+------------------+------------------+

:ok

API Coverage

This library allows you to access all the endpoints from the Fred V1 API. Each group of Fred API endpoints is handled by the following library modules:

• Fred.Categories - Get data on Fred data categories
• Fred.Releases - Get data on Fred data releases
• Fred.Series - Get data (time series data) on actual economic observations
• Fred.Sources - Get the sources of the Fred data
• Fred.Tags - Get the tags associated with economic data
• Fred.Maps - Get regional data and shape files from Fred

Be sure to check out each individual module to see the options available for each endpoint.

Livebook Notebooks

The livebooks/ directory contains interactive Livebook notebooks that demonstrate the library with live charts:

To run them, open Livebook, set the FRED_API_KEY environment variable, and open any .livemd file to see how you can use this library in conjunction with VegaLite and MapLibre.

Telemetry

Fred emits :telemetry spans for every API request, giving you full observability over latency, error rates, and usage patterns. For more information, be sure to check out the Fred.Telemetry module.

Quick Setup - Built-in Logger

The fastest way to see what's happening is to attach the built-in logger handler. Add it to your application's start/2 callback:

defmodule MyApp.Application do
  use Application

  def start(_type, _args) do
    # Add this line to attach the logger to the telemetry events
    Fred.Telemetry.Logger.attach()

    children = [
      ...
    ]

    Supervisor.start_link(children, strategy: :one_for_one)
  end
end

With that in place, you should see log output like so whenever you make a call to the Fred API:

[info] [fred] GET /series/observations - 200 in 142ms (params: %{series_id: "UNRATE", frequency: :m})
[info] [fred] GET /series - error in 83ms: (400) Bad Request (params: %{series_id: ""})
[info] [fred] GET /series/observations - exception in 5012ms: %Req.TransportError{reason: :timeout}

Configure the log level or use a custom handler ID:

Fred.Telemetry.Logger.attach(level: :debug, handler_id: "my-fred-log")

Detach when you no longer need it:

Fred.Telemetry.Logger.detach()