value-dividend-screener

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Value Dividend Screener

价值股息筛选工具

Overview

概述

This skill identifies high-quality dividend stocks that combine value characteristics, attractive income generation, and consistent growth using a two-stage screening approach:

FINVIZ Elite API (Optional but Recommended): Pre-screen stocks with basic criteria (fast, cost-effective)
Financial Modeling Prep (FMP) API: Detailed fundamental analysis of candidates

Screen US equities based on quantitative criteria including valuation ratios, dividend metrics, financial health, and profitability. Generate comprehensive reports ranking stocks by composite quality scores with detailed fundamental analysis.

Efficiency Advantage: Using FINVIZ pre-screening can reduce FMP API calls by 90%, making this approach ideal for free-tier API users.

本Skill采用两阶段筛选法，识别兼具价值特征、可观收益能力与持续增长性的高质量股息股票：

FINVIZ Elite API（可选但推荐）：通过基础条件快速预筛选股票（高效、低成本）
Financial Modeling Prep (FMP) API：对候选标的进行详细基本面分析

基于估值比率、股息指标、财务健康度及盈利能力等量化标准筛选美股，生成综合质量评分排名的详尽报告，并附带详细基本面分析。

效率优势：通过FINVIZ预筛选可减少90%的FMP API调用量，非常适合免费版API用户。

When to Use

适用场景

Invoke this skill when the user requests:

"Find high-quality dividend stocks"
"Screen for value dividend opportunities"
"Show me stocks with strong dividend growth"
"Find income stocks trading at reasonable valuations"
"Screen for sustainable high-yield stocks"
Any request combining dividend yield, valuation metrics, and fundamental analysis

当用户提出以下请求时调用本Skill：

"寻找高质量股息股票"
"筛选价值型股息标的"
"展示股息持续增长的股票"
"寻找估值合理的收益型股票"
"筛选可持续高股息股票"
任何结合股息收益率、估值指标与基本面分析的请求

Workflow

操作流程

Step 1: Verify API Key Availability

步骤1：验证API密钥可用性

For Two-Stage Screening (Recommended):

Check if both API keys are available:

python

import os
fmp_api_key = os.environ.get('FMP_API_KEY')
finviz_api_key = os.environ.get('FINVIZ_API_KEY')

If not available, ask user to provide API keys or set environment variables:

bash

export FMP_API_KEY=your_fmp_key_here
export FINVIZ_API_KEY=your_finviz_key_here

For FMP-Only Screening:

Check if FMP API key is available:

python

import os
api_key = os.environ.get('FMP_API_KEY')

If not available, ask user to provide API key or set environment variable:

bash

export FMP_API_KEY=your_key_here

FINVIZ Elite API Key:

Requires FINVIZ Elite subscription (~$40/month or ~$330/year)
Provides access to CSV export of pre-screened results
Highly recommended for reducing FMP API usage

Provide instructions from

references/fmp_api_guide.md

if needed.

推荐采用两阶段筛选：

检查是否同时拥有两个API密钥：

python

import os
fmp_api_key = os.environ.get('FMP_API_KEY')
finviz_api_key = os.environ.get('FINVIZ_API_KEY')

若密钥未配置，请提示用户提供密钥或设置环境变量：

bash

export FMP_API_KEY=your_fmp_key_here
export FINVIZ_API_KEY=your_finviz_key_here

仅使用FMP筛选：

检查是否拥有FMP API密钥：

python

import os
api_key = os.environ.get('FMP_API_KEY')

若密钥未配置，请提示用户提供密钥或设置环境变量：

bash

export FMP_API_KEY=your_key_here

FINVIZ Elite API密钥说明：

需要订阅FINVIZ Elite服务（约40美元/月或330美元/年）
支持导出预筛选结果的CSV文件
强烈推荐使用以减少FMP API调用量

必要时可参考

references/fmp_api_guide.md

中的配置说明。

Step 2: Execute Screening Script

步骤2：执行筛选脚本

Run the screening script with appropriate parameters:

