The Financial data from Yahoo!

Data Usage Instructions

Use DuckDB or Python API or Terminal or AI Agents, including Claude Desktop, Manus, Codex, Hermes Agent, OpenClaw Agent, and others, to access data.

When using defeatbeta-api, version 0.0.61 or later is required. Earlier versions use the legacy flat data/ paths and are incompatible with the current market-specific directory layout.

All datasets are publicly accessible. Tabular datasets are stored in Parquet format, while instrument catalogs are stored in JSON format.

Repository Layout

Data is organized by market. The repository currently publishes U.S. market data under data/US/:

data/
└── US/
    ├── company_tickers.json
    ├── stock_prices.parquet
    ├── stock_profile.parquet
    └── ...
spec.json

• data/US/company_tickers.json is the U.S. instrument catalog. Each record contains the SEC CIK, ticker symbol, company name, and financial reporting currency.
• data/US/*.parquet contains the U.S. market datasets described below.
• spec.json remains at the repository root. Its files and hashes keys use market-relative paths such as US/stock_prices.parquet.
• Prices for securities listed in the US market directory are quoted in USD. The financial_currency field in company_tickers.json is the currency used by the company to report its financial statements and may be different from USD.

When using AI, you can also use skills for enhanced data analysis capabilities.

---

Datasets Overview

1. stock_profile

   • Source: https://finance.yahoo.com/quote/{$symbol}/profile/
   • Description: Contains company details such as address, industry, and employee count.
   • Columns:

     Column Name	Column Type	Description
     symbol	VARCHAR	Stock ticker symbol
     address	VARCHAR	Company address
     city	VARCHAR	City
     country	VARCHAR	Country
     phone	VARCHAR	Phone number
     zip	VARCHAR	Zip code
     industry	VARCHAR	Industry type
     sector	VARCHAR	Business sector
     long_business_summary	VARCHAR	Business summary
     full_time_employees	BIGINT	Number of full-time staff
     web_site	VARCHAR	Company website URL
     report_date	VARCHAR	Data reporting date

2. stock_officers

   • Source: https://finance.yahoo.com/quote/{$symbol}/profile/
   • Description: Lists company executives, including their pay and title.
   • Columns:

     Column Name	Column Type	Description
     symbol	VARCHAR	Stock ticker symbol
     name	VARCHAR	Executive's name
     title	VARCHAR	Executive's job title
     age	BIGINT	Executive's age
     born	BIGINT	Year of birth
     pay	BIGINT	Wage (USD)
     exercised	BIGINT	Stock options exercised
     unexercised	BIGINT	Unexercised stock options
     report_date	VARCHAR	Data reporting date

3. stock_tailing_eps

   • Source: https://ycharts.com/companies/${symbol}/eps_ttm
   • Description: Provides financial metrics such as Trailing earnings per share (TTM EPS).
   • Columns:

     Column Name	Column Type	Description
     symbol	VARCHAR	Stock ticker symbol
     report_date	VARCHAR	Reporting date
     eps	DECIMAL(16,4)	Earnings per share
     tailing_eps	DECIMAL(16,4)	Trailing EPS (TTM)
     update_time	VARCHAR	Last update time

4. stock_earning_calendar

   • Source: https://www.nasdaq.com/market-activity/earnings
   • Description: Contains information about companies' earnings reports, including their ticker symbols, reporting dates, names, and fiscal quarter end dates.
   • Columns:

     Column Name	Column Type	Description
     symbol	VARCHAR	Stock ticker symbol
     report_date	VARCHAR	Reporting date
     name	VARCHAR	Company Simple Name
     fiscal_quarter_ending	VARCHAR	Fiscal quarter end date

5. stock_statement

   • Source: https://finance.yahoo.com/quote/${symbol}/financials/
   • Description: Contains financial statement details of companies, including ticker symbols, reporting dates, specific financial items, their values, and related statement types and periods.
   • Columns:

     Column Name	Column Type	Description
     symbol	VARCHAR	Stock ticker symbol
     report_date	VARCHAR	Reporting date
     item_name	VARCHAR	Name of the financial statement item
     item_value	DECIMAL(38,2)	Value of the financial statement item
     finance_type	VARCHAR	Type of financial statement (e.g., balance_sheet, income_statement, cash_flow)
     period_type	VARCHAR	Reporting period type (e.g., annual, quarterly)

6. stock_prices

   • Source: https://finance.yahoo.com/quote/${symbol}/chart
   • Description: Contains historical stock market data, including ticker symbols, reporting dates, and key trading metrics such as open, close, high, low prices, and trading volume.
   • Columns:

     Column Name	Column Type	Description
     symbol	VARCHAR	Stock ticker symbol
     report_date	VARCHAR	Trading date
     open	DECIMAL(16,4)	Opening price of the stock
     close	DECIMAL(16,4)	Closing price of the stock
     high	DECIMAL(16,4)	Highest price
     low	DECIMAL(16,4)	Lowest price
     volume	BIGINT	Number of shares traded

7. stock_dividend_events

   • Source: https://finance.yahoo.com/quote/${symbol}/chart
   • Description: Contains dividend data, including stock tickers, reporting dates, and dividend values.
   • Columns:

     Column Name	Column Type	Description
     symbol	VARCHAR	Stock ticker symbol
     report_date	VARCHAR	Reporting date
     amount	DECIMAL(20,4)	Dividend amount

8. stock_split_events

   • Source: https://finance.yahoo.com/quote/${symbol}/chart
   • Description: Contains data about stock splits, including the stock ticker, reporting date, and the split factor.
   • Columns:
     | Column Name | Column Type | Description |
     |---------------|---------------|----------------------------------|
     | symbol | VARCHAR | Stock ticker symbol |
     | report_date | VARCHAR | Reporting date |
     | split_factor | VARCHAR | The factor by which shares are split |

9. exchange_rate

   • Source: https://finance.yahoo.com/quote/${symbol}/chart
   • Description: Contains currency exchange data for a report date, including opening, closing, highest, and lowest prices.
   • Columns:
     | Column Name | Column Type | Description |
     |---------------|---------------|----------------------------------|
     | symbol | VARCHAR | Stock ticker symbol |
     | report_date | VARCHAR | Reporting date |
     | open | DECIMAL(16,4) | Opening price |
     | close | DECIMAL(16,4) | Closing price |
     | high | DECIMAL(16,4) | Highest price during the day |
     | low | DECIMAL(16,4) | Lowest price during the day |

10. daily_treasury_yield

    • Source: https://home.treasury.gov/
    • Description: Contains data related to daily treasury yield values for different time periods (monthly and yearly).
    • Columns:
      | Column Name | Column Type | Description |
      |---------------|---------------|------------------------------------|
      | report_date | VARCHAR | Reporting date |
      | bc_1month | DECIMAL(16,4) | Treasury yield for 1 month |
      | bc_2month | DECIMAL(16,4) | Treasury yield for 2 months |
      | bc_3month | DECIMAL(16,4) | Treasury yield for 3 months |
      | bc_6month | DECIMAL(16,4) | Treasury yield for 6 months |
      | bc_1year | DECIMAL(16,4) | Treasury yield for 1 year |
      | bc_2year | DECIMAL(16,4) | Treasury yield for 2 years |
      | bc_3year | DECIMAL(16,4) | Treasury yield for 3 years |
      | bc_5year | DECIMAL(16,4) | Treasury yield for 5 years |
      | bc_7year | DECIMAL(16,4) | Treasury yield for 7 years |
      | bc_10year | DECIMAL(16,4) | Treasury yield for 10 years |
      | bc_20year | DECIMAL(16,4) | Treasury yield for 20 years |
      | bc_30year | DECIMAL(16,4) | Treasury yield for 30 years |

11. stock_earning_call_transcripts

    • Source: https://finance.yahoo.com/quote/{symbol}/earnings-calls/
    • Description: Contains verbatim transcripts of quarterly earnings calls for publicly traded companies, including speaker information and content segmentation.
    • Columns:

      Column Name	Data Type	Description
      symbol	VARCHAR	The stock ticker symbol of the company
      fiscal_year	INTEGER	The fiscal year of the earnings call
      fiscal_quarter	INTEGER	The fiscal quarter (1-4) of the earnings call
      report_date	VARCHAR	The date when the earnings call was reported (format may vary)
      transcripts	STRUCT<paragraph_number: INTEGER, speaker: VARCHAR, content: VARCHAR>[]	Array of structured transcript segments: paragraph_number: Sequential numbering of transcript paragraphs, speaker: Name and/or title of the speaker,content: The actual spoken content/text
      transcripts_id	INTEGER	Unique identifier for the transcript record

12. stock_news

    • Source: https://news.yahoo.com/
    • Description: Stores information about financial research reports or news articles, including metadata and content details
    • Columns:

      Column Name	Data Type	Description
      uuid	VARCHAR	Unique identifier for the report/article (nullable)
      symbol	VARCHAR	stock ticker
      title	VARCHAR	Title of the report/article (nullable)
      publisher	VARCHAR	Organization or entity that published the report (nullable)
      report_date	VARCHAR	Date when the report was published (stored as string, nullable)
      type	VARCHAR	Classification or category of the report/article (nullable)
      link	VARCHAR	URL or reference link to the original content (nullable)
      news	STRUCT<paragraph_number: INTEGER, highlight: VARCHAR, paragraph: VARCHAR>[]	Array of structured paragraphs containing content with numbering, highlights, and text (nullable)

13. stock_revenue_breakdown

    • Source: https://stockanalysis.com/stocks/${symbol}/metrics/
    • Description: Per-company breakdown metrics covering revenue by segment, operating income by segment, operating expense breakdown, and a long tail of business KPIs (store counts, aircraft deliveries, paid memberships, oil production volumes, etc.) — whichever pages stockanalysis.com publishes for that ticker. The set of breakdown slugs varies per company: NVDA also has data-center-revenue-breakdown, OXY has production-by-geography, PLTR has deals-closed-by-size, etc. Each row is one data point: one series in one period.
    • Columns:

      Column Name	Data Type	Description
      symbol	VARCHAR	Stock ticker symbol
      breakdown	VARCHAR	Breakdown slug (e.g. revenue-by-segment, operating-income-by-segment, operating-expense-breakdown)
      breakdown_name	VARCHAR	Human-readable breakdown name (e.g. Revenue by Segment)
      value_type	VARCHAR	CURRENCY (monetary value) or NUMBER (count / volume — units implied by breakdown_name)
      currency	VARCHAR	ISO 4217 reporting currency for CURRENCY rows (e.g. USD, CNY, EUR, TWD); NULL for NUMBER rows
      series_name	VARCHAR	Series within the breakdown (e.g. Data Center, Europe, Over $1 Million)
      period_type	VARCHAR	quarterly (single period) or trailing (TTM rolling)
      report_date	VARCHAR	Period end date
      value	BIGINT	Raw value in base units (full dollars / cents-free count, not in millions)

14. stock_shares_outstanding

    • Source: https://ycharts.com/companies/${symbol}/shares_outstanding
    • Description: Provides Shares Outstanding.
    • Columns:

      Column Name	Column Type	Description
      symbol	VARCHAR	Stock ticker symbol
      report_date	VARCHAR	Reporting date
      shares_outstanding	Long	Shares Outstanding

15. stock_sec_filing

    • Source: https://www.sec.gov/cgi-bin/browse-edgar
    • Description: Contains SEC (U.S. Securities and Exchange Commission) filing records for publicly traded companies. Supported form types include:
      • US Domestic Company Forms:
        • 10-K, 10-K/A - Annual report
        • 10-Q, 10-Q/A - Quarterly report
        • 8-K, 8-K/A - Current report (material events)
        • DEF 14A, DEFA14A - Proxy statement (shareholder meetings, executive compensation)
      • Insider Trading Forms:
        • 3, 3/A - Initial beneficial ownership
        • 4, 4/A - Changes in beneficial ownership
        • 5, 5/A - Annual beneficial ownership
        • 144, 144/A - Notice of proposed sale of securities
      • Institutional Holdings:
        • 13F-HR, 13F-HR/A - Institutional holdings report (quarterly)
        • SC 13G, SC 13G/A - Passive investor holdings (>5%)
        • SC 13D, SC 13D/A - Active investor holdings (>5%, may influence company)
      • Foreign Private Issuer Forms (e.g., BABA, PDD, JD):
        • 20-F, 20-F/A - Annual report
        • 6-K, 6-K/A - Current report (quarterly + material events)
      • Canadian Company Forms (e.g., SHOP, TD, RY):
        • 40-F, 40-F/A - Annual report
      • ETF/Investment Company Forms (e.g., SPY, QQQ, VOO):
        • N-CSR, N-CSR/A - Annual/Semi-annual shareholder report
        • N-CSRS, N-CSRS/A - Semi-annual shareholder report
        • N-30D, N-30D/A - Shareholder report (legacy format)
        • NPORT-P - Monthly portfolio holdings
        • N-CEN - Annual report (fund operations)
        • N-Q, N-Q/A - Quarterly portfolio (discontinued, historical data exists)
    • Columns:

      Column Name	Column Type	Description
      symbol	VARCHAR	Stock ticker symbol
      cik	VARCHAR	Central Index Key - unique SEC identifier for the filer
      accession_number	VARCHAR	Unique identifier for the filing
      company_name	VARCHAR	Official company name as registered with SEC
      form_type	VARCHAR	SEC form type (e.g., 10-K, 10-Q, 8-K, 4, SC 13G)
      form_type_description	VARCHAR	Human-readable description of the form type
      filing_date	VARCHAR	Date when the filing was submitted to SEC
      report_date	VARCHAR	Period end date covered by the filing (if applicable)
      acceptance_date_time	VARCHAR	Timestamp when SEC accepted the filing
      filing_url	VARCHAR	Direct URL to the filing on SEC EDGAR

Querying Datasets

Use the following SQL queries in DuckDB to retrieve data for a specific stock (e.g., TSLA):

1. stock_profile

   SELECT * FROM 
       'https://huggingface.co/datasets/defeatbeta/yahoo-finance-data/resolve/main/data/US/stock_profile.parquet'
   WHERE symbol='TSLA';
   

2. stock_officers

   SELECT * FROM 
       'https://huggingface.co/datasets/defeatbeta/yahoo-finance-data/resolve/main/data/US/stock_officers.parquet'
   WHERE symbol='TSLA';
   

3. stock_tailing_eps

   SELECT * FROM 
       'https://huggingface.co/datasets/defeatbeta/yahoo-finance-data/resolve/main/data/US/stock_tailing_eps.parquet'
   WHERE symbol='TSLA';
   

4. stock_earning_calendar

   SELECT * FROM
       'https://huggingface.co/datasets/defeatbeta/yahoo-finance-data/resolve/main/data/US/stock_earning_calendar.parquet'
   WHERE symbol='TSLA';
   

5. stock_statement

   SELECT * FROM 
       'https://huggingface.co/datasets/defeatbeta/yahoo-finance-data/resolve/main/data/US/stock_statement.parquet'
   WHERE symbol='TSLA' and finance_type='income_statement'
   

6. stock_prices

   SELECT * FROM 
       'https://huggingface.co/datasets/defeatbeta/yahoo-finance-data/resolve/main/data/US/stock_prices.parquet'
   WHERE symbol='TSLA'
   

7. stock_dividend_events

   SELECT * FROM 
       'https://huggingface.co/datasets/defeatbeta/yahoo-finance-data/resolve/main/data/US/stock_dividend_events.parquet'
   WHERE symbol='TSLA'
   

8. stock_split_events

   SELECT * FROM 
       'https://huggingface.co/datasets/defeatbeta/yahoo-finance-data/resolve/main/data/US/stock_split_events.parquet'
   WHERE symbol='TSLA'
   

9. exchange_rate

   SELECT * FROM 
       'https://huggingface.co/datasets/defeatbeta/yahoo-finance-data/resolve/main/data/US/exchange_rate.parquet'
   WHERE symbol='EUR=X'
   

10. daily_treasury_yield

    SELECT * FROM 
        'https://huggingface.co/datasets/defeatbeta/yahoo-finance-data/resolve/main/data/US/daily_treasury_yield.parquet'
    

11. stock_earning_call_transcripts

    SELECT symbol,
        fiscal_year,
        fiscal_quarter,
        report_date,
        unnest(transcripts).paragraph_number,
        unnest(transcripts).speaker,
        unnest(transcripts).content 
    FROM 'https://huggingface.co/datasets/defeatbeta/yahoo-finance-data/resolve/main/data/US/stock_earning_call_transcripts.parquet'
    WHERE symbol='TSLA' AND fiscal_year=2024 AND fiscal_quarter=4;
    

12. stock_news

    SELECT symbol, 
        uuid, 
        title, 
        publisher, 
        report_date, 
        type, 
        link, 
        unnest(news).paragraph_number, 
        unnest(news).highlight, 
        unnest(news).paragraph 
    FROM 'https://huggingface.co/datasets/defeatbeta/yahoo-finance-data/resolve/main/data/US/stock_news.parquet'
    WHERE symbol='TSLA'
    AND uuid='621f7c6a-b7d0-3532-b28c-65cb360c99ab';
    

13. stock_revenue_breakdown

    List every breakdown a company exposes:

    SELECT DISTINCT breakdown, breakdown_name, value_type, currency
    FROM 'https://huggingface.co/datasets/defeatbeta/yahoo-finance-data/resolve/main/data/US/stock_revenue_breakdown.parquet'
    WHERE symbol='NVDA';
    

    Quarterly time series for one breakdown (long format):

    SELECT report_date, series_name, value
    FROM 'https://huggingface.co/datasets/defeatbeta/yahoo-finance-data/resolve/main/data/US/stock_revenue_breakdown.parquet'
    WHERE symbol='NVDA'
      AND breakdown='revenue-by-segment'
      AND period_type='quarterly'
    ORDER BY report_date DESC, series_name;
    

    Pivot to one row per date with each series as a column (DuckDB-style):

    PIVOT (
      SELECT report_date, series_name, value
      FROM 'https://huggingface.co/datasets/defeatbeta/yahoo-finance-data/resolve/main/data/US/stock_revenue_breakdown.parquet'
      WHERE symbol='PLTR'
        AND breakdown='deals-closed-by-size'
        AND period_type='quarterly'
    ) ON series_name USING first(value)
    ORDER BY report_date DESC;
    

14. stock_shares_outstanding

SELECT * FROM
    'https://huggingface.co/datasets/defeatbeta/yahoo-finance-data/resolve/main/data/US/stock_shares_outstanding.parquet'
WHERE symbol='TSLA';

15. stock_sec_filing

SELECT * FROM
    'https://huggingface.co/datasets/defeatbeta/yahoo-finance-data/resolve/main/data/US/stock_sec_filing.parquet'
WHERE symbol='TSLA' AND form_type='10-K';