fetch-market-data

fetch-market-data Skill

CLI tool that returns stock market data as JSON. Supports US equities (e.g. AAPL) and Japanese equities (e.g. 7203.T). Data is sourced from Yahoo Finance via yfinance.

Prerequisites

uv must be installed. Run which uv to verify.

Command Syntax

uvx --from git+https://github.com/Trippy3/fetch_market_data fetch-market-data SYMBOL [SYMBOL ...] [OPTIONS]

Multiple symbols and multiple metric flags can be combined in a single call.

Development note: if you have the repository cloned, use uv run fetch-market-data instead of the uvx form above.

Output Format

Always outputs a JSON object to stdout, keyed by ticker symbol:

{
  "AAPL": {
    "price": 213.49,
    "trailing-pe": 32.35,
    "dividend-yield": 0.0046,
    "currency": "USD",
    "error": null
  },
  "7203.T": {
    "price": 3255.0,
    "trailing-pe": 11.46,
    "dividend-yield": 0.0291,
    "currency": "JPY",
    "error": null
  }
}

• currency: always present — "USD" for US stocks, "JPY" for Japanese stocks (.T suffix)
• error: null on success; error message string if the ticker failed entirely
• metric fields: numeric value, or null if unavailable for that ticker
• numeric values are rounded to 4 decimal places

Unit Conventions

Critical: ratio/percentage metrics are returned as decimals, not percentages.

Metric	Unit	Example	Meaning
price-change-pct	decimal	0.0312	+3.12%
weekly-change	decimal	-0.0215	-2.15%
monthly-change	decimal	0.0841	+8.41%
dividend-yield	decimal	0.0046	0.46%
operating-margin	decimal	0.2973	29.73%
gross-margin	decimal	0.4563	45.63%
equity-ratio	decimal	0.3120	31.20%
fcf-margin	decimal	0.2241	22.41%
revenue-growth	decimal	0.0623	+6.23% YoY
dividend-growth	decimal	0.0400	+4.00% YoY
roe / roa	decimal	1.4732	147.32%
price, market-cap, revenue, etc.	absolute	213.49	currency units
buyback	absolute, usually negative	-89000000000	cash outflow

Available Metric Categories

Full option list with descriptions: See references/metrics-reference.md. The analysis patterns below cover common use cases only — not all 48 options are shown.

Category	Key options
Price & Market	--price --price-change --price-change-pct --weekly-change --monthly-change --week52-high --week52-low --volume --avg-volume --market-cap
Valuation	--trailing-pe --forward-pe --pbr --psr --peg --ev-ebitda --dividend-yield --payout-ratio
Income Statement	--revenue --revenue-growth --operating-income --operating-margin --gross-margin --net-income --trailing-eps --forward-eps
Balance Sheet	--cash --goodwill --intangible-assets --equity-ratio --debt-ebitda
Cash Flow	--operating-cf --fcf --fcf-margin --buyback
Profitability & Risk	--roe --roa --beta
Shareholder Returns	--dividend-history --dividend-growth --total-return-ratio
Analyst	--price-target --ratings --eps-estimate --revenue-estimate
Events	--next-earnings --guidance
Insider	--insider-trades --major-holders

Analysis Patterns

All examples use the full uvx invocation. Replace uvx --from git+https://github.com/Trippy3/fetch_market_data fetch-market-data with uv run fetch-market-data if running from the cloned repository.

Valuation check

uvx --from git+https://github.com/Trippy3/fetch_market_data fetch-market-data AAPL MSFT \
  --price --trailing-pe --forward-pe --pbr --peg --ev-ebitda

Dividend income evaluation

uvx --from git+https://github.com/Trippy3/fetch_market_data fetch-market-data 7203.T 6758.T \
  --price --dividend-yield --payout-ratio --dividend-growth

Growth quality

uvx --from git+https://github.com/Trippy3/fetch_market_data fetch-market-data NVDA AMZN \
  --revenue-growth --operating-margin --gross-margin --fcf-margin

Financial health

uvx --from git+https://github.com/Trippy3/fetch_market_data fetch-market-data 9984.T \
  --equity-ratio --debt-ebitda --cash --operating-cf

Shareholder returns

uvx --from git+https://github.com/Trippy3/fetch_market_data fetch-market-data AAPL \
  --buyback --dividend-history --total-return-ratio --payout-ratio

Analyst consensus

uvx --from git+https://github.com/Trippy3/fetch_market_data fetch-market-data TSLA \
  --price-target --ratings --eps-estimate --revenue-estimate

Upcoming events

uvx --from git+https://github.com/Trippy3/fetch_market_data fetch-market-data AAPL \
  --next-earnings --guidance

Compare US + Japan

uvx --from git+https://github.com/Trippy3/fetch_market_data fetch-market-data AAPL 6758.T \
  --price --trailing-pe --pbr --roe --dividend-yield

Balance sheet & M&A risk

uvx --from git+https://github.com/Trippy3/fetch_market_data fetch-market-data GENDA 4385.T \
  --goodwill --intangible-assets --equity-ratio --debt-ebitda --cash

Market context

uvx --from git+https://github.com/Trippy3/fetch_market_data fetch-market-data AAPL MSFT \
  --price --week52-high --week52-low --volume --avg-volume --beta

Error Handling

Situation	What you see	Action
Invalid ticker	"error": "Ticker not found"	Check symbol; add .T for Japanese stocks
Data unavailable	metric is null, "error": null	Normal — not all metrics exist for all tickers
Source fetch failed	metric is null, "error": "..."	Transient network issue; retry
Japanese stocks missing analyst data	null on --ratings, --price-target, etc.	Expected — Yahoo Finance analyst coverage is US-centric

[warn] lines on stderr are informational and do not affect JSON output.

Structured Metrics

Some metrics return nested JSON instead of a scalar:

• --dividend-history → {"2023-12-15T00:00:00": 0.24, ...} (date → amount)
• --ratings → [{"strongBuy": 28, "buy": 12, ...}]
• --guidance → full calendar dict including revenue/EPS estimates
• --eps-estimate / --revenue-estimate → list of analyst estimate records
• --price-target → {"current": 240.0, "low": 180.0, "mean": 255.0, "high": 320.0}
• --insider-trades / --major-holders → list of records

Supported Markets

Market	Format	Example
US equities	Symbol as-is	AAPL, MSFT, NVDA
Japanese equities	Code + .T	7203.T, 6758.T, 9984.T

Full Metrics Reference

See references/metrics-reference.md for the complete list of all 48 supported options with descriptions, return types, and source speed.