美股
概览
美股的行情、新闻、SEC 公告、内部人交易、财务、宏观序列,以及由它们聚成的事件——每一样都能回到过去某个时刻去问,只返回那一刻已经看得到的东西。
- 状态
- live
- 文档 id
id如AAPL- 引用格式
上游每条记录的 id(px: / evt_ / news: / filing: / form4: / fin: / macro:…@vintage)原样引用,并注明 license
细则
- 上游 1.0-beta(2026-10-19):license tiingo_internal renamed tiingo_licensed: Tiingo data is now licensed for redistribution; statement timeout (12 s) returns 504 with Retry-After: 60 instead of 500; GET /v1/search and GET /v1/stocks/search results cached for 60 s per parameter set; /v1/meta: base and routes[].free_samples are host-relative paths (no internal address, no doubled /v1)
回到某个时刻
每次调用都可以指定一个过去的时刻,结果只含那一刻已经看得到的东西:已经成交的价格,已经发出的新闻,已经受理的公告,宏观数据取当时首发的值而不是后来修订的值。拿它做回测,不会偷看未来。
search 放在 filters.as_of;read 用查询参数 as_of。ISO 日期或时间;不带时区按美东,只给日期就是美东那天结束。不传就是现在。那一刻还不存在的记录返回 404 not_visible_at_as_of,未来的时刻返回 400。
调用
POST /v1/stocks/search
{"query": "chip export restrictions", "filters": {"as_of": "2026-10-15"}}
POST /v1/stocks/search
{"query": "cloud server", "filters": {"source": "stocks"}}
GET /v1/stocks/read/AAPL?as_of=2026-09-01
GET /v1/stocks/read/AAPL?extra=prices&as_of=2026-09-01
GET /v1/stocks/read/macro:CPIAUCSL?as_of=2026-09-01
文字查询按相关性在新闻、事件、公告里一起排;这种默认检索的第一页另附顶层 stocks:按主题匹配到的前 5 只股票。filters.source 只查其中一类,source=stocks 只返回公司,按主题、业务找。全大写的代码(如 NVDA)或 * 改为按时间倒序列出。read 接代码、macro:<序列>、digest:market / digest:macro,或检索结果里任意一条记录的 id(news:…、evt_…、filing:…、form4:…、fin:…)。结果缓存 60 秒。
每类记录从什么时候起可见
| prices | daily bar of D visible after D 16:00 ET; 1m IEX bar visible at ts+1min |
| news | visible_at (live: first_seen_at; backfilled: crawl_at + 336 s) |
| filings | live 8-K / Form 4: acceptance (or first_seen_at if later); date-only filings: 22:00 ET of the date |
| financials | XBRL facts with filed date <= as_of (filed date counts from 22:00 ET) |
| macro | ALFRED vintage at as_of; daily FRED series: value dated X visible from X+1 17:00 ET; Treasury curve from 18:00 ET (backfill) / first seen (live); monthly releases after 16:00 ET on release day for the daily cut |
| events | cluster/member first_seen_at; partial clusters re-derive direction and summary from visible members |
| returns | only horizons whose end session closed before as_of |
| features | row D uses only data visible at D 16:00 ET; rows computed after as_of are recomputed |
| digest | as_of capped at the end of the session day; each section follows its source rule |
许可
每条记录带 license 字段,取值如下:
| sec_public | SEC EDGAR, public |
| us_gov_public | US federal agencies / Federal Reserve Board, public |
| cleveland_fed_public | Cleveland Fed nowcast, public |
| tiingo_licensed | Tiingo news/prices, licensed for redistribution (was tiingo_internal before 2026-10-19) |
| fed_bank | regional Reserve Bank / FRED-computed series (terms of use) |
| third_party | copyrighted series redistributed by FRED (ICE BofA, Cboe, Moody's, UMich, S&P, NAR, Freddie Mac) |
| wire_rss_summary | press-release RSS summaries |
尚未覆盖
- news history starts 2026-04-19
- Form 4 before 2026-10-16 arrives with the fadata history (2026-10-23)
- IEX 1-minute bars from 2026-10-19, focus list only
- fundamentals: SEC XBRL filers only (no ADRs / funds)
- analyst signals come from news stance (no broker feed, no consensus)
103 个宏观序列,用 macro:<id> 读
| id | 频率 | 序列 · license |
|---|---|---|
| A191RL1Q225SBEA | Q | Real Gross Domestic Product us_gov_public |
| AAA | M | Moody's Seasoned Aaa Corporate Bond Yield third_party |
| AWHAETP | M | Average Weekly Hours of All Employees, Total Private us_gov_public |
| BAA | M | Moody's Seasoned Baa Corporate Bond Yield third_party |
| BAMLC0A0CM | D | ICE BofA US Corporate Index Option-Adjusted Spread third_party |
| BAMLH0A0HYM2 | D | ICE BofA US High Yield Index Option-Adjusted Spread third_party |
| BAMLH0A0HYM2EY | D | ICE BofA US High Yield Index Effective Yield third_party |
| BUSLOANS | M | Commercial and Industrial Loans, All Commercial Banks us_gov_public |
| CCSA | W | Continued Claims (Insured Unemployment) us_gov_public |
| CES0500000003 | M | Average Hourly Earnings of All Employees, Total Private us_gov_public |
| CFNAI | M | Chicago Fed National Activity Index fed_bank |
| CIVPART | M | Labor Force Participation Rate us_gov_public |
| CPIAUCSL | M | Consumer Price Index for All Urban Consumers: All Items in U.S. City Average us_gov_public |
| CPILFESL | M | Consumer Price Index for All Urban Consumers: All Items Less Food and Energy in U.S. City Average us_gov_public |
| CSUSHPISA | M | S&P Cotality Case-Shiller U.S. National Home Price Index third_party |
| DCOILBRENTEU | D | Crude Oil Prices: Brent - Europe us_gov_public |
| DCOILWTICO | D | Crude Oil Prices: West Texas Intermediate (WTI) - Cushing, Oklahoma us_gov_public |
| DEXCHUS | D | Chinese Yuan Renminbi to U.S. Dollar Spot Exchange Rate us_gov_public |
| DEXJPUS | D | Japanese Yen to U.S. Dollar Spot Exchange Rate us_gov_public |
| DEXUSEU | D | U.S. Dollars to Euro Spot Exchange Rate us_gov_public |
| DFEDTARL | D | Federal Funds Target Range - Lower Limit us_gov_public |
| DFEDTARU | D | Federal Funds Target Range - Upper Limit us_gov_public |
| DFF | D | Federal Funds Effective Rate us_gov_public |
| DFII10 | D | Market Yield on U.S. Treasury Securities at 10-Year Constant Maturity, Quoted on an Investment Basis, Inflation-Indexed us_gov_public |
| DGORDER | M | Manufacturers' New Orders: Durable Goods us_gov_public |
| DGS1 | D | Market Yield on U.S. Treasury Securities at 1-Year Constant Maturity, Quoted on an Investment Basis us_gov_public |
| DGS10 | D | Market Yield on U.S. Treasury Securities at 10-Year Constant Maturity, Quoted on an Investment Basis us_gov_public |
| DGS1MO | D | Market Yield on U.S. Treasury Securities at 1-Month Constant Maturity, Quoted on an Investment Basis us_gov_public |
| DGS2 | D | Market Yield on U.S. Treasury Securities at 2-Year Constant Maturity, Quoted on an Investment Basis us_gov_public |
| DGS20 | D | Market Yield on U.S. Treasury Securities at 20-Year Constant Maturity, Quoted on an Investment Basis us_gov_public |
| DGS3 | D | Market Yield on U.S. Treasury Securities at 3-Year Constant Maturity, Quoted on an Investment Basis us_gov_public |
| DGS30 | D | Market Yield on U.S. Treasury Securities at 30-Year Constant Maturity, Quoted on an Investment Basis us_gov_public |
| DGS3MO | D | Market Yield on U.S. Treasury Securities at 3-Month Constant Maturity, Quoted on an Investment Basis us_gov_public |
| DGS5 | D | Market Yield on U.S. Treasury Securities at 5-Year Constant Maturity, Quoted on an Investment Basis us_gov_public |
| DGS6MO | D | Market Yield on U.S. Treasury Securities at 6-Month Constant Maturity, Quoted on an Investment Basis us_gov_public |
| DGS7 | D | Market Yield on U.S. Treasury Securities at 7-Year Constant Maturity, Quoted on an Investment Basis us_gov_public |
| DHHNGSP | D | Henry Hub Natural Gas Spot Price us_gov_public |
| DPRIME | D | Bank Prime Loan Rate us_gov_public |
| DSPIC96 | M | Real Disposable Personal Income us_gov_public |
| DTB3 | D | 3-Month Treasury Bill Secondary Market Rate, Discount Basis us_gov_public |
| DTWEXBGS | D | Nominal Broad U.S. Dollar Index us_gov_public |
| ECIALLCIV | Q | Employment Cost Index: Total compensation: All Civilian us_gov_public |
| EFFR | D | Effective Federal Funds Rate fed_bank |
| EXHOSLUSM495S | M | Existing Home Sales third_party |
| GDP | Q | Gross Domestic Product us_gov_public |
| GDPC1 | Q | Real Gross Domestic Product us_gov_public |
| GDPNOW | Q | GDPNow fed_bank |
| HOUST | M | New Privately-Owned Housing Units Started: Total Units us_gov_public |
| HSN1F | M | New One Family Houses Sold: United States us_gov_public |
| ICSA | W | Initial Claims us_gov_public |
| INDPRO | M | Industrial Production: Total Index us_gov_public |
| IORB | D | Interest Rate on Reserve Balances (IORB Rate) us_gov_public |
| JTSJOL | M | Job Openings: Total Nonfarm us_gov_public |
| M2SL | M | M2 us_gov_public |
| MICH | M | University of Michigan: Inflation Expectation third_party |
| MORTGAGE15US | W | 15-Year Fixed Rate Mortgage Average in the United States third_party |
| MORTGAGE30US | W | 30-Year Fixed Rate Mortgage Average in the United States third_party |
| NEWORDER | M | Manufacturers' New Orders: Nondefense Capital Goods Excluding Aircraft us_gov_public |
| NFCI | W | Chicago Fed National Financial Conditions Index fed_bank |
| PAYEMS | M | All Employees, Total Nonfarm us_gov_public |
| PCE | M | Personal Consumption Expenditures us_gov_public |
| PCEPI | M | Personal Consumption Expenditures: Chain-type Price Index us_gov_public |
| PCEPILFE | M | Personal Consumption Expenditures Excluding Food and Energy (Chain-Type Price Index) us_gov_public |
| PERMIT | M | New Privately-Owned Housing Units Authorized in Permit-Issuing Places: Total Units us_gov_public |
| PPIACO | M | Producer Price Index by Commodity: All Commodities us_gov_public |
| PPIFIS | M | Producer Price Index by Commodity: Final Demand us_gov_public |
| PSAVERT | M | Personal Saving Rate us_gov_public |
| RRPONTSYD | D | Overnight Reverse Repurchase Agreements: Treasury Securities Sold by the Federal Reserve in the Temporary Open Market Operations fed_bank |
| RSAFS | M | Advance Retail Sales: Retail Trade and Food Services us_gov_public |
| RSXFS | M | Advance Retail Sales: Retail Trade us_gov_public |
| SAHMREALTIME | M | Real-time Sahm Rule Recession Indicator fed_bank |
| SOFR | D | Secured Overnight Financing Rate fed_bank |
| STLFSI4 | W | St. Louis Fed Financial Stress Index fed_bank |
| T10Y2Y | D | 10-Year Treasury Constant Maturity Minus 2-Year Treasury Constant Maturity fed_bank |
| T10Y3M | D | 10-Year Treasury Constant Maturity Minus 3-Month Treasury Constant Maturity fed_bank |
| T10YIE | D | 10-Year Breakeven Inflation Rate fed_bank |
| T5YIE | D | 5-Year Breakeven Inflation Rate fed_bank |
| T5YIFR | D | 5-Year, 5-Year Forward Inflation Expectation Rate fed_bank |
| TCU | M | Capacity Utilization: Total Index us_gov_public |
| TOTALSA | M | Total Vehicle Sales us_gov_public |
| TOTBKCR | W | Bank Credit, All Commercial Banks us_gov_public |
| U6RATE | M | Total Unemployed, Plus All Persons Marginally Attached to the Labor Force, Plus Total Employed Part Time for Economic Reasons, as a Percent of the Civilian Labor Force Plus All Persons Marginally Attached to the Labor Force (U-6) us_gov_public |
| UMCSENT | M | University of Michigan: Consumer Sentiment third_party |
| UNRATE | M | Unemployment Rate us_gov_public |
| USREC | M | NBER based Recession Indicators for the United States from the Period following the Peak through the Trough third_party |
| VIXCLS | D | CBOE Volatility Index: VIX third_party |
| VXNCLS | D | CBOE NASDAQ 100 Volatility Index third_party |
| WALCL | W | Assets: Total Assets: Total Assets (Less Eliminations from Consolidation): Wednesday Level us_gov_public |
| WRESBAL | W | Liabilities and Capital: Other Factors Draining Reserve Balances: Reserve Balances with Federal Reserve Banks: Week Average us_gov_public |
| WTREGEN | W | Liabilities and Capital: Liabilities: Deposits with F.R. Banks, Other Than Reserve Balances: U.S. Treasury, General Account: Week Average us_gov_public |
| UST_PAR_1M | D | Treasury par yield 1M us_gov_public |
| UST_PAR_2M | D | Treasury par yield 2M us_gov_public |
| UST_PAR_3M | D | Treasury par yield 3M us_gov_public |
| UST_PAR_4M | D | Treasury par yield 4M us_gov_public |
| UST_PAR_6M | D | Treasury par yield 6M us_gov_public |
| UST_PAR_1Y | D | Treasury par yield 1Y us_gov_public |
| UST_PAR_2Y | D | Treasury par yield 2Y us_gov_public |
| UST_PAR_3Y | D | Treasury par yield 3Y us_gov_public |
| UST_PAR_5Y | D | Treasury par yield 5Y us_gov_public |
| UST_PAR_7Y | D | Treasury par yield 7Y us_gov_public |
| UST_PAR_10Y | D | Treasury par yield 10Y us_gov_public |
| UST_PAR_20Y | D | Treasury par yield 20Y us_gov_public |
| UST_PAR_30Y | D | Treasury par yield 30Y us_gov_public |
事件每小时 :40–:55 重建,这段时间响应会慢一些。上游不可用时网关返回 503 domain_unavailable,不扣费。
检索
POST
/v1/stocks/search混合检索,每条命中一张卡片。2 credits。免费样例:
chip export restrictions。过滤字段
| 字段 | 类型 · op | 含义 |
|---|---|---|
| source | keyword · eqall · news · events · filings · stocks · insiders | 查哪类:all(默认,新闻 + 事件 + 公告按相关性混排,第一页另附 stocks:按主题找到的前 5 只股票)| news | events | filings | stocks(按主题 / 业务找股票)| insiders(只按时间列) |
| ticker | keyword · eq | 股票代码 |
| as_of | keyword · eq | 时点(ISO 日期或时间),原样透传给上游 |
| date | datetime · range | 时间范围 {gte, lte} → 上游 from / to |
还有 7 个,照样能用
| 字段 | 类型 · op | 含义 |
|---|---|---|
| news_kind | keyword · eqcompany_news · press_release · analyst_note · market_wrap · macro · opinion · listicle_promo · non_finance | 新闻类型(source=news) |
| form | keyword · eq any8-K · 6-K · SCHEDULE 13G/A · 10-Q · SCHEDULE 13G · 10-K …共 15 个,/facets 可列全 | 表格类型(source=filings),可多个 |
| event_type | keyword · eqanalyst_rating · asset_sale · auditor_change · bankruptcy · buyback_dividend · capex_investment …共 38 个,/facets 可列全 | 事件类型(source=events),闭集见 nasdaq-event-taxonomy |
| semantic | keyword · eqoff · on · auto | 语义通道 auto(默认)| on | off(fa-index 的 searchd 通道上线前都是纯字面) |
| with_returns | bool · eq | 带收益标签(source=events,只给已满期的) |
| side | keyword · eqbuy · sell | buy | sell(source=insiders) |
| min_value | number · eq | 最小成交额 USD(source=insiders) |
参数
| 参数 | 类型 | 说明 |
|---|---|---|
| query 必填 | string | 1–1000 字符。也可以是最多 5 条的数组(批量,hits 变 results[])。 |
| top_k | integer= 10 | 1–100。 |
| fields | brief · head= brief | head 多扣 1 credit,每条附 head 视图。 |
| filters | json | 过滤 DSL 对象(见快速开始);可用字段见上表。 |
| mode | keyword= keyword | 这个域只有一种模式——词面匹配,不是语义检索。 |
| offset | integer= 0 | 翻页。 |
示例
{ "domain": "stocks", "query": "…", "hits": [ { "id": "AAPL", "score": 0.83, "brief": { … } } ], "total": null, "coverage": …, "warnings": [],
"meta": { "request_id": "req_…", "credits": { "charged": 2, "balance": 1998, "pool": "allowance" }, "latency_ms": 41, "cached": false } } 用了未声明的过滤字段返回 400,不会静默忽略。过滤条件是 AND;可用
_or / _not。读
GET
/v1/stocks/read/{id}三档深浅,不传就是
detail。免费样例:AAPL。三档
| 深浅 | credits | 返回 |
|---|---|---|
| brief | 1 | 个股概览:最新价、近期事件、新闻、公告 |
| detail (默认) | 1 | 个股概览:最新价、近期事件、新闻、公告 |
| full | 2 | 个股简报输入(逐条带可引用 id;上游现拼,慢,~45 s) |
侧面
同一份文档的另一个侧面,与 level 二选一。
| 侧面 | credits | 返回 |
|---|---|---|
| prices | 1 | 价格:interval=1d(日线)| 1m(IEX 分钟线,重点股,2026-10-16 起) |
| financials | 1 | 财务(XBRL,按 filed 时点可见,之后的重述不可见) |
| events | 1 | 事件(新闻 / 8-K / Form 4 归并) |
| news | 1 | 新闻 |
| filings | 1 | SEC 公告 |
| insiders | 1 | 内部人公开市场买卖(Form 4 P/S) |
| features | 2 | 特征(量价 / 事件派生) |
参数
| 参数 | 类型 | 说明 |
|---|---|---|
| id (path) 必填 | string | 文档 id(id)。 |
| level | brief · detail · full= detail | 读多深。 |
| extra | prices · financials · events · news · filings · insiders · features | 改读某个侧面,与 level 二选一。 |
| format | json · md · html= json | 响应形态。 |
| date | string | 交易日 (level = brief) |
| as_of | string | 时点:ISO 日期或时间(无时区按美东;只给日期 = 美东当天结束)。只返回当时已可见的数据 (level = brief) |
| from | string | 起(日期或时间) (extra = prices) |
| to | string | 止 (extra = prices) |
| limit | integer | 条数(1–200) (extra = prices) |
| interval | string= 1d | 1d | 1m (extra = prices) |
| fields | string | 只取这些字段 (extra = prices) |
| period | string= quarterly | quarterly | annual (extra = financials) |
| type | string | 事件类型 (extra = events) |
| with_returns | string | 1 = 带收益标签 (extra = events) |
| kind | string | 新闻类型 (extra = news) |
| form | string | 表格类型,逗号分隔 (extra = filings) |
| side | string | buy | sell (extra = insiders) |
| min_value | string | 最小金额 (extra = insiders) |
示例
{ "domain": "stocks", "id": "AAPL", "level": "detail", "view": "ticker_brief", "data": { … } | "text": "…", "token_count": 1834, "meta": { … } } 旧写法
GET /v1/stocks/doc/{id}?view=… 仍然可用。批量读
POST
/v1/stocks/read最多 50 个 id,同一档。查不到的 id 返回
error: "not_found",不扣费。参数
| 参数 | 类型 | 说明 |
|---|---|---|
| ids 必填 | string[] | 文档 id 列表。 |
| level | brief · detail · full= detail | 所有 id 共用的档。 |
| extra | prices · financials · events · news · filings · insiders · features | 改读某个侧面。 |
示例
{ "domain": "stocks", "level": "detail", "docs": [ { "id": "…", "data": { … } }, { "id": "…", "error": "not_found" } ], "meta": { … } } Facets
GET
/v1/stocks/facets?field={field}某个过滤字段的合法值,agent 不用猜;预聚合字段带计数,声明的枚举没有。免费、不需要 key。
参数
| 参数 | 类型 | 说明 |
|---|---|---|
| field 必填 | source · news_kind · form · event_type · semantic · side | 有 facets 的过滤字段。 |
| limit | integer= 50 | 最多返回多少个值。 |
示例
{ "domain": "stocks", "field": "…", "values": [ { "value": "…", "count": 3120 } ], "meta": { … } } 问registered key+ /stream
POST
/v1/stocks/ask对美股数据直接提问:按主题找公司、个股的价格与新闻面、事件、内部人交易、财务、宏观;问过去某个时点会自动带 as_of。引用为上游记录 id([stocks: 标题]),答案末尾附数据来源与「不构成投资建议」。
effort low / medium / high 对应 50 / 100 / 200 credits。加 /stream 走 NDJSON,第一个事件一定是 billing。首个 answer_delta 之前失败会退款。参数
| 参数 | 类型 | 说明 |
|---|---|---|
| query 必填 | string | 1–2000 字符。问得具体;要数字就直接问数字。 |
| effort | low · medium · high= low | 检索轮数,也决定价格:50 / 100 / 200 credits。套餐限制最高档。 |
| verbose | bool= false | 返回工具调用轨迹(流式时多 tool_call / tool_result / thinking 事件)。 |
| top_k | integer= 10 | 预取候选数。 |
| stream_answer | bool= true | 仅流式:false 时只发一个 answer 事件。 |
| max_rounds | integer | 0–8,覆盖 effort 预设。 |
| force_answer_after | number | 秒;强制切入作答阶段。 |
| max_answer_tokens | integer= 4096 | 触顶时置 answer_truncated。 |
| language | string | 回答语言,默认跟随 query。 |
示例
{ "answer": "… 上游每条记录的 id(px: / evt_ / news: / filing: / form4: / fin: / macro:…@vintage)原样引用,并注明 license …", "sources": [ … ], "stats": { "rounds": 1, "elapsed_s": 6.2, "answer_truncated": false }, "coverage"?: { … }, "meta": { "credits": { "charged": 50, … } } } 引用是真的——
answer 里的每个 id 都存在于本垂域(格式 上游每条记录的 id(px: / evt_ / news: / filing: / form4: / fin: / macro:…@vintage)原样引用,并注明 license)。sources 是召回集,不是引用列表。answer_truncated 表示不完整。