Free Short Interest Data API
for US Stock Research免费美股空头持仓数据 API
查询与接入指南
Evaluate free short interest APIs by the position snapshot they actually deliver: settlement date, publication timing, shares short, float denominator, days-to-cover inputs, corporate-action treatment, and historical revisions.
评估免费的美股空头持仓 API 时，应关注它实际提供的持仓快照：结算日、发布日期、空头股数、流通股分母、回补天数输入、公司行动处理与历史修订。
TL;DR摘要
Short interest is the open short position at a designated settlement date. Daily short-sale volume is trading activity and cannot replace it.
Store settlement date, official publication date, and provider retrieval time separately. A value is not knowable in a backtest before publication.
Days to cover depends on an average-volume window; short percent of float depends on a float estimate and effective date. Preserve both inputs.
Ticker changes, splits, mergers, delistings, corrections, and provider backfills can break naive comparisons. Keep raw and adjusted views explicit.
short interest 是指定结算日仍未平仓的空头头寸；每日卖空成交量只是交易活动，不能替代持仓快照。
结算日、官方发布日期与服务商抓取时间含义不同。回测时，数据在发布日期之前并不可知。
回补天数取决于平均成交量窗口，流通股卖空比例取决于 float 估算及其生效日；两个输入都应保存。
代码变更、拆股、并购、退市、更正和服务商回填都会破坏简单比较，应明确区分原始值与调整后视图。
What a free short interest data API should return免费美股空头持仓数据 API 应返回哪些字段
A useful short interest API JSON response needs enough context to compare one reporting cycle with another. Do not treat a single percentage without its denominator, date, and source as analysis-ready data.
可用的美股空头持仓数据接口必须提供足够上下文，才能比较不同报告周期。缺少分母、日期或来源的单一百分比，不应直接用于分析。
FINRA reporting is tied to designated settlement dates and later publication dates. A provider can deliver the published file quickly, but it cannot turn that official position snapshot into real-time open interest. If a product advertises “live short interest,” determine whether it is an estimate, securities-lending signal, daily short volume, or the most recently published official observation.
FINRA 的空头持仓申报以指定结算日为基准，并在之后的发布日期公开。服务商可以更快分发已发布文件，但不能把官方持仓快照变成实时未平仓量。如果产品宣传“实时 short interest”，必须确认它指的是模型估算、证券借贷信号、每日卖空成交量，还是最近一次正式发布值。
| Field字段 | Meaning含义 | Validation核验重点 |
|---|---|---|
ticker | Security identifier used by the endpoint.接口使用的证券代码。 | Exchange and ticker mapping.交易所与代码映射。 |
settlement_date | Date to which the reported position applies.报告持仓对应的结算日。 | Do not confuse it with publication time.不要与发布日期混淆。 |
short_interest | Shares sold short and not yet covered.已卖空但尚未回补的股数。 | Units, adjustments, and missing values.单位、复权与缺失值。 |
avg_daily_volume | Volume baseline used for comparison.用于比较的平均日成交量。 | Provider calculation window.服务商采用的计算窗口。 |
days_to_cover | Short interest divided by average daily volume.空头股数除以平均日成交量。 | Recalculate when both inputs exist.输入齐全时自行复算。 |
publication_date | Date the reporting-cycle value became publicly available.该报告周期数值正式公开的日期。 | Required for point-in-time research; do not substitute settlement date.时点研究必需，不能用结算日替代。 |
float_shares | Provider estimate of tradable public float used by short-percent-of-float.用于计算流通股卖空比例的可交易公众持股估算。 | Source, as-of date, share-class scope, and split adjustment.来源、口径日期、股份类别范围与拆股调整。 |
source_revision | Version or correction state of the published observation.已发布观测值的版本或更正状态。 | Whether history is overwritten, versioned, or backfilled.历史数据是覆盖、保留版本还是回填。 |
Short interest ratio API and days to cover卖空比率 API 与回补天数
Providers sometimes use “short interest ratio” to mean days to cover. Read the data dictionary instead of assuming every ratio is short interest as a percentage of float.
部分服务商用“卖空比率”指代回补天数。应先阅读数据字典，不要假设所有 ratio 都代表空头持仓占流通股比例。
Even when two providers both publish days to cover, they may use different average-volume windows, venues, or adjusted volumes. Recompute the ratio from stored inputs when possible, label the window, and do not rank securities across providers until the formulas are aligned.
即使两家服务都提供 days to cover，也可能采用不同的平均成交量窗口、交易场所范围或复权成交量。条件允许时应根据保存的输入自行复算并标明窗口；公式未统一前，不应直接跨服务商排名。
Short interest is not short volume空头持仓量不等于卖空成交量
Short volume records reported short-sale activity during a period. Short interest measures open positions on a settlement date. The two datasets answer different questions and should not be substituted.
卖空成交量记录一段时间内的卖空交易活动；空头持仓量记录结算日尚未回补的头寸。两者回答不同问题，不能互相替代。
A short sale can be closed the same day and therefore appear in daily short volume without remaining in the next position snapshot. Conversely, a short position opened earlier can remain in short interest without generating new short-sale volume that day. Off-exchange daily files are also not automatically a consolidated view of all venues.
一笔卖空交易可以在当天回补，因此会出现在每日卖空成交量中，却不会留到下一次持仓快照；反过来，较早建立的空头头寸可以继续存在于 short interest 中，但当天并没有新的卖空成交。场外每日文件也不天然代表所有交易场所的合并口径。
How to choose a historical short interest data API如何选择历史美股空头持仓数据接口
Check whether the free plan includes the short interest endpoint, which tickers are available, the request quota, history depth, and whether a credit card is required.
Confirm exchanges, active and delisted securities, earliest settlement date, update timing, and how corrections are handled.
Look for stable names, explicit null handling, pagination, date filters, units, split treatment, and a documented error model.
A free API key does not automatically grant redistribution rights. Review caching, display, commercial-use, attribution, and retention terms.
Use samples with a split, ticker change, multiple share classes, delisting, and merger. Determine whether historical short shares are raw or adjusted and whether the API keeps a stable security identifier beside ticker.
For each observation, require settlement date, publication date, retrieval time, and correction state. Replay a historical date and prove that the API does not expose a later correction or backfill as though it were known earlier.
检查免费方案是否包含空头持仓端点、可查询股票、请求限额、历史深度，以及是否需要信用卡。
确认交易所、在市与退市证券、最早结算日、更新时间，以及数据更正方式。
查看字段名是否稳定、空值如何表达、是否分页、是否支持日期过滤，以及单位、拆股和错误响应是否有文档。
免费 API Key 不等于允许再分发。应核对缓存、展示、商业用途、署名和数据保留条款。
样本应包含拆股、股票代码变更、多类别股份、退市和并购，确认历史空头股数是原始口径还是复权口径，以及接口是否在 ticker 之外保留稳定证券标识。
每条观测都应包含结算日、发布日期、抓取时间与更正状态。以历史日期重放，确认接口不会把之后的更正或回填伪装成当时已经可知的数据。
Authority source and reporting context权威来源与报告口径
For US reporting context, consult FINRA’s Short Interest Reporting guidance. An API provider may normalize or enrich the data, so record both the original reporting date and the provider retrieval time.
了解美国市场报告口径时，应查阅 FINRA 空头持仓报告说明。服务商可能对数据做标准化或补充，因此应同时记录原始报告日期和接口获取时间。
Python short interest data API examplePython 获取美股空头持仓数据示例
Replace the placeholder URL and authentication method with the provider’s documented values. The example deliberately validates HTTP status and required fields before analysis.
请按服务商文档替换占位 URL 与鉴权方式。示例会先检查 HTTP 状态和必需字段，再进入分析。
import os
import requests
response = requests.get(
"https://api.example.com/v1/short-interest",
params={"ticker": "AAPL", "limit": 24},
headers={"Authorization": f"Bearer {os.environ['DATA_API_KEY']}"},
timeout=20,
)
response.raise_for_status()
rows = response.json()["results"]
required = {"settlement_date", "short_interest",
"avg_daily_volume", "days_to_cover"}
if rows and not required.issubset(rows[0]):
raise ValueError("Provider response is missing required fields")
for row in rows[:3]:
print(row["settlement_date"], row["days_to_cover"])Validate historical short interest data by ticker按股票代码验证历史卖空数据
Sort by settlement date, detect duplicates, preserve nulls, and compare consecutive reports. If you calculate percentage change or days to cover yourself, store the exact input fields and calculation version.
按结算日排序、检测重复记录、保留空值，并比较相邻报告。若自行计算变化率或回补天数，应保存精确输入字段和计算版本。
A production validator should enforce uniqueness on stable security identifier plus settlement date and source version, not ticker alone. Check that short shares are non-negative integers, dates follow the expected reporting calendar, days to cover matches the documented volume window within tolerance, and split-era discontinuities are explained. Keep raw provider payloads so later corrections can be audited.
生产级验证器应以稳定证券标识、结算日和来源版本组成唯一键，而不是只用 ticker。检查空头股数是否为非负整数、日期是否符合预期报告日历、回补天数能否在容差范围内由文档规定的成交量窗口复算，并要求拆股前后的突变有明确解释。原始服务商响应也应保存，以便审计之后的更正。
Use QVeris to find and call short interest data tools用 QVeris 查找并调用空头持仓数据工具
QVeris can help an agent discover and inspect capabilities for official short-interest history, derived ratios, or short-volume data. Before a call, the agent should state which dataset it needs, the security identifier, settlement-date range, publication-time cutoff, adjustment policy, and required denominators. It must not substitute daily short volume for open short positions or describe a twice-monthly official snapshot as real time. The provider remains the source of the data and its terms.
QVeris 可以帮助 Agent 发现并检查官方空头持仓历史、派生比率或卖空成交量等能力。调用前，应明确需要哪一种数据、证券标识、结算日范围、发布日期截止时点、复权策略与必需分母；不能用每日卖空成交量替代未平仓空头头寸，也不能把每月两次的官方快照描述成实时数据。底层服务商仍是数据及其条款的来源。
- Open the QVeris tool details to review matching data capabilities.
- Inspect parameters and response fields before allowing an agent to call a provider.
- Use the QVeris documentation and Python SDK guide for integration patterns.
- 先使用 QVeris 工具详情发现匹配的数据能力。
- 在允许智能体调用服务商前，先检查参数与返回字段。
- 参考 QVeris 文档和 Python SDK 指南完成接入。
FAQ常见问题
Some providers offer a free plan or evaluation access, and FINRA publishes public reporting context and data resources. Verify that the endpoint contains position snapshots rather than only daily short volume, then check history, quota, licensing, and stable identifiers.
Start with provider API documentation and compare it with the relevant exchange or FINRA reporting context. Choose an API only after validating the source and schema.
FINRA member firms report positions for designated settlement dates twice each month, followed by due and publication dates. A provider’s ingestion time, later corrections, and estimated “live” signals are separate timestamps and should be labeled.
At minimum: ticker, settlement date, short interest shares, average daily volume, and days to cover, plus source and retrieval metadata when available.
No. Short volume is trading activity during a period; short interest is an open position measured on a settlement date.
Call a documented ticker endpoint, check the HTTP response, parse JSON, validate required fields, and sort the records by settlement date.
It is short shares divided by a defined public-float share count. The ratio is only reproducible when the float source, effective date, share class, corporate-action adjustment, and short-interest settlement date are known.
Yes, but use publication time—not settlement date—as the earliest availability point, retain historical revisions, and avoid current float or adjusted values that were unavailable at the simulated date.
部分服务商提供免费方案或评测额度，FINRA 也公开报告口径与相关数据资源。首先确认端点提供的是持仓快照，而不是只有每日卖空成交量，再核对历史、额度、许可与稳定证券标识。
先查看数据服务商的 API 文档，并与相关交易所或 FINRA 的报告口径对照。只有确认数据来源和字段结构后，才应选择并接入接口。
FINRA 会员公司针对每月两次的指定结算日申报持仓，之后还有报送截止日与公开发布日期。服务商采集时间、后续更正和所谓“实时”估算属于不同时间，应分别标明。
至少应包含股票代码、结算日、空头持仓股数、平均日成交量和回补天数；如条件允许，还应提供数据来源和获取时间等元数据。
不同。卖空成交量表示一段时间内的卖空交易活动；空头持仓量表示某个结算日仍未平仓的空头头寸。
调用有明确文档的股票代码查询端点，检查 HTTP 响应，解析 JSON，验证必需字段，再按结算日对记录排序。
它是空头股数除以定义明确的公众流通股数量。只有同时知道 float 来源、生效日、股份类别、公司行动复权方式和空头持仓结算日，这个比例才可以复算。
可以，但最早可用时间应采用发布日期，而不是结算日；还要保留历史修订，并避免使用模拟时点尚不可知的当前 float 或事后复权值。