API
API 执行的搜索与网站完全相同,并以数据形式返回结果:默认为 JSON,也支持 XML、CSV、TSV、NDJSON 和纯文本。搜索只读取数据;API 会创建、重命名和删除的只有您自己的域名集。
基础 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 | 执行搜索。参见参数、格式。 |
/v1/account |
GET | 套餐、配额与限额。不消耗任何配额,不计入速率限制,任何账户都可使用。 |
/v1/clusters |
GET, POST | 已保存的网站列表:可由搜索或列表创建、相互组合,从网页源代码中提取联系方式和各类 ID,并生成特征码。参见域名集。 |
/mcp |
POST | 面向 AI 助手和智能体的 MCP 服务器:以工具形式提供搜索和域名集,使用同一个令牌。 |
/ |
GET | API 的自描述信息,包括错误码。无需令牌。 |
/openapi.json |
GET | 以 OpenAPI 3.1 描述形式提供的同样内容,可导入 Postman、n8n、Make、Power Automate 等工具。无需令牌。 |
没有单独的导出接口。批量获取就是使用较大 per_page 的 /v1/search,上限取决于套餐,即 /v1/account 中的 max_per_page;响应会边生成边以流式返回。
每个响应都带有两组限额响应头:X-Requests-* 是每分钟的请求数,X-RateLimit-* 是每天的搜索次数,详见限制。
我们的承诺
-
绝不悄悄削减结果。在浏览器中,每日配额用完后,网站会默默退回免费版的限制,显示更少的结果。脚本察觉不到这种变化,因此在 API 中这会直接返回错误
429 quota_exceeded,而不是返回一个看似完整、实则不全的结果。 -
不完整的结果会明确标出:在所有格式中,响应体里都有
truncated,响应头里都有X-Truncated。 -
无排名的网站会如实说明:返回
rank: null和ranked: false,绝不使用可能被客户端误认为真实(且非常大)排名的内部占位值。 -
告诉您等待,好过让您干等。请求过快时,会立即返回带有
Retry-After的响应,而不是一直占用连接。
获取令牌
在您的个人中心生成令牌,或让应用通过 OAuth 2.1 为您获取。通过 API 使用搜索和域名集需要付费套餐;在网站上,免费账户也可以在其限额内使用,详见价格。调用旧版 ?export= URL 的现有脚本无需修改即可继续使用,详见旧版导出 URL。
详细说明
- 身份验证:请求头中的令牌,以及 OAuth 2.1。
- 发送请求:
/v1/search的查询及其参数,GET 和 POST 均可。 - 响应格式:JSON、NDJSON、XML、CSV、TSV 和纯文本,通过
format=选择。 - 配额与速率限制:每天的搜索次数、每分钟的请求数,以及报告这两项的响应头。
- 错误:所有错误都采用同一结构,并带有固定不变的错误码。
- 域名集:已保存的网站列表:创建、组合、提取值、生成特征码。
- 代码示例:用多种语言实现同一个搜索,包括逐页获取结果,以及在被要求等待时等待。
- Google Sheets:把搜索带进电子表格的公式和菜单。
- Clay:通过 Clay 的 HTTP API,使用您的令牌接入 PublicWWW。
- 旧版导出 URL:通过
?export=下载,保持不变。