# API

API 执行的搜索与网站完全相同，并以数据形式返回结果：默认为 JSON，也支持 XML、CSV、TSV、NDJSON 和纯文本。搜索只读取数据；API 会创建、重命名和删除的只有您自己的[域名集](https://zh.publicwww.com/docs/api/clusters/)。

基础 URL `https://api.publicwww.com`

## 一条命令即可上手

通过 API 搜索和使用域名集需要付费套餐；免费账户的令牌只能读取 `/v1/account`。

```
export PUBLICWWW_KEY=...
curl -H "Authorization: Bearer $PUBLICWWW_KEY" \
     "https://api.publicwww.com/v1/search?query=%22angular.min.js%22&per_page=3"
```

```
{
  "query": "\"angular.min.js\"",
  "page": 1,
  "per_page": 3,
  "total": 70907,
  "total_pages": 23636,
  "returned": 3,
  "truncated": false,
  "index_complete": true,
  "took_ms": 2,
  "results": [
    { "domain": "imgbox.com", "url": "https://imgbox.com/", "rank": 4187, "ranked": true }
  ]
}
```

## 接口

| 接口 | 方法 | 功能 |
| --- | --- | --- |
| `/v1/search` | GET, POST | 执行搜索。参见[参数](https://zh.publicwww.com/docs/api/requests/)、[格式](https://zh.publicwww.com/docs/api/formats/)。 |
| `/v1/account` | GET | 套餐、配额与限额。不消耗任何配额，不计入速率限制，任何账户都可使用。 |
| `/v1/clusters` | GET, POST | 已保存的网站列表：可由搜索或列表创建、相互组合，从网页源代码中提取联系方式和各类 ID，并生成特征码。参见[域名集](https://zh.publicwww.com/docs/api/clusters/)。 |
| `/mcp` | POST | 面向 AI 助手和智能体的 [MCP 服务器](https://zh.publicwww.com/docs/mcp/)：以工具形式提供搜索和域名集，使用同一个令牌。 |
| `/` | GET | API 的自描述信息，包括错误码。无需令牌。 |
| `/openapi.json` | GET | 以 [OpenAPI 3.1 描述](https://api.publicwww.com/openapi.json)形式提供的同样内容，可导入 Postman、n8n、Make、Power Automate 等工具。无需令牌。 |

没有单独的导出接口：批量获取时，向 `/v1/search` 请求较大的 `per_page`，上限为 `/v1/account` 中的 `max_per_page`；响应会边生成边以流式返回。

限额响应头：`X-Requests-*` 统计每分钟的请求数，`X-RateLimit-*` 统计每天的搜索次数，`X-Snippets-*` 统计每天的代码片段请求次数；哪些响应带有这些响应头，见[限制](https://zh.publicwww.com/docs/api/limits/)。

搜索的总数在任何格式下也会放在响应头中：`X-Total-Results`、`X-Returned-Results`、`X-Truncated` 和 `X-Index-Complete`； CSV、TSV 和 TXT 的正文里没有位置放它们，所以只在响应头中（见[格式](https://zh.publicwww.com/docs/api/formats/)）。

## 我们的承诺

- **绝不悄悄削减结果。**每日配额用完后，网站会默默退回免费版的限制；而 API 会返回 `429 quota_exceeded`，而不是一个看似完整、实则不全的结果。
- **不完整的结果会明确标出**：在所有格式中，响应体里都有 `truncated`，响应头里都有 `X-Truncated`。
- **无排名的网站会如实说明**：返回 `rank: null` 和 `ranked: false`，绝不使用可能被客户端误认为真实（且非常大）排名的内部占位值。
- **告诉您等待，好过让您干等。**请求过快时，会立即返回带有 `Retry-After` 的响应，而不是一直占用连接。

## 获取令牌

在您的[个人中心](https://zh.publicwww.com/profile/api)生成令牌，或让应用通过 [OAuth 2.1](https://zh.publicwww.com/docs/api/authentication/#oauth) 为您获取。在网站上，免费账户可以在其限额内使用搜索和域名集；各套餐见[价格](https://zh.publicwww.com/prices.html)。

API 供您自己的代码使用，例如脚本、服务器或应用程序。网页无法在浏览器中调用它：浏览器会拦截这类调用，而且令牌也会暴露在页面中。

## 详细说明

- [身份验证](https://zh.publicwww.com/docs/api/authentication/)：请求头中的令牌，以及 OAuth 2.1。
- [发送请求](https://zh.publicwww.com/docs/api/requests/)：`/v1/search` 的查询及其参数，GET 和 POST 均可。
- [响应格式](https://zh.publicwww.com/docs/api/formats/)：JSON、NDJSON、XML、CSV、TSV 和纯文本，通过 `format=` 选择。
- [配额与速率限制](https://zh.publicwww.com/docs/api/limits/)：每天的搜索次数、每分钟的请求数，以及报告这两项的响应头。
- [错误](https://zh.publicwww.com/docs/api/errors/)：所有错误都采用同一结构，并带有固定不变的错误码。
- [域名集](https://zh.publicwww.com/docs/api/clusters/)：已保存的网站列表：创建、组合、提取值、生成特征码。
- [代码示例](https://zh.publicwww.com/docs/api/examples/)：用多种语言实现同一个搜索，包括逐页获取结果，以及在被要求等待时等待。
- [Google Sheets](https://zh.publicwww.com/docs/api/sheets/)：把搜索带进电子表格的公式和菜单。
- [Clay](https://zh.publicwww.com/docs/api/clay/)：通过 Clay 的 HTTP API，使用您的令牌接入 PublicWWW。
- [旧版导出 URL](https://zh.publicwww.com/docs/api/legacy/)：通过 `?export=` 下载，保持不变。

Source: https://zh.publicwww.com/docs/api/
