> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pubrio.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 扩张字段参考

> 扩张 API 的逐字段字典——每一个请求筛选项和响应字段，及其类型、允许值和含义。

<Info>
  本页是扩张 API 的**字段字典**：每个请求筛选项的作用以及每个响应字段的含义。关于该模型背后的*原理*，请参阅 [扩张信号的工作原理](/cn/knowledge-base/concepts/how-expansion-signals-work)，值目录请参阅 [扩张信号的工作原理](/cn/knowledge-base/concepts/how-expansion-signals-work)。如需始终最新的允许值列表，请调用 [扩张分类法](/cn/api-reference/endpoint/expansions/types) 端点。
</Info>

## 核心维度

每一次扩张都沿着几个相互独立的轴来描述。请勿混淆它们：

| 字段                | 它所刻画的内容                              | 示例值                                                                  |
| ----------------- | ------------------------------------ | -------------------------------------------------------------------- |
| `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`                                                               |

<Note>
  阶段的 slug 为 `exploring`、`committing`、`expanding`、`scaling` 与 `established`，分别对应显示名称：探索、投入中、拓展中、规模化中与已建立。
</Note>

<Warning>
  **流向**（这次举措的方向）与 `momentum`（走势）是不同的概念。按"正在推进的公司"筛选用的是 `momentum: ["advancing"]`；按"正在向*美国*扩张的公司"筛选则是 `tos: ["US"]`。没有单独的 `direction` 请求字段——流向完全由 `froms` / `tos` 决定。
</Warning>

## 请求筛选项

### 市场（`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`；若该引用是招聘信息、广告投放等窗口期内的数量汇总而非单一事件，则为整数。 |

<Note>
  `expansion_score` 是一个**可排序的分值**（可跨公司比较）。它不同于任何内部模型置信度——公开 API 不返回后者。
</Note>