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

# 云足迹搜索

> 查看公司使用哪些云与托管服务商、部署在哪些国家和区域，并发现它刚进入的市场。

[云足迹搜索](/cn/api-reference/endpoint/companies/cloud_footprints_search) 按「公司 × 服务商 × 国家」返回记录。一家公司在德国用 AWS、在新加坡用 Cloudflare，就是两条记录。每条记录包含该处的部署规模、涉及的云区域与城市，以及首次和最近观察到的时间。

```bash cURL theme={null}
curl -X POST https://api.pubrio.com/companies/cloud_footprints/search \
  -H "pubrio-api-key: $PUBRIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "target_locations": ["DE"],
    "providers": ["AWS"],
    "first_seen_dates": ["2026-07-01", null],
    "host_count": [100, null],
    "per_page": 25
  }'
```

## 适用场景

* **发现市场进入。**`first_seen_dates` 找出在你设定的时间窗口内首次出现于某国的公司。
* **按规模筛选。**`host_count` 与 `server_count` 区分象征性存在与真实部署。
* **按技术栈细分。**`providers` 与 `cloud_regions` 找出使用特定平台或区域的所有公司。
* **识别扩张。**`is_cross_border_only` 仅返回本土市场以外的部署。

## 限定公司范围

| Key                | Value                                         |
| ------------------ | --------------------------------------------- |
| `domains`          | `["stripe.com"]`                              |
| `domain`           | `"stripe.com"`                                |
| `linkedin_urls`    | `["https://www.linkedin.com/company/stripe"]` |
| `companies`        | `["db26de04-…"]` — `domain_search_id` values  |
| `domain_search_id` | `"db26de04-…"`                                |

也可以不指定公司，这是构建名单的常用方式，例如 `{"target_locations": ["DE"], "providers": ["AWS"]}`。

## 筛选条件

### 服务商、区域与城市

| Key             | Example                          |
| --------------- | -------------------------------- |
| `providers`     | `["AWS", "Cloudflare"]`          |
| `cloud_regions` | `["eu-central-1", "westeurope"]` |
| `cities`        | `["Frankfurt", "Ashburn"]`       |

每个键都接受列表，并有对应的 `exclude_` 版本。`cloud_regions` 与 `cities` 是记录上的数组，因此还支持 `filter_conditions`，可从 OR（任一）切换为 AND（全部）。

### 基础设施位置

| Key                 | Example        |
| ------------------- | -------------- |
| `target_locations`  | `["DE", "SG"]` |
| `company_locations` | `["US"]`       |

`target_locations` 是基础设施运行所在地；`company_locations` 是公司总部所在地。两者不同之处，正是最值得关注的记录。

### 规模

| Key                   | Meaning                             |
| --------------------- | ----------------------------------- |
| `host_count`          | Hosts on this row                   |
| `server_count`        | Distinct IP addresses               |
| `shared_server_count` | Servers shared with other companies |
| `region_count`        | Cloud regions                       |
| `city_count`          | Cities                              |

五项均接受 `[min, max]`，`null` 表示该端不设边界。它们只描述当前这条记录 —— 一个服务商、一个国家。

### 出现时间

| Key                | Example                |
| ------------------ | ---------------------- |
| `first_seen_dates` | `["2026-07-01", null]` |
| `last_seen_dates`  | `[null, "2026-06-30"]` |

两者均接受 ISO 日期的 `[from, to]`，任一端可为 `null`。`first_seen_dates` 用于筛选市场进入；`last_seen_dates` 回答相反的问题。

### 仅跨境

设置 `is_cross_border_only: true` 只保留本土市场以外的部署。总部未知的公司会被排除，而不是猜测。

### 公司整体

| Key                                          | Meaning                           |
| -------------------------------------------- | --------------------------------- |
| `cloud_footprint_host_count`                 | Hosts everywhere                  |
| `cloud_footprint_provider_count`             | Distinct providers used           |
| `cloud_footprint_country_count`              | Countries hosted in               |
| `cloud_footprint_cross_border_country_count` | Countries outside the home market |
| `cloud_footprint_providers`                  | Uses any of these providers       |
| `cloud_footprint_primary_provider`           | Largest provider is one of these  |

带 `cloud_footprint_` 前缀的键描述公司在其所有记录上的整体情况，而非当前这一条。用它筛选公司，同时仍能看到该公司的全部记录。

### 分页与排序

`per_page`、`page` 与 `is_ascending_order` 的行为与其他搜索一致。记录按 `last_seen_at` 倒序排列，最近观察到的在前。

## 记录示例