使用合适参数运行筛选脚本：

Two-Stage Screening (RECOMMENDED)

推荐：两阶段筛选

Uses FINVIZ for pre-screening, then FMP for detailed analysis:

Default execution (Top 20 stocks):

bash

python3 scripts/screen_dividend_stocks.py --use-finviz

With explicit API keys:

bash

python3 scripts/screen_dividend_stocks.py --use-finviz \
  --fmp-api-key $FMP_API_KEY \
  --finviz-api-key $FINVIZ_API_KEY

Custom top N:

bash

python3 scripts/screen_dividend_stocks.py --use-finviz --top 50

Custom output location:

bash

python3 scripts/screen_dividend_stocks.py --use-finviz --output /path/to/results.json

Script behavior (Two-Stage):

FINVIZ Elite pre-screening:
- Market cap: Mid-cap or higher
- Dividend yield: 3%+
- Dividend growth (3Y): 5%+
- EPS growth (3Y): Positive
- P/B: Under 2
- P/E: Under 20
- Sales growth (3Y): Positive
- Geography: USA
FMP detailed analysis of FINVIZ results (typically 20-50 stocks):
- Dividend growth rate calculation (3-year CAGR)
- Revenue and EPS trend analysis
- Dividend sustainability assessment (payout ratios, FCF coverage)
- Financial health metrics (debt-to-equity, current ratio)
- Quality scoring (ROE, profit margins)
Composite scoring and ranking
Output top N stocks to JSON file

Expected runtime (Two-Stage): 2-3 minutes for 30-50 FINVIZ candidates (much faster than FMP-only)

先通过FINVIZ预筛选，再用FMP进行详细分析：

默认执行（筛选前20支股票）：

bash

python3 scripts/screen_dividend_stocks.py --use-finviz

指定API密钥执行：

bash

python3 scripts/screen_dividend_stocks.py --use-finviz \
  --fmp-api-key $FMP_API_KEY \
  --finviz-api-key $FINVIZ_API_KEY

自定义筛选数量：

bash

python3 scripts/screen_dividend_stocks.py --use-finviz --top 50

自定义输出路径：

bash

python3 scripts/screen_dividend_stocks.py --use-finviz --output /path/to/results.json

两阶段筛选脚本逻辑：

FINVIZ Elite预筛选：
- 市值：中盘及以上
- 股息收益率：3%+
- 3年股息增长率：5%+
- 3年每股收益增长率：正增长
- 市净率：低于2
- 市盈率：低于20
- 3年营收增长率：正增长
- 地域：美国
对FINVIZ结果进行FMP详细分析（通常20-50支股票）：
- 计算3年股息复合年增长率（CAGR）
- 营收与每股收益趋势分析
- 股息可持续性评估（派息率、自由现金流覆盖率）
- 财务健康指标（债务权益比、流动比率）
- 质量评分（净资产收益率、利润率）
综合评分与排名
将前N支股票输出至JSON文件

两阶段筛选预计耗时：针对30-50支FINVIZ候选标的，耗时2-3分钟（远快于仅使用FMP的方式）

FMP-Only Screening (Original Method)

仅使用FMP筛选（原始方法）

Uses only FMP Stock Screener API (higher API usage):

Default execution:

bash

python3 scripts/screen_dividend_stocks.py

With explicit API key:

bash

python3 scripts/screen_dividend_stocks.py --fmp-api-key $FMP_API_KEY

Script behavior (FMP-Only):

Initial screening using FMP Stock Screener API (dividend yield >=3.0%, P/E <=20, P/B <=2)
Detailed analysis of candidates (typically 100-300 stocks):
- Same detailed analysis as two-stage approach
Composite scoring and ranking
Output top N stocks to JSON file

Expected runtime (FMP-Only): 5-15 minutes for 100-300 candidates (rate limiting applies)

API Usage Comparison:

Two-Stage: ~50-100 FMP API calls (FINVIZ pre-filters to ~30 stocks)
FMP-Only: ~500-1500 FMP API calls (analyzes all screener results)

