Fred.Maps (Fred v0.4.0)

Copy Markdown View Source

Functions for the FRED Maps (GeoFRED) API endpoints.

The GeoFRED API provides access to geographic/regional economic data and shape files. Not all FRED series have geographic data available. The shapes endpoint specifically returns GeoJSON which can then be parsed by the Geo library to be turned into Geo structs.

Endpoints

Coordinate System

The GeoFRED shapes endpoint returns coordinates as quantized integers, not standard WGS84 longitude/latitude. These shapes cannot be rendered directly on web maps (MapLibre, Leaflet, etc.) without dequantization. For map rendering, use standard GeoJSON boundary files from sources like the US Census Bureau and use Fred.Maps.regional_data/4 or Fred.Series for the economic data.

Summary

Functions

regional_data(series_group, region_type, date, opts \\ [])

Get regional economic data by series group.

series_data(series_id, opts \\ [])

Get series data for a geographic region.

series_group(series_id)

Get the series group information for a regional data series.

shapes(shape)

Get shape files for a geographic type. Returns GeoJSON data for the specified shape type.

Functions

regional_data(series_group, region_type, date, opts \\ [])

@spec regional_data(
  series_group :: String.t(),
  region_type :: String.t(),
  date :: Date.t(),
  keyword()
) ::
  Fred.Client.response()

Get regional economic data by series group.

The region_type argument must be one of:

  • :bea
  • :msa
  • :frb
  • :necta
  • :state
  • :country
  • :county
  • :censusregion

Options

  • :aggregation_method (atom/0) - How the data should be aggregated. Supported values are:
  • :avg - Average
  • :sum - Sum
  • :eop - End of period

  • :frequency (atom/0) - Frequency filter. Supported values are:

    • :d - Daily
    • :w - Weekly
    • :bw - Biweekly
    • :m - Monthly
    • :q - Quarterly
    • :sa - Semiannual
    • :a - Annual
    • :wef - Weekly, Ending Friday
    • :weth - Weekly, Ending Thursday
    • :wew - Weekly, Ending Wednesday
    • :wetu - Weekly, Ending Tuesday
    • :wem - Weekly, Ending Monday
    • :wesu - Weekly, Ending Sunday
    • :wesa - Weekly, Ending Saturday
    • :bwew - Biweekly, Ending Wednesday
    • :bwem - Biweekly, Ending Monday

  • :season (atom/0) - Seasonal adjustment filter. Supported values are:

    • :SA - Seasonally Adjusted
    • :NSA - Not Seasonally Adjusted
    • :SSA - Smoothed Seasonally Adjusted
    • :SAAR - Seasonally Adjusted Annual Rate
    • :NSAAR - Not Seasonally Adjusted Annual Rate

  • :start_date (struct of type Date) - Start of date range.

  • :transformation (atom/0) - Data transformation. Supported values are:

    • :lin - Levels (no transformation, default)
    • :chg - Change
    • :ch1 - Change from year ago
    • :pch - Percent change
    • :pc1 - Percent change from year ago
    • :pca - Compounded annual rate of change
    • :cch - Continuously compounded rate of change
    • :cca - Continuously compounded annual rate of change
    • :log - Natural Log

  • :units (atom/0) - Data value transformation. Supported values are:

    • :lin - Levels (no transformation, default)
    • :chg - Change
    • :ch1 - Change from year ago
    • :pch - Percent change
    • :pc1 - Percent change from year ago
    • :pca - Compounded annual rate of change
    • :cch - Continuously compounded rate of change
    • :cca - Continuously compounded annual rate of change
    • :log - Natural Log

Examples

iex> {:ok, _} =
...>   Fred.Maps.regional_data(
...>     "882",
...>     :state,
...>     ~D[2023-01-01],
...>     frequency: :a,
...>     units: :lin,
...>     season: :NSA
...>   )

iex> {:error, %Fred.Error{type: :option_error}} =
...>   Fred.Maps.regional_data("882", :state, ~D[2023-01-01], units: "Bad Input")

series_data(series_id, opts \\ [])

@spec series_data(series_id :: String.t(), opts :: keyword()) ::
  Fred.Client.response()

Get series data for a geographic region.

Options

  • :date (struct of type Date) - The observation date.

  • :start_date (struct of type Date) - Start of date range.

Examples

iex> {:ok, _wisconsin_cpi} = Fred.Maps.series_data("WIPCPI")

iex> {:error, %Fred.Error{type: :option_error}} =
...>   Fred.Maps.series_data("WIPCPI", date: "Bad Input")

series_group(series_id)

@spec series_group(series_id :: String.t()) :: Fred.Client.response()

Get the series group information for a regional data series.

Examples

iex> {:ok, series_group} = Fred.Maps.series_group("SMU56000000500000001a")
iex> %{"series_group" => _series_group} = series_group

shapes(shape)

@spec shapes(shape :: String.t()) :: {:ok, map() | list()} | {:error, Fred.Error.t()}

Get shape files for a geographic type. Returns GeoJSON data for the specified shape type.

The shape argument must be one of the following values:

  • :bea - Bureau of Economic Anaylis Region
  • :msa - Metropolitan Statistical Area
  • :frb - Federal Reserve Bank Districts
  • :necta - New England City and Town Area
  • :state
  • :country
  • :county - USA Counties
  • :censusregion - US Census Regions
  • :censusdivision - US Census Divisons

Examples

iex> {:ok, geojson} = Fred.Maps.shapes("state")
iex> %Geo.GeometryCollection{geometries: [_ | _]} = geojson