> ## 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

> 完成身份验证、发起您的首批扩张 API 调用、对结果分页，并读取扩张分数。

<Info>
  本快速入门通过几次调用，让您从零开始读取实时扩张信号。它假设您已拥有 Pubrio API 密钥——参见[身份验证](/cn/api-reference/authentication)以创建一个。
</Info>

## 前提条件

* 一个 Pubrio API 密钥（参见[身份验证](/cn/api-reference/authentication)）。
* 一个公司的 `domain_search_id`。您可以从[公司检索](/cn/api-reference/endpoint/companies/search)端点获取。

所有扩张端点均为 `POST` 并接受 JSON 请求体。请按[身份验证](/cn/api-reference/authentication)中的说明，在每个请求中包含您的凭据。

## 第 1 步 — 查询一家公司的扩张

从单家公司入手，列出它正在进入的每一个市场。

```bash theme={null}
POST /expansions/companies/lookup
{ "domain_search_id": "550e8400-e29b-41d4-a716-446655440002", "is_all_markets": true }
```

```json theme={null}
{
  "metadata": { "domain_search_id": "550e8400-e29b-41d4-a716-446655440002", "home_country_code": "US" },
  "data": { "market_count": 2, "dominant_stage_slug": "expanding", "total_signal_count": 194 },
  "markets_summary": [
    { "country_code": "GB", "stage_slug": "expanding", "is_home_market": false, "signal_count": 140, "distinct_type_count": 6, "latest_signal_at": "2026-07-08T02:42:23.544Z", "rank_now": 1 },
    { "country_code": "DE", "stage_slug": "committing", "is_home_market": false, "signal_count": 54, "distinct_type_count": 3, "latest_signal_at": "2026-06-20T00:00:00.000Z", "rank_now": 2 }
  ]
}
```

## 第 2 步 — 读取结果

`markets_summary` 中的每一项都描述该公司活跃的一个市场：

* **`stage_slug`** — 公司在该市场推进到何种程度（`exploring` → `scaling`）。
* **`signal_count`** / **`distinct_type_count`** — 支撑该市场的证据量，以及跨多少种信号类型。
* **`latest_signal_at`** — 最新信号的新近程度。
* **`signal_velocity_30d`** / **`signal_velocity_90d`** — 活跃度加速的快慢。
* **`rank_now`** — 该市场对这家公司的当前排名（`1` = 最强）。
* **`is_home_market`** — 是否为该公司的总部所在国。

若要找出最新鲜的行动者或按走势筛选，请使用接下来介绍的发现类端点（`freshness`、`momentum`）。

## 第 3 步 — 探索整个市场

若要以市场为先（而非以公司为先）开展工作，请使用[扩张市场详情](/cn/api-reference/endpoint/expansions/market_lookup)。它通过标准的 `page` / `per_page` 参数进行分页。

地理是一种有向的 **from → to** 关系，用两个列表表达：`froms`（来源 / 总部市场）与 `tos`（目标市场）。选择与你的问题相匹配的模式：

<CodeGroup>
  ```bash Inbound（进入 GB） theme={null}
  POST /expansions/lookup
  {
    "tos": ["GB"],
    "freshness": ["fresh", "cooling"],
    "page": 1,
    "per_page": 25
  }
  ```

  ```bash Outbound（来自 CN） theme={null}
  POST /expansions/lookup
  {
    "froms": ["CN"],
    "freshness": ["fresh", "cooling"],
    "page": 1,
    "per_page": 25
  }
  ```

  ```bash Corridor（CN → GB） theme={null}
  POST /expansions/lookup
  {
    "froms": ["CN"],
    "tos": ["GB"],
    "page": 1,
    "per_page": 25
  }
  ```
</CodeGroup>

读取 `metadata.pagination` 以翻页浏览结果：

```json theme={null}
{
  "metadata": {
    "filters": { "tos": ["GB"], "freshness": ["fresh", "cooling"] }
  },
  "data": {
    "pagination": { "page": 1, "per_page": 25, "total_entries": 64, "total_pages": 3 },
    "companies": [ /* ... */ ]
  }
}
```

通过递增 `page` 请求下一页。`per_page` 受您的套餐限制。

## 第 4 步 — 深入证据

当您想要一家公司举措背后的单条信号时，调用[公司信号事件](/cn/api-reference/endpoint/expansions/company_pulse_events)。

```bash theme={null}
POST /expansions/companies/pulse_events
{
  "domain_search_id": "550e8400-e29b-41d4-a716-446655440002",
  "signal_types": ["HIRE", "EXEC", "NEWS"],
  "window_days": 90,
  "page": 1
}
```

该端点返回 `total_entries` 和 `total_pages`——请求第 `1` 页至 `total_pages` 页（即在 `page` \< `total_pages` 时继续请求）。

## 筛选参考

大多数扩张端点接受以下筛选条件。其有效值列在[扩张信号的工作原理](/cn/knowledge-base/concepts/how-expansion-signals-work)中：

| 筛选             | 用途                                                         |
| -------------- | ---------------------------------------------------------- |
| `stages`       | 限定到一个或多个扩张阶段。                                              |
| `freshness`    | 按证据近期性限定。                                                  |
| `momentum`     | 按走势限定（`accelerating`/`advancing`/`steady`/`pulling_back`）。 |
| `scopes`       | 按市场进入范围限定。                                                 |
| `signal_types` | 限定到特定的信号类型。                                                |
| `froms`        | 来源 / 总部市场（**从**这里扩张）。                                      |
| `tos`          | 目标市场（扩张**进入**）。                                            |
| `companies`    | 通过 `domain_search_id`、域名或 LinkedIn URL 限定到特定公司。            |

`companies` 筛选接受任意组合的标识符类型——无需先解析为 ID：

<CodeGroup>
  ```bash 按域名 theme={null}
  POST /expansions/lookup
  { "companies": ["stripe.com", "airbnb.com"] }
  ```

  ```bash 按 LinkedIn URL theme={null}
  POST /expansions/lookup
  { "companies": ["https://www.linkedin.com/company/stripe"] }
  ```

  ```bash 按 domain_search_id theme={null}
  POST /expansions/lookup
  { "companies": ["550e8400-e29b-41d4-a716-446655440002"] }
  ```
</CodeGroup>

<Warning>
  不要混淆**流向**与**走势**。流向（市场之间举措的方向）由 `froms` / `tos` 设定——没有 `direction` 请求筛选。走势（举措如何推进）是 `momentum` 筛选，并在响应中以 `direction` 字段体现。
</Warning>

## 后续步骤

<CardGroup cols={2}>
  <Card title="实例演练" href="/cn/knowledge-base/concepts/expansion-signals-example">
    从市场到信号的完整演练。
  </Card>

  <Card title="扩张端点" href="/cn/api-reference/endpoint/expansions/dashboard">
    浏览每一个扩张 API 端点。
  </Card>
</CardGroup>