仅通过FMP股票筛选API实现（API调用量更高）：

默认执行：

bash

python3 scripts/screen_dividend_stocks.py

指定API密钥执行：

bash

python3 scripts/screen_dividend_stocks.py --fmp-api-key $FMP_API_KEY

仅FMP筛选脚本逻辑：

通过FMP股票筛选API初步筛选（股息收益率≥3.0%、市盈率≤20、市净率≤2）
对候选标的进行详细分析（通常100-300支股票）：
- 与两阶段筛选的详细分析内容一致
综合评分与排名
将前N支股票输出至JSON文件

仅FMP筛选预计耗时：针对100-300支候选标的，耗时5-15分钟（受API速率限制影响）

API调用量对比：

两阶段筛选：约50-100次FMP API调用（FINVIZ预筛选至约30支股票）
仅FMP筛选：约500-1500次FMP API调用（分析所有筛选结果）

Step 3: Parse and Analyze Results

步骤3：解析与分析结果

Read the generated JSON file:

python

import json

with open('dividend_screener_results.json', 'r') as f:
    data = json.load(f)

metadata = data['metadata']
stocks = data['stocks']

Key data points per stock:

Basic info:
```
symbol
```
,
```
company_name
```
,
```
sector
```
,
```
market_cap
```
,
```
price
```
Valuation:
```
dividend_yield
```
,
```
pe_ratio
```
,
```
pb_ratio
```

Growth metrics:

dividend_cagr_3y

revenue_cagr_3y

eps_cagr_3y

Sustainability:

payout_ratio

fcf_payout_ratio

dividend_sustainable

Financial health:

debt_to_equity

current_ratio

financially_healthy

Quality:
```
roe
```
,
```
profit_margin
```
,
```
quality_score
```
Overall ranking:
```
composite_score
```

读取生成的JSON文件：

python

import json

with open('dividend_screener_results.json', 'r') as f:
    data = json.load(f)

metadata = data['metadata']
stocks = data['stocks']

单支股票的核心数据项：

基础信息：
```
symbol
```
、
```
company_name
```
、
```
sector
```
、
```
market_cap
```
、
```
price
```
估值指标：
```
dividend_yield
```
、
```
pe_ratio
```
、
```
pb_ratio
```

增长指标：

dividend_cagr_3y

、

revenue_cagr_3y

、

eps_cagr_3y

可持续性：

payout_ratio

、

fcf_payout_ratio

、

dividend_sustainable

财务健康：

debt_to_equity

、

current_ratio

、

financially_healthy

质量指标：
```
roe
```
、
```
profit_margin
```
、
```
quality_score
```
综合排名：
```
composite_score
```

Step 4: Generate Markdown Report

步骤4：生成Markdown报告

Create structured markdown report for user with following sections:

为用户创建结构化Markdown报告，包含以下章节：

Report Structure

报告结构

markdown

undefined

markdown

undefined

Value Dividend Stock Screening Report

价值股息股票筛选报告

Generated: [Timestamp] Screening Criteria:

Dividend Yield: >= 3.5%
P/E Ratio: <= 20
P/B Ratio: <= 2
Dividend Growth (3Y CAGR): >= 5%
Revenue Trend: Positive over 3 years
EPS Trend: Positive over 3 years

Total Results: [N] stocks

生成时间： [时间戳] 筛选标准：

股息收益率：≥ 3.5%
市盈率：≤ 20
市净率：≤ 2
3年股息复合年增长率：≥ 5%
营收趋势：近3年正增长
每股收益趋势：近3年正增长

总结果数： [N]支股票

Top 20 Stocks Ranked by Composite Score

综合评分排名前20支股票

Rank	Symbol	Company	Yield	P/E	Div Growth	Score
1	[TICKER]	[Name]	[%]	[X.X]	[%]	[XX.X]
...

排名	代码	公司名称	收益率	市盈率	股息增长率	综合评分
1	[TICKER]	[名称]	[%]	[X.X]	[%]	[XX.X]
...

