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

Functions for the FRED Categories endpoints.

Categories organize FRED series into a hierarchical tree structure.
The root category has `category_id` 0.

## Endpoints

Below is a listing of the functions that this module contains along with what endpoints
they map to in the FRED API. Click on the endpoint to go to the FRED documentation for that
particular endpoint:

  - `children/2` - [`/fred/category/children`](https://fred.stlouisfed.org/docs/api/fred/category_children.html)
  - `get/2` - [`/fred/category`](https://fred.stlouisfed.org/docs/api/fred/category.html)
  - `related/2` - [`/fred/category/related`](https://fred.stlouisfed.org/docs/api/fred/category_related.html)
  - `related_tags/2` - [`/fred/category/related_tags`](https://fred.stlouisfed.org/docs/api/fred/category_related_tags.html)
  - `series/2` - [`/fred/category/series`](https://fred.stlouisfed.org/docs/api/fred/category_series.html)
  - `tags/2` - [`/fred/category/tags`](https://fred.stlouisfed.org/docs/api/fred/category_tags.html)

# `children`

```elixir
@spec children(category_id :: integer(), opts :: keyword()) :: Fred.Client.response()
```

Get the child categories for a specified parent category.

## Options

  * `:realtime_end` (struct of type `Date`) - End of the real-time period.

* `:realtime_start` (struct of type `Date`) - Start of the real-time period.

## Examples

    iex> {:ok, children} = Fred.Categories.children(0)
    iex> %{"categories" => [_ | _]} = children

    iex> {:error, %Fred.Error{type: :option_error}} =
    ...>   Fred.Categories.children(0, realtime_start: "Bad Input")

# `get`

```elixir
@spec get(category_id :: integer(), opts :: keyword()) :: Fred.Client.response()
```

Get a category.

## Options

  * `:realtime_end` (struct of type `Date`) - End of the real-time period.

* `:realtime_start` (struct of type `Date`) - Start of the real-time period.

## Examples

    iex> {:ok, category} = Fred.Categories.get(125)
    iex> %{
    ...>   "categories" => [
    ...>     %{"id" => 125, "name" => "Trade Balance", "parent_id" => 13}
    ...>   ]
    ...> } = category

    iex> {:error, %Fred.Error{type: :option_error}} =
    ...>   Fred.Categories.get(125, realtime_start: "Bad Input")

# `related`

```elixir
@spec related(category :: integer(), opts :: keyword()) :: Fred.Client.response()
```

Get the related categories for a given category.

A related category is a one-way relation between two categories that is not
part of the parent-child tree structure.

## Options

  * `:realtime_end` (struct of type `Date`) - End of the real-time period.

* `:realtime_start` (struct of type `Date`) - Start of the real-time period.

## Examples

    iex> {:ok, categories} = Fred.Categories.related(32073)
    iex> %{"categories" => [_ | _]} = categories

    iex> {:error, %Fred.Error{type: :option_error}} =
    ...>   Fred.Categories.related(32073, realtime_start: "Bad Input")

# `related_tags`

```elixir
@spec related_tags(category :: integer(), opts :: keyword()) :: Fred.Client.response()
```

Get the related FRED tags for a category.

Related tags are tags assigned to series that match all tags in `:tag_names`.

## Options

  * `:exclude_tag_names` (list of `t:String.t/0`) - List of tag names to exclude.

* `:filter_value` (`t:String.t/0`) - The value of the filter_variable attribute to filter results by. This requires that the `:filter_variable` is also provided.

* `:filter_variable` (`t:atom/0`) - The attribute to filter results by. Supported values are:
  - `:frequency`
  - `:units`
  - `:seasonal_adjustment`

* `:limit` (`t:pos_integer/0`) - Max results (between 1-1000).

* `:offset` (`t:pos_integer/0`) - Result offset.

* `:order_by` (`t:atom/0`) - Order the results by the provided field. Supported values are:
  - `:series_count`
  - `:popularity`
  - `:created`
  - `:name`
  - `:group_id`

* `:realtime_end` (struct of type `Date`) - End of the real-time period.

* `:realtime_start` (struct of type `Date`) - Start of the real-time period.

* `:search_text` (`t:String.t/0`) - Text to search tag names.

* `:sort_order` (`t:atom/0`) - The sort order of the results. Supported values are:
  - `:asc`
  - `:desc`

* `:tag_group_id` (`t:atom/0`) - Tag group filter. Supported values are:
  - `:freq` - Frequency
  - `:gen` - General or Concept
  - `:geo` - Geography
  - `:geot` - Geography Type
  - `:rls` - Release
  - `:seas` - Seasonal Adjustment
  - `:src` - Source

* `:tag_names` (list of `t:String.t/0`) - List of tag names to match.

## Examples

    iex> {:ok, tags} = Fred.Categories.related_tags(125, tag_names: ["services", "quarterly"])
    iex> %{"tags" => [_ | _]} = tags

# `series`

```elixir
@spec series(category :: integer(), opts :: keyword()) :: Fred.Client.response()
```

Get the series in a category.

## Options

  * `:exclude_tag_names` (list of `t:String.t/0`) - List of tag names to exclude.

* `:filter_value` (`t:String.t/0`) - The value of the filter_variable attribute to filter results by. This requires that the `:filter_variable` is also provided.

* `:filter_variable` (`t:atom/0`) - The attribute to filter results by. Supported values are:
  - `:frequency`
  - `:units`
  - `:seasonal_adjustment`

* `:limit` (`t:pos_integer/0`) - Max results (between 1-1000).

* `:offset` (`t:pos_integer/0`) - Result offset.

* `:order_by` (`t:atom/0`) - Order the results by the provided field. Supported values are:
  - `:series_id`
  - `:title`
  - `:units`
  - `:frequency`
  - `:seasonal_adjustment`
  - `:realtime_start`
  - `:realtime_end`
  - `:last_updated`
  - `:observation_start`
  - `:observation_end`
  - `:popularity`
  - `:group_popularity`

* `:realtime_end` (struct of type `Date`) - End of the real-time period.

* `:realtime_start` (struct of type `Date`) - Start of the real-time period.

* `:sort_order` (`t:atom/0`) - The sort order of the results. Supported values are:
  - `:asc`
  - `:desc`

* `:tag_names` (list of `t:String.t/0`) - List of tag names to match.

## Examples

    iex> {:ok, series} = Fred.Categories.series(125, limit: 10, order_by: :popularity, sort_order: :desc)
    iex> %{"seriess" => [_ | _]} = series

# `tags`

```elixir
@spec tags(category :: integer(), opts :: keyword()) :: Fred.Client.response()
```

Get the FRED tags for a category.

## Options

  * `:filter_value` (`t:String.t/0`) - The value of the filter_variable attribute to filter results by. This requires that the `:filter_variable` is also provided.

* `:filter_variable` (`t:atom/0`) - The attribute to filter results by. Supported values are:
  - `:frequency`
  - `:units`
  - `:seasonal_adjustment`

* `:limit` (`t:pos_integer/0`) - Max results (between 1-1000).

* `:offset` (`t:pos_integer/0`) - Result offset.

* `:order_by` (`t:atom/0`) - Order the results by the provided field. Supported values are:
  - `:series_count`
  - `:popularity`
  - `:created`
  - `:name`
  - `:group_id`

* `:realtime_end` (struct of type `Date`) - End of the real-time period.

* `:realtime_start` (struct of type `Date`) - Start of the real-time period.

* `:search_text` (`t:String.t/0`) - Text to search tag names.

* `:sort_order` (`t:atom/0`) - The sort order of the results. Supported values are:
  - `:asc`
  - `:desc`

* `:tag_group_id` (`t:atom/0`) - Tag group filter. Supported values are:
  - `:freq` - Frequency
  - `:gen` - General or Concept
  - `:geo` - Geography
  - `:geot` - Geography Type
  - `:rls` - Release
  - `:seas` - Seasonal Adjustment
  - `:src` - Source

* `:tag_names` (list of `t:String.t/0`) - List of tag names to match.

## Examples

    iex> {:ok, tags} = Fred.Categories.tags(125, tag_group_id: :freq)
    iex> %{"tags" => [_ | _]} = tags

---

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