yfscreen: Yahoo Finance Screener in R and Python

Open Source Quantitative Finance 2025

Overview

yfscreen is a package that provides simple and efficient access to Yahoo Finance’s screener API (https://finance.yahoo.com/research-hub/screener/) for querying and retrieval of financial data.

The core functionality of the yfscreen package abstracts the complexities of interacting with Yahoo Finance APIs, such as session management, crumb and cookie handling, query construction, pagination, and JSON payload generation. This abstraction allows users to focus on filtering and retrieving data rather than managing API details. Use cases include screens across a range of security types:

• Equities: coverage spans 50 regions to enable the identification of top-performing stocks based on specified criteria
• Mutual funds: funds can be screened using metrics such as historical performance, performance ratings, and other factors
• ETFs: a wide range of ETFs can be filtered by criteria including expense ratio, historical performance, and additional attributes
• Indices: stock market indices are available and often categorized by sector, industry, or the overall market
• Futures: futures contracts can be screened by exchange, price percent changes, and regional specifications

The package supports advanced query capabilities, including logical operators, nested filters, and customizable payloads. It automatically handles pagination for efficient retrieval of large datasets by fetching results in batches of up to 250 entries per request. Filters can be dynamically defined to accommodate a wide range of screen needs.

The implementation leverages standard HTTP libraries to handle API interactions efficiently and provides support for both R and Python to make it accessible for a broad audience.

Installation in R

• Install the released version from CRAN:

install.packages("yfscreen")

• Or the development version from GitHub:

# install.packages("devtools")
devtools::install_github("jasonjfoster/screen/r")

• Then load the package:

library(yfscreen)

Installation in Python

• Install the released version from PyPI:

pip install yfscreen

• Or the development version from GitHub:

pip install \
  git+https://github.com/jasonjfoster/screen.git@main#subdirectory=python

• Then import the package:

import yfscreen as yfs

Available filters

Load the package and explore the available filter options using yfscreen::data_filters in R or yfs.data_filters in Python:

Usage

Create query

The yfs::create_query function in R and yfs.create_query method in Python create a structured query with logical operations and nested conditions formatted for the Yahoo Finance API.

Parameters

• filters: list. Each element is a sublist that defines a filtering condition with the following structure:
  • comparison: string. Comparison operator (i.e., “gt”, “lt”, “eq”, “btwn”).
  • field: list. Field name (e.g. “region”) and its associated value(s).
• top_operator: string. Top-level logical operator to combine all filters (i.e., “and”, “or”).

Value

A nested list representing the structured query with logical operations and nested conditions formatted for the Yahoo Finance API.

Examples

• Most active stocks: discover the most traded equities in the trading day.

R

most_actives <- list(
  list("eq", list("region", "us")),
  list("btwn", list("intradaymarketcap", 2e9, 1e11)),
  list("gt", list("dayvolume", 5e6))
)
query <- yfscreen::create_query(most_actives)

Python

most_actives = [
  ["eq", ["region", "us"]],
  ["btwn", ["intradaymarketcap", 2e9, 1e11]],
  ["gt", ["dayvolume", 5e6]]
]
query = yfs.create_query(most_actives)

Get data

The yfs::get_data function in R and yfs.get_data method in Python get data from the Yahoo Finance API using the specified payload.

Parameters

• payload: list. Payload that contains search criteria created using create_query() and create_payload().

Value

A data frame that contains data from the Yahoo Finance API for the specified search criteria.

Examples

R

payload <- yfscreen::create_payload("equity", query)
data <- yfscreen::get_data(payload)

Python

payload = yfs.create_payload("equity", query)
data = yfs.get_data(payload)

View data

R

head(data[ , c("symbol", "regularMarketPrice.raw",
               "regularMarketChangePercent.raw", ...)])

Python

data[["symbol", "regularMarketPrice.raw",
      "regularMarketChangePercent.raw", ...]].head()

More filters in R

• Undervalued growth stocks: equities with earnings growth above 25% and relatively low P/E and PEG ratios.

sec_type <- "equity"
undervalued_growth_stocks <- list(
  list("btwn", list("peratio.lasttwelvemonths", 0, 20)),
  list("lt", list("pegratio_5y", 1)),
  list("gt", list("epsgrowth.lasttwelvemonths", 25))
)

• Top mutual funds: mutual funds with a performance rating of 4 or 5.

sec_type <- "mutualfund"
top_mutual_funds <- list(
  list("gt", list("intradayprice", 15)),
  list("eq", list("performanceratingoverall", 4)),
  list("eq", list("performanceratingoverall", 5))
)

More filters in Python

• Day gainer stocks: equities with the largest gains during the trading day.

sec_type = "equity"
day_gainers = [
  ["gt", ["percentchange", 3]],
  ["gt", ["intradaymarketcap", 2e9]],
  ["gt", ["intradayprice", 5]],
  ["gt", ["dayvolume", 1.5e3]]
]

• Day loser stocks: equities with the largest losses during the trading day.

day_losers = [
  ["lt", ["percentchange", -2.5]],
  ["gt", ["intradaymarketcap", 2e9]],
  ["gt", ["intradayprice", 5]],
  ["gt", ["dayvolume", 2e3]]
]

Application

Next we use the yfscreen package to analyze how positioning influenced recent performance among “Tactical Allocation” mutual funds with the “categoryname” field to define the peer group. To estimate asset allocations, we use a constrained least squares regression with two explanatory variables: the S&P 500 Index (SP500) to represent market exposure and the 3-month Treasury bill rate (DTB3) to represent cash. The objective is to estimate how each mutual fund allocates between market and cash exposures subject to the following constraints:

The sum-to-one constraint ensures that the entire portfolio is allocated between market and cash positions without leverage. The positive bounds reflect the typical long-only structure of mutual funds.

Results

After the estimation of market and cash exposures, we separate mutual funds into performance quartiles and compare positioning over time. The chart below shows the regression-based market and cash split for the top (Q1) and bottom (Q4) performing “Tactical Allocation” managers since the U.S. election in November 2024. The analysis provides insight into how tactical shifts, such as increasing cash allocations or maintaining higher market exposure, contributed to differences in recent mutual fund performance.

Data source: Federal Reserve Economic Data (FRED): https://fred.stlouisfed.org/; Yahoo Finance API: https://finance.yahoo.com/

The results show that Q1 managers shifted allocations into cash at the end of February and de-risked ahead of subsequent market volatility. In contrast, Q4 managers maintained higher market exposure that contributed to underperformance over the same period. By comparing estimated exposures across quartiles, the analysis provides a regression-based approach for understanding how tactical allocation decisions, specifically the market versus cash split, affected recent performance.

Conclusion

The yfscreen package provides simple and efficient access to Yahoo Finance’s screener API for querying and retrieving financial data. It abstracts the complexities of session management, query construction, pagination, and payload generation. This allows users to focus on filtering and retrieving data across a range of security types, including equities, mutual funds, ETFs, indices, and futures. The package supports advanced query capabilities, such as logical operators, nested filters, and customizable payloads, and automatically handles pagination to retrieve large datasets efficiently. It is available for both R and Python to make it accessible for a broad audience. The analysis of tactical allocation mutual funds illustrates how the package can be used to estimate asset exposures and interpret positioning differences across managers. For more examples and analysis in R and Python, go to https://jasonjfoster.github.io/.