Detailed Analysis

详细分析

1. [SYMBOL] - [Company Name] (Score: XX.X)

1. [SYMBOL] - [公司名称]（评分：XX.X）

Sector: [Sector Name] Market Cap: $[X.XX]B Current Price: $[XX.XX]

Valuation Metrics:

Dividend Yield: [X.X]%
P/E Ratio: [XX.X]
P/B Ratio: [X.X]

Growth Profile (3-Year):

Dividend CAGR: [X.X]% [✓ Consistent / ⚠ One cut]
Revenue CAGR: [X.X]%
EPS CAGR: [X.X]%

Dividend Sustainability:

Payout Ratio: [XX]%
FCF Payout Ratio: [XX]%
Status: [✓ Sustainable / ⚠ Monitor / ❌ Risk]

Financial Health:

Debt-to-Equity: [X.XX]
Current Ratio: [X.XX]
Status: [✓ Healthy / ⚠ Caution]

Quality Metrics:

ROE: [XX]%
Net Profit Margin: [XX]%
Quality Score: [XX]/100

Investment Considerations:

[Key strength 1]
[Key strength 2]
[Risk factor or consideration]

[Repeat for other top stocks]

行业： [行业名称] 市值： $[X.XX]B 当前股价： $[XX.XX]

估值指标：

股息收益率：[X.X]%
市盈率：[XX.X]
市净率：[X.X]

3年增长概况：

股息复合年增长率：[X.X]% [✓ 稳定增长 / ⚠ 曾有削减]
营收复合年增长率：[X.X]%
每股收益复合年增长率：[X.X]%

股息可持续性：

派息率：[XX]%
自由现金流派息率：[XX]%
状态：[✓ 可持续 / ⚠ 需关注 / ❌ 存在风险]

财务健康：

债务权益比：[X.XX]
流动比率：[X.XX]
状态：[✓ 健康 / ⚠ 需谨慎]

质量指标：

净资产收益率：[XX]%
净利润率：[XX]%
质量评分：[XX]/100

投资参考：

[核心优势1]
[核心优势2]
[风险因素或注意事项]

[重复上述格式分析其他排名靠前的股票]

Portfolio Construction Guidance

投资组合构建指南

Diversification Recommendations:

Sector breakdown of top 20 results
Suggested allocation strategy
Concentration risk warnings

Monitoring Recommendations:

Key metrics to track quarterly
Warning signs for each position
Rebalancing triggers

Risk Considerations:

Market cap concentration
Sector biases in results
Economic sensitivity warnings

undefined

分散化建议：

前20支股票的行业分布
建议配置策略
集中度风险提示

监控建议：

需按季度跟踪的核心指标
各持仓的预警信号
再平衡触发条件

风险提示：

市值集中度风险
结果的行业偏向性
经济敏感性预警

undefined

Step 5: Provide Context and Methodology

步骤5：提供背景与方法论说明

Reference screening methodology when explaining results:

Key concepts to explain:

Why these specific thresholds (3.5% yield, P/E 20, P/B 2)
Importance of dividend growth vs. static high yield
How composite score balances value, growth, and quality
Dividend sustainability vs. dividend trap distinction
Financial health metrics significance

Load

references/screening_methodology.md

to provide detailed explanations of:

Phase 1: Initial quantitative filters
Phase 2: Growth quality filters
Phase 3: Sustainability and quality analysis
Composite scoring system
Investment philosophy and limitations

解释结果时需参考筛选方法论：

需解释的核心概念：

为何设定这些具体阈值（3.5%收益率、20倍市盈率、2倍市净率）
股息增长 vs 静态高收益率的重要性
综合评分如何平衡价值、增长与质量
股息可持续性与股息陷阱的区别
财务健康指标的意义

可加载

references/screening_methodology.md

文件，提供以下内容的详细说明：

第一阶段：初始量化筛选
第二阶段：增长质量筛选
第三阶段：可持续性与质量分析
综合评分体系
投资理念与局限性

