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

Functions for the FRED Tags endpoints.

FRED tags are attributes assigned to series. Tags provide an alternative way
to find and filter series beyond categories.

## Endpoints

  - [`list/1`] - [`fred/tags`](https://fred.stlouisfed.org/docs/api/fred/tags.html) - Get all tags
  - [`related/2`] - [`fred/related_tags`](https://fred.stlouisfed.org/docs/api/fred/related_tags.html) - Get related tags
  - [`series/2`] - [`fred/tags/series`](https://fred.stlouisfed.org/docs/api/fred/tags_series.html) - Get series matching tags

# `list`

```elixir
@spec list(opts :: keyword()) :: Fred.Client.response()
```

Get FRED tags, optionally filtered by tag name, group, or search text.

## Options

  * `: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.Tags.list(order_by: :popularity, sort_order: :desc, limit: 10)
    iex> %{"tags" => [_ | _]} = tags

    iex> {:ok, tags} = Fred.Tags.list(order_by: :name, limit: 10)
    iex> %{"tags" => [_ | _]} = tags

    iex> {:ok, tags} = Fred.Tags.list(search_text: "inflation")
    iex> %{"tags" => [_ | _]} = tags

    iex> {:error, %Fred.Error{type: :option_error}} =
    ...>   Fred.Tags.list(limit: 20, realtime_start: "Bad Input")

# `related`

```elixir
@spec related(tag_names :: String.t(), opts :: keyword()) :: Fred.Client.response()
```

Get the related FRED tags for one or more tags.

Related tags are tags assigned to series that match all tags in the `:tag_names`
parameter, excluding the tags themselves.

## Options

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

* `: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

## Examples

    iex> {:ok, tags} = Fred.Tags.related(["monetary aggregates", "m1"])
    iex> %{"tags" => [_ | _]} = tags

    iex> {:error, %Fred.Error{type: :option_error}} =
    ...>   Fred.Tags.related(["monetary aggregates", "m1"], limit: 20, realtime_start: "Bad Input")

# `series`

```elixir
@spec series(tag_names :: [String.t(), ...], opts :: keyword()) ::
  Fred.Client.response()
```

Get the series matching all tags in the `:tag_names` parameter.

## Options

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

* `: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`

## Examples

    iex> {:ok, series} = Fred.Tags.series(["slovenia", "food", "oecd"], limit: 10)
    iex> %{"seriess" => [_ | _]} = series

    iex> {:error, %Fred.Error{type: :option_error}} =
    ...>   Fred.Tags.series(["slovenia", "food", "oecd"], limit: 20, realtime_start: "Bad Input")

---

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