核心维度
每一次扩张都沿着几个相互独立的轴来描述。请勿混淆它们：
| 字段 | 它所刻画的内容 | 示例值 |
|---|
stage | 一家公司在某个市场中推进到了什么程度 | exploring、committing、expanding、scaling、established |
momentum | 此刻这次举措的走势 | accelerating、advancing、steady、pulling_back |
| flow（流向） | 市场之间这次举措的方向，用 froms / tos 表达 | outbound（froms）、inbound（tos）、corridor（froms→tos） |
freshness | 证据的新近程度 | fresh、cooling、stale、cold |
scope | 是进入新市场，还是在既有存在基础上的增长 | entering_new_market、expanding_within_presence、established_only |
expansion_score | 可排序的 0–1 分值，衡量该扩张的显著程度 | 0.72 |
阶段的 slug 为 exploring、committing、expanding、scaling 与 established，分别对应显示名称：探索、投入中、拓展中、规模化中与已建立。
流向（这次举措的方向）与 momentum（走势）是不同的概念。按”正在推进的公司”筛选用的是 momentum: ["advancing"]；按”正在向美国扩张的公司”筛选则是 tos: ["US"]。没有单独的 direction 请求字段——流向完全由 froms / tos 决定。
请求筛选项
市场（froms / tos）
地理是一种有向关系：公司从某个来源地向某个目标市场扩张。两个列表即可表达所有情形——无需单独的方向标志。
| 参数 | 类型 | 含义 |
|---|
froms | string[]（ISO alpha-2） | 来源市场——公司从哪里扩张（其所在地 / 总部）。 |
tos | string[]（ISO alpha-2） | 目标市场——公司向哪里扩张。 |
exclude_froms | string[]（ISO alpha-2） | 要排除的来源市场。 |
exclude_tos | string[]（ISO alpha-2） | 要排除的目标市场。 |
| 你发送 | 你得到 |
|---|
tos: ["US"] | 所有扩张进入美国的公司（inbound）。 |
froms: ["CN"] | 中国公司向任意地方扩张（outbound）。 |
froms: ["CN"]、tos: ["US"] | 仅 CN → US 走廊。 |
| 两者都不传 | 全球所有扩张。 |
扩张信号筛选项
| 参数 | 类型 | 含义 |
|---|
stages | string[] | 筛选到一个或多个扩张阶段。 |
momentum | string[] | 按走势筛选（accelerating/advancing/steady/pulling_back）。 |
freshness | string[] | 按证据新近程度筛选（fresh/cooling/stale/cold）。 |
scopes | string[] | 按 entering_new_market / expanding_within_presence 筛选。 |
signal_types | string[] | 限定为特定信号类型（HIRE、OFFICE、AD、NEWS……）。 |
signal_strengths | string[] | 按证据强度分档筛选（例如 high、very_high）。 |
min_signal_count | integer | 扩张信号的最小数量——凸显足迹厚重的行动者。 |
ahead_of_pace | boolean | 仅显示比该市场典型节奏更快推进的公司。 |
only_contraction | boolean | 仅显示处于风险中 / 正在收缩的市场。 |
min_markets | integer | 公司在该时间窗内进入的不同新市场的最小数量。 |
企业信息
| 参数 | 类型 | 含义 |
|---|
verticals、technologies | string[] | 公司行业 / 技术栈筛选项。 |
employees | number[][] | 员工规模区间，例如 [[50, 200]]。 |
founded_dates | number[] | 成立年份区间 [from, to]。 |
revenues | number[] | 营收区间（美元）[from, to]。 |
keywords | string[] | 自由文本主题范围限定。 |
companies | string[] | 通过 domain_search_id、域名或 LinkedIn URL 的任意组合限定到特定公司（域名 / URL 会解析为排名最高的对应公司）。 |
时间窗与搜索
| 参数 | 类型 | 含义 |
|---|
transitioned_dates | string[] | 信号 / 转变时间窗，采用 ISO [from, to] 区间。 |
window_days | integer | 滚动时间窗（天），在未提供 transitioned_dates 时使用。 |
query | string | 自然语言搜索——Pubrio 会将其解读为筛选项（并在 filters 中回显）。 |
is_explain_match | boolean | 为每家公司添加一段基于其真实信号的 AI match_summary。引用的信号数量及批处理规模均随 per_page 变化；高频来源（招聘信息、广告投放）会以数量形式汇总，而非逐条列出。 |
sort_by | string | 结果排序方式：expansion_score、signal_count 或 company_ranking。留空则使用默认排序（按最近变更时间排序）。 |
响应字段
每公司 / 每市场的 stage
| 字段 | 含义 |
|---|
stage.slug | 当前阶段（exploring … scaling）。 |
stage.expansion_score | 可排序的 0–1 显著性分值。 |
stage.scope | 新市场 vs 既有存在内。 |
stage.direction | 该阶段的走势：advancing、steady、retreating 或 new。这是走势这一轴在响应侧的呈现，与你用 momentum 请求参数所筛选的是同一维度——两者取值集合不同，请据此映射。 |
stage.freshness | 最新证据的新近程度分档。 |
stage.signal_count | 该市场中活跃扩张信号的数量。 |
stage.first_signal_at / latest_signal_at / last_transition_at | 关键时间戳。 |
信号、存在与解释
| 字段 | 含义 |
|---|
signals[] | 底层证据：signal_type、signal_subtype、signal_strength、polarity、event_date、source_type、display_label、evidence_url。 |
presence[] | 已知的市场内足迹（办公室 / 实体）：presence_type、presence_strength、address、known_since。 |
timeline[] | 阶段转变历史：stage_slug、transitioned_at、transition_kind。 |
other_markets[] | 该公司的其他活跃市场，各自附带其阶段 + 计数。 |
match_summary | （当 is_explain_match: true 时） { text, citations }——AI 给出的”为何匹配”，并引用该公司的真实信号。每条引用都带有 count 字段：若为真实的单条信号则为 null；若该引用是招聘信息、广告投放等窗口期内的数量汇总而非单一事件，则为整数。 |
expansion_score 是一个可排序的分值（可跨公司比较）。它不同于任何内部模型置信度——公开 API 不返回后者。
