# `Fred.Maps`
[🔗](https://github.com/akoutmos/fred/blob/master/lib/fred/maps.ex#L1)

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

  - `shapes/1` - [`/geofred/shapes/file`](https://fred.stlouisfed.org/docs/api/geofred/shapes.html)
  - `series_group/1` - [`/geofred/series/group`](https://fred.stlouisfed.org/docs/api/geofred/series_group.html)
  - `series_data/2` - [`/geofred/series/data`](https://fred.stlouisfed.org/docs/api/geofred/series_data.html)
  - `regional_data/4` - [`/geofred/regional/data`](https://fred.stlouisfed.org/docs/api/geofred/regional_data.html)

> #### Coordinate System {: .info}
>
> 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.

# `regional_data`

```elixir
@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` (`t:atom/0`) - How the data should be aggregated. Supported values are:
  - `:avg` - Average
  - `:sum` - Sum
  - `:eop` - End of period

* `:frequency` (`t: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` (`t: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` (`t: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` (`t: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`

```elixir
@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`

```elixir
@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`

```elixir
@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

---

*Consult [api-reference.md](api-reference.md) for complete listing*