```json theme={null}
{
  "cloud_footprint_id": "b8fcf5c3-a309-4052-ae8f-fe5706051617",
  "domain_search_id": "db26de04-4131-493a-904b-2c7fda2873ee",
  "provider": "Azure",
  "country_code": "NL",
  "company_country_code": "DK",
  "is_home_market": false,
  "host_count": 437,
  "server_count": 8,
  "shared_server_count": 0,
  "region_count": 1,
  "city_count": 0,
  "cloud_regions": ["westeurope"],
  "cities": null,
  "first_seen_at": "2026-07-27T06:59:38.260Z",
  "last_seen_at": "2026-09-04T12:43:28.724Z",
  "evidence_url": "https://www.pubrio.com/evidence/e458a89952ed1e39e977794327939397",
  "companies": {
    "domain_search_id": "db26de04-4131-493a-904b-2c7fda2873ee",
    "company_name": "Wonderful Sound for All - WSA",
    "domain": "wsa.com",
    "country_code": "DK",
    "logo_url": "https://buckets.pubrio.com/company-logo/…"
  }
}
```

这是一家丹麦公司在荷兰使用 Azure：`company_country_code` 为 `DK`，`country_code` 为 `NL`，因此 `is_home_market` 为 `false`。`evidence_url` 指向佐证该记录的 Pubrio 页面；本土市场不产生扩张信号，因此为 `null`。

## 示例

<Tabs>
  <Tab title="刚进入德国的公司">
    ```bash cURL theme={null}
    curl -X POST https://api.pubrio.com/companies/cloud_footprints/search \
      -H "pubrio-api-key: $PUBRIO_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "target_locations": ["DE"],
        "first_seen_dates": ["2026-08-01", null],
        "is_cross_border_only": true,
        "host_count": [50, null],
        "per_page": 25
      }'
    ```
  </Tab>

  <Tab title="亚洲的重度 AWS 用户">
    ```bash cURL theme={null}
    curl -X POST https://api.pubrio.com/companies/cloud_footprints/search \
      -H "pubrio-api-key: $PUBRIO_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "providers": ["AWS"],
        "target_locations": ["SG", "JP", "IN"],
        "server_count": [10, null],
        "per_page": 25
      }'
    ```
  </Tab>

  <Tab title="布局多个市场的公司">
    ```bash cURL theme={null}
    curl -X POST https://api.pubrio.com/companies/cloud_footprints/search \
      -H "pubrio-api-key: $PUBRIO_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "cloud_footprint_country_count": [5, null],
        "target_locations": ["DE"],
        "host_count": [100, null],
        "per_page": 25
      }'
    ```

    每条记录的 `domain_search_id` 都是一家在至少 5 个国家有部署、且在该国有实际规模的公司。
  </Tab>

  <Tab title="Pilots worth a call">
    ```bash cURL theme={null}
    curl -X POST https://api.pubrio.com/companies/cloud_footprints/search \
      -H "pubrio-api-key: $PUBRIO_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "is_cross_border_only": true,
        "first_seen_dates": ["2026-08-01", null],
        "host_count": [1, 25],
        "per_page": 25
      }'
    ```

    A small, brand-new footprint in a market the company is not headquartered in — the shape of a proof of concept before it becomes a deployment.
  </Tab>
</Tabs>

## 单公司视图

[云足迹洞察](/cn/api-reference/endpoint/companies/cloud_footprints_insights) 接收一个 `domain_search_id`，返回该公司的完整画像：总量、主要服务商、国家与区域、每周新增基础设施序列，以及最新新增项。适用于公司详情页；构建列表请使用搜索。

## 订阅变化

云足迹的变化会以扩张信号的形式出现，因此监控可以在变化发生时推送到 webhook 或邮件。`DNS` 即云足迹信号类型：

```json theme={null}
{
  "signal_types": ["expansions"],
  "signal_filters": [
    { "signal_type": "expansions", "filters": { "tos": ["DE"], "signal_types": ["DNS"], "window_days": 30 } }
  ]
}
```

每次推送都包含 `evidence_url`，且绝不包含原始基础设施明细。参见[设置 webhooks](/cn/developer-guides/setting-up-webhooks)。

## 需要注意

* 在两个国家都有部署的公司会计入两个国家的细分，因此细分之和可能大于总量。这是按市场统计的事实，并非重复计数。
* 当公司总部未知时，`is_cross_border` 为 `null`——表示未知，而非本土。
* 区间使用 `[min, max]`，任一端可为 `null` 表示不设边界。
* 在公司搜索中，`cloud_footprint_country_activity` 可将范围条件限定到单一国家（`{"country":"DE","host_count":[100,null]}`）；扁平的 `cloud_footprint_host_count` 是公司总量，无法表达这一点。

## 相关内容

<CardGroup cols={2}>
  <Card title="云足迹搜索接口" icon="code" href="/cn/api-reference/endpoint/companies/cloud_footprints_search">
    全部参数与响应字段。
  </Card>

  <Card title="云足迹洞察" icon="chart-column" href="/cn/api-reference/endpoint/companies/cloud_footprints_insights">
    单家公司的总量、服务商、区域与每周变化。
  </Card>

  <Card title="云足迹筛选" icon="filter" href="/cn/api-reference/endpoint/companies/search">
    在公司搜索中按云足迹查找公司。
  </Card>

  <Card title="设置 webhooks" icon="webhook" href="/cn/developer-guides/setting-up-webhooks">
    将云足迹变化推送到 webhook 或邮件。
  </Card>
</CardGroup>