Step 6: Answer Follow-up Questions

步骤6：解答后续问题

Anticipate common user questions:

"Why did [stock] not make the list?"

Check which criteria it failed (yield, valuation, growth, sustainability)
Explain the specific filter that excluded it

"Can I screen for specific sectors?"

Filtering capability exists in script (modify line 383-388)
Suggest re-running with sector parameter additions

"What if I want higher/lower yield threshold?"

Script parameters are adjustable
Trade-offs between yield and growth
Recommend re-screening with new parameters

"How often should I re-run this screen?"

Quarterly recommended (aligns with earnings cycles)
Semi-annually sufficient for long-term holders
Market conditions may warrant more frequent checks

"How many stocks should I buy?"

Diversification guidance: minimum 10-15 for dividend portfolio
Sector balance considerations
Position sizing based on risk tolerance

提前准备常见用户问题的解答：

"为什么[某支股票]未入选？"

检查该股票未满足的具体标准（收益率、估值、增长、可持续性）
解释排除它的具体筛选条件

"能否针对特定行业筛选？"

脚本支持行业筛选功能（修改第383-388行）
建议添加行业参数后重新运行脚本

"如果我想调整收益率阈值怎么办？"

脚本参数可灵活调整
说明收益率与增长之间的权衡关系
建议使用新参数重新筛选

"我应该多久重新筛选一次？"

建议每季度筛选一次（与财报周期同步）
长期持有者每半年筛选一次即可
市场环境变化时可增加筛选频率

"我应该买入多少支股票？"

分散化建议：股息投资组合至少配置10-15支股票
需考虑行业平衡
根据风险承受能力调整仓位大小

Resources

资源说明

scripts/screen_dividend_stocks.py

Comprehensive screening script that:

Interfaces with FMP API for data retrieval
Implements multi-phase filtering logic
Calculates growth rates (CAGR) over 3-year periods
Evaluates dividend sustainability via payout ratios and FCF coverage
Assesses financial health (debt-to-equity, current ratio)
Computes quality scores (ROE, profit margins)
Ranks stocks by composite scoring system
Outputs structured JSON results

Dependencies:

requests

library (install via

pip install requests

)

Rate limiting: Built-in delays to respect FMP API limits (250 requests/day free tier)

Error handling: Graceful degradation for missing data, rate limit retries, API errors

功能全面的筛选脚本，具备以下能力：

与FMP API交互获取数据
实现多阶段筛选逻辑
计算3年复合年增长率（CAGR）
通过派息率与自由现金流覆盖率评估股息可持续性
评估财务健康度（债务权益比、流动比率）
计算质量评分（净资产收益率、利润率）
基于综合评分体系对股票排名
输出结构化JSON结果

依赖项：

requests

库（通过

pip install requests

安装）

速率限制： 内置延迟机制以遵守FMP API限制（免费版每日250次请求）

错误处理： 对缺失数据、速率限制、API错误等情况实现优雅降级

references/screening_methodology.md

Comprehensive documentation of screening approach:

Phase 1: Initial Quantitative Filters

Dividend yield >= 3.5% rationale and calculation
P/E ratio <= 20 threshold justification
P/B ratio <= 2 valuation logic

Phase 2: Growth Quality Filters

Dividend growth (3-year CAGR >= 5%)
Revenue positive trend analysis
EPS positive trend analysis

Phase 3: Quality & Sustainability Analysis

Dividend sustainability metrics (payout ratios, FCF coverage)
Financial health indicators (D/E, current ratio)
Quality scoring methodology (ROE, profit margins)

Composite Scoring System (0-100 points)

Score component breakdown and weighting
Interpretation guidelines

Investment Philosophy

Why this approach works
What this strategy avoids (dividend traps, value traps)
Ideal candidate profile

Usage Notes & Limitations

Best practices for portfolio construction
When to sell criteria
Historical context for threshold selection

筛选方法的详尽文档：

第一阶段：初始量化筛选

