YahooFinanceEx (YahooFinanceEx v0.2.0)

Elixir client for Yahoo! Finance.

v0.2 surface:

get_quote/1 — single-symbol quote.
get_quotes/1 — batched quote fetch (up to 50 symbols per HTTP call; this function transparently batches larger lists).
get_fx_rate/2 — current FX rate between two ISO 4217 currency codes via Yahoo's <FROM><TO>=X quote symbol.

All paths go through YahooFinanceEx.Session to handle the cookie + CSRF crumb auth dance, and through Req for HTTP — so tests can stub the whole thing with Req.Test.

Dividend history, symbol search, and an in-memory cache layer are planned follow-ups.

Quickstart

{:ok, quote} = YahooFinanceEx.get_quote("AAPL")

{:ok, by_symbol} = YahooFinanceEx.get_quotes(["AAPL", "MSFT", "GOOG"])
by_symbol["AAPL"]
#=> {:ok, %YahooFinanceEx.Quote{symbol: "AAPL", ...}}

{:ok, rate} = YahooFinanceEx.get_fx_rate("EUR", "USD")
#=> {:ok, 1.08}

Notes

Yahoo's API is unofficial. Endpoints, auth requirements, and response shapes can change without notice. Two auth strategies are tried in order before erroring; sessions live for 60 seconds before being re-fetched.

Summary

Types

error()

Errors returned by the public functions.

per_symbol_result()

Per-symbol result inside a batched get_quotes/1 response.

Functions

get_fx_rate(currency, currency)

Fetches the current FX rate between two ISO 4217 currency codes — one unit of from expressed in to.

get_quote(symbol)

Fetches a single stock quote.

get_quotes(symbols)

Fetches quotes for many symbols in one or more batched HTTP calls.

Types

error()

@type error() ::
  {:auth_failed, term()}
  | {:http_status, non_neg_integer()}
  | {:transport, term()}
  | :not_found

Errors returned by the public functions.

per_symbol_result()

@type per_symbol_result() :: {:ok, YahooFinanceEx.Quote.t()} | {:error, :not_found}

Per-symbol result inside a batched get_quotes/1 response.

Functions

get_fx_rate(currency, currency)

@spec get_fx_rate(String.t(), String.t()) :: {:ok, float()} | {:error, error()}

Fetches the current FX rate between two ISO 4217 currency codes — one unit of from expressed in to.

Returns {:ok, 1.0} for identity pairs without hitting the API. Returns {:ok, rate} (a float) on success, or {:error, reason} on failure (including :not_found when Yahoo has no quote for the pair).

get_quote(symbol)

@spec get_quote(String.t()) :: {:ok, YahooFinanceEx.Quote.t()} | {:error, error()}

Fetches a single stock quote.

Returns {:ok, %YahooFinanceEx.Quote{}} on success, or {:error, reason} with one of the error/0 shapes on failure.

Retries once on transient auth errors (Yahoo invalidates sessions occasionally); deeper failures bubble up.

get_quotes(symbols)

@spec get_quotes([String.t()]) ::
  {:ok, %{required(String.t()) => per_symbol_result()}} | {:error, error()}

Fetches quotes for many symbols in one or more batched HTTP calls.

Returns {:ok, results_map} where results_map is %{symbol => {:ok, Quote.t()} | {:error, :not_found}} — i.e. each requested symbol is present in the map, mapped to its individual result. Symbols Yahoo doesn't recognize come back as {:error, :not_found}.

Top-level errors ({:auth_failed, _}, {:transport, _}, etc.) abort the whole call and are returned as {:error, reason}.

Symbols are batched in groups of 50 (Yahoo's per-request ceiling). Duplicates and empty lists are tolerated.