股息收益率≥3.5%的依据与计算方式
市盈率≤20的阈值合理性
市净率≤2的估值逻辑

第二阶段：增长质量筛选

3年股息复合年增长率≥5%
营收正增长趋势分析
每股收益正增长趋势分析

第三阶段：质量与可持续性分析

股息可持续性指标（派息率、自由现金流覆盖率）
财务健康指标（债务权益比、流动比率）
质量评分方法论（净资产收益率、利润率）

综合评分体系（0-100分）

评分构成与权重分配
评分解读指南

投资理念

该方法的有效性原因
该策略规避的风险（股息陷阱、价值陷阱）
理想标的特征

使用说明与局限性

投资组合构建最佳实践
卖出标准
阈值选择的历史背景

references/fmp_api_guide.md

Complete guide for Financial Modeling Prep API:

API Key Setup

Obtaining free API key
Setting environment variables
Free tier limits (250 requests/day)

Key Endpoints Used

Stock Screener API
Income Statement API
Balance Sheet API
Cash Flow Statement API
Key Metrics API
Historical Dividend API

Rate Limiting Strategy

Built-in protection in script
Request budget management
Best practices for free tier

Error Handling

Common errors and solutions
Debugging techniques

Data Quality Considerations

Data freshness and gaps
Data accuracy caveats
When to verify with SEC filings

Financial Modeling Prep API的完整指南：

API密钥设置

获取免费API密钥
设置环境变量
免费版限制（每日250次请求）

使用的核心接口

股票筛选API
利润表API
资产负债表API
现金流量表API
核心指标API
历史股息API

速率限制策略

脚本内置保护机制
请求预算管理
免费版最佳实践

错误处理

常见错误与解决方案
调试技巧

数据质量注意事项

数据时效性与缺口
数据准确性说明
何时需通过SEC文件验证

Advanced Usage

高级用法

Customizing Screening Criteria

自定义筛选标准

Modify thresholds in

scripts/screen_dividend_stocks.py

Line 383-388 - Initial screening parameters:

python

candidates = client.screen_stocks(
    dividend_yield_min=3.5,  # Adjust yield threshold
    pe_max=20,               # Adjust P/E threshold
    pb_max=2,                # Adjust P/B threshold
    market_cap_min=2_000_000_000  # Minimum $2B market cap
)

Line 423 - Dividend CAGR threshold:

python

if not div_cagr or div_cagr < 5.0:  # Adjust growth threshold

修改

scripts/screen_dividend_stocks.py

中的阈值：

第383-388行 - 初始筛选参数：

python

candidates = client.screen_stocks(
    dividend_yield_min=3.5,  # Adjust yield threshold
    pe_max=20,               # Adjust P/E threshold
    pb_max=2,                # Adjust P/B threshold
    market_cap_min=2_000_000_000  # Minimum $2B market cap
)

第423行 - 股息复合年增长率阈值：

python

if not div_cagr or div_cagr < 5.0:  # Adjust growth threshold

Sector-Specific Screening

特定行业筛选

Add sector filtering after initial screening:

python

undefined

在初始筛选后添加行业过滤：

python

undefined

Filter for specific sectors

target_sectors = ['Consumer Defensive', 'Utilities', 'Healthcare'] candidates = [s for s in candidates if s.get('sector') in target_sectors]

undefined

target_sectors = ['Consumer Defensive', 'Utilities', 'Healthcare'] candidates = [s for s in candidates if s.get('sector') in target_sectors]

undefined

Excluding REITs and Financials

排除REITs与金融股

REITs and financial stocks have different dividend characteristics (higher payouts, different metrics):

python

undefined

REITs与金融股的股息特征不同（派息率更高、指标体系不同）：

python

undefined

Exclude REITs and Financials

exclude_sectors = ['Real Estate', 'Financial Services'] candidates = [s for s in candidates if s.get('sector') not in exclude_sectors]

undefined

exclude_sectors = ['Real Estate', 'Financial Services'] candidates = [s for s in candidates if s.get('sector') not in exclude_sectors]

undefined

Exporting to CSV

导出为CSV格式

Convert JSON results to CSV for Excel analysis:

python

import json
import csv

with open('dividend_screener_results.json', 'r') as f:
    data = json.load(f)

stocks = data['stocks']

with open('screening_results.csv', 'w', newline='') as csvfile:
    if stocks:
        fieldnames = stocks[0].keys()
        writer = csv.DictWriter(csvfile, fieldnames=fieldnames)
        writer.writeheader()
        writer.writerows(stocks)

将JSON结果转换为CSV格式以便用Excel分析：

python

import json
import csv

with open('dividend_screener_results.json', 'r') as f:
    data = json.load(f)

stocks = data['stocks']

with open('screening_results.csv', 'w', newline='') as csvfile:
    if stocks:
        fieldnames = stocks[0].keys()
        writer = csv.DictWriter(csvfile, fieldnames=fieldnames)
        writer.writeheader()
        writer.writerows(stocks)

Troubleshooting

故障排除

"ERROR: requests library not found"

Solution: Install requests library

bash

pip install requests

解决方案： 安装requests库

bash

pip install requests

"ERROR: FMP API key required"

Solution: Set environment variable or provide via command-line

bash

export FMP_API_KEY=your_key_here

解决方案： 设置环境变量或通过命令行指定

bash

export FMP_API_KEY=your_key_here

OR

或

python3 scripts/screen_dividend_stocks.py --fmp-api-key your_key_here

undefined

python3 scripts/screen_dividend_stocks.py --fmp-api-key your_key_here

undefined

"ERROR: FINVIZ API key required when using --use-finviz"

Solution: Set environment variable or provide via command-line

bash

export FINVIZ_API_KEY=your_key_here

解决方案： 设置环境变量或通过命令行指定

bash

export FINVIZ_API_KEY=your_key_here

OR

或

python3 scripts/screen_dividend_stocks.py --use-finviz --finviz-api-key your_key_here


**Note:** FINVIZ Elite subscription required (~$40/month or ~$330/year)

python3 scripts/screen_dividend_stocks.py --use-finviz --finviz-api-key your_key_here


**注意：** 需要订阅FINVIZ Elite服务（约40美元/月或330美元/年）

"ERROR: FINVIZ API authentication failed"

Possible causes:

Invalid FINVIZ API key
FINVIZ Elite subscription expired
API key format incorrect

Solution:

Verify FINVIZ Elite subscription is active
Check API key for typos (should be alphanumeric string)
Log into FINVIZ Elite account and verify API key in settings
Try accessing FINVIZ Elite screener manually to confirm subscription

可能原因：

FINVIZ API密钥无效
FINVIZ Elite订阅已过期
API密钥格式错误

解决方案：

验证FINVIZ Elite订阅是否处于活跃状态
检查API密钥是否存在拼写错误（应为字母数字字符串）
登录FINVIZ Elite账户，在设置中验证API密钥
手动访问FINVIZ Elite筛选器确认订阅可用

"ERROR: FINVIZ pre-screening failed or returned no results"

Possible causes:

FINVIZ API connection issue
Screening criteria too restrictive (no stocks match)
Market conditions (bear market may yield fewer results)

Solution:

Check internet connection
Verify FINVIZ Elite website is accessible

Try FMP-only method as fallback:

bash

python3 scripts/screen_dividend_stocks.py

可能原因：

FINVIZ API连接问题
筛选标准过于严格（无匹配股票）
市场环境影响（熊市中符合条件的股票较少）

解决方案：

检查网络连接
确认FINVIZ Elite网站可正常访问
尝试使用仅FMP的筛选方式作为备选：
bash
```
python3 scripts/screen_dividend_stocks.py
```

"WARNING: Rate limit exceeded"

Solution: Script automatically retries after 60 seconds. If persistent:

Wait until next day (free tier resets daily)
Reduce number of stocks analyzed (modify line 394 limit)
Consider upgrading to paid FMP tier

解决方案： 脚本会自动在60秒后重试。若问题持续：

等待至次日（免费版每日重置请求限额）
减少分析的股票数量（修改第394行的限制参数）
考虑升级至FMP付费版

"No stocks found matching all criteria"

Solution: Criteria may be too restrictive

Relax P/E threshold (increase from 20)
Lower dividend yield requirement (decrease from 3.5%)
Reduce dividend growth requirement (decrease from 5%)
Check market conditions (bear markets may have fewer qualifiers)

解决方案： 筛选标准可能过于严格

放宽市盈率阈值（从20调高）
降低股息收益率要求（从3.5%调低）
降低股息增长率要求（从5%调低）
关注市场环境（熊市中符合条件的股票较少）

Script runs slowly

脚本运行缓慢

Expected behavior: Script includes 0.3s delay between API calls for rate limiting

100 stocks analyzed = ~8-10 minutes
First 20-30 qualifying stocks usually found within first 50-70 analyzed

正常现象： 脚本在API调用之间内置了0.3秒的延迟以遵守速率限制

分析100支股票约需8-10分钟
通常在分析50-70支股票后即可找到20-30支符合条件的标的

Performance & Cost Optimization

性能与成本优化

API Call Comparison

API调用量对比

Two-Stage Screening (FINVIZ + FMP):

FINVIZ: 1 API call
FMP Quote API: ~30-50 calls (one per pre-screened symbol)
FMP Financial Data: ~150-250 calls (5 endpoints × 30-50 symbols)
Total FMP calls: ~180-300

FMP-Only Screening:

FMP Stock Screener: 1 call (returns 100-1000 stocks)
FMP Financial Data: ~500-5000 calls (5 endpoints × 100-1000 symbols)
Total FMP calls: ~500-5000

Savings: 60-94% reduction in FMP API usage

两阶段筛选（FINVIZ + FMP）：

FINVIZ：1次API调用
FMP报价API：约30-50次调用（每支预筛选标的1次）
FMP财务数据API：约150-250次调用（5个接口 × 30-50支标的）
FMP总调用量：约180-300次

仅FMP筛选：

FMP股票筛选API：1次调用（返回100-1000支股票）
FMP财务数据API：约500-5000次调用（5个接口 × 100-1000支标的）
FMP总调用量：约500-5000次

节省幅度：FMP API调用量减少60-94%

Cost Analysis

成本分析

FINVIZ Elite:

Monthly: $39.99
Annual: $329.99 (~$27.50/month)

FMP API:

Free tier: 250 calls/day (sufficient for two-stage screening)
Starter tier: $29.99/month for 750 calls/day
Professional tier: $79.99/month for 2000 calls/day

Recommendation:

For free FMP tier users: Use two-stage screening (FINVIZ + FMP free tier)
For paid FMP tier users: Either approach works; two-stage is faster
Budget option: FMP-only with free tier (run screening every few days)
Optimal option: FINVIZ Elite ($330/year) + FMP free tier = Complete solution

FINVIZ Elite：

月付：39.99美元
年付：329.99美元（约合27.50美元/月）

FMP API：

免费版：每日250次请求（满足两阶段筛选需求）
入门版：29.99美元/月，每日750次请求
专业版：79.99美元/月，每日2000次请求

推荐方案：

FMP免费版用户：采用两阶段筛选（FINVIZ + FMP免费版）
FMP付费版用户：两种方式均可，两阶段筛选速度更快
预算有限用户：使用仅FMP的免费版筛选方式（每几天运行一次）
最优方案：FINVIZ Elite（330美元/年） + FMP免费版 = 完整解决方案

Version History

版本历史

v1.1 (November 2025): Added FINVIZ Elite integration for two-stage screening
v1.0 (November 2025): Initial release with comprehensive multi-phase screening

v1.1（2025年11月）：新增FINVIZ Elite集成，支持两阶段筛选
v1.0（2025年11月）：初始版本，支持多阶段综合筛选