概览#
借助 Proxonym API,您可以通过代码管理账户:读取余额和套餐、拉取用量、下载代理列表、编辑 IP 白名单以及管理子用户。Google SERP API(谷歌搜索结果 API)使用独立的主机,以 JSON 格式返回解析好的搜索结果。
基础 URL
https://api.proxonym.com/v1本参考中的路径均相对于基础 URL。所有请求均使用 HTTPS。SERP API 有自己的基础 URL:https://serp.proxonym.com/v1。
OpenAPI 描述文件
账户 API 另提供 OpenAPI 3.1 描述文件,位于 /docs/api/openapi.json,可直接用于客户端生成器、API 工具和 AI 智能体。
版本控制
主版本号包含在路径中。不兼容的变更会以新版本发布。在 v1 内,可能会新增端点、可选参数和响应字段,因此请确保客户端能够忽略无法识别的字段。
约定
- 格式:响应均为 UTF-8 编码的 JSON,响应头带有
Content-Type: application/json;使用format=txt请求的代理列表除外。请求体请以 JSON 格式发送,并带上Content-Type: application/json请求头。 - 状态码:成功时返回
200,创建资源时返回201。失败情况的说明请见错误。 - 时间戳:采用 UTC 时间的 ISO 8601 格式,例如
2026-10-01T09:30:00Z。日期参数可接受完整的时间戳,也可接受2026-09-24这样的日期(按 UTC 零点处理)。 - 流量:以 GB 为单位,用十进制小数表示,例如
17.836。 - ID:带类型前缀的字符串,例如子用户 ID
su_3k9x2m7q。请将其视为不透明的标识符。 - 缺失值:以
null表示,例如,永不过期的流量包会显示"expires_at": null。 - 产品:
residential、mobile、unlimited、isp、datacenter、dedicated和serp。
端点
| 方法 | 路径 | 说明 |
|---|---|---|
GET | /account | 账户、GB 余额和有效套餐 |
GET | /usage | 单个产品在一段时间内的用量 |
GET | /proxies/{product} | 数据中心、ISP 或独享代理的代理列表 |
GET | /whitelist | 列出白名单中的 IP |
POST | /whitelist | 将 IP 添加到白名单 |
DELETE | /whitelist/{ip} | 从白名单中移除 IP |
GET | /sub-users | 列出子用户 |
POST | /sub-users | 创建子用户 |
PATCH | /sub-users/{id} | 更新子用户 |
DELETE | /sub-users/{id} | 删除子用户 |
GET | https://serp.proxonym.com/v1/search | Google 搜索结果(解析后的 JSON) |
第一次调用
在控制台中创建 API 密钥,将其导出为环境变量,然后请求账户信息:
export PROXONYM_API_KEY="your_api_key"
curl https://api.proxonym.com/v1/account \
-H "Authorization: Bearer $PROXONYM_API_KEY"本参考中的示例从 $PROXONYM_API_KEY 读取账户 API 密钥,从 $PROXONYM_SERP_KEY 读取 SERP API 密钥。
身份验证#
账户 API 使用 API 密钥对每个请求进行身份验证,密钥以 Bearer 令牌的形式放在 Authorization 请求头中发送:
Authorization: Bearer <API_KEY>在控制台中创建和撤销密钥。一个密钥对整个账户生效:可以读取用量、下载代理凭据并管理子用户。如果请求中的密钥缺失、格式错误或已被撤销,请求会失败并返回 401:
curl -i https://api.proxonym.com/v1/account \
-H "Authorization: Bearer wrong_key"HTTP/1.1 401 Unauthorized
Content-Type: application/json
{
"error": {
"code": "invalid_api_key",
"message": "The API key is missing, malformed or revoked."
}
}妥善保管密钥
- 只从您自己的服务器调用 API。切勿将密钥放进网页、移动应用或公开代码仓库。
- 从环境变量或密钥管理服务中加载密钥,并确保密钥不会出现在日志中。
- 为每个服务使用单独的密钥,这样撤销其中一个时不会影响其他服务。
- API 密钥不是代理凭据。代理连接使用的是您的代理用户名和密码;请参阅代理身份验证。
轮换密钥
- 在控制台中创建新密钥。
- 将其部署到所有调用 API 的服务。
- 确认使用新密钥的调用均已成功,然后撤销旧密钥。
请定期轮换密钥;如果密钥可能已泄露,请立即撤销。使用已撤销密钥的请求会失败并返回 401。
SERP API 密钥
SERP API 从 X-API-Key 请求头而不是 Authorization 读取密钥。详见 SERP API。
速率限制#
账户 API 每分钟最多接受 60 次请求。每个响应都会告知您当前的额度使用情况:
| 响应头 | 说明 |
|---|---|
X-RateLimit-Limit | 每分钟允许的请求数:60 |
X-RateLimit-Remaining | 当前时间窗口内剩余的请求数 |
Retry-After | 仅出现在 429 响应中:发出下一个请求前需要等待的秒数 |
超出限制时,API 会返回 429:
HTTP/1.1 429 Too Many Requests
Content-Type: application/json
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
Retry-After: 18
{
"error": {
"code": "rate_limited",
"message": "Rate limit of 60 requests per minute exceeded. Retry after 18 seconds."
}
}SERP API 的用量则按套餐的每月请求数计量;请参阅 SERP API。
处理 429
等待 Retry-After 中指定的秒数后再重试。为避免超出限制:
- 缓存变化缓慢的数据,例如代理列表和白名单。
- 每隔几分钟(而不是几秒)轮询一次用量。最细的统计粒度为一小时。
- 将批量任务(例如创建大量子用户)分散到几分钟内完成。
import os
import time
import requests
API = "https://api.proxonym.com/v1"
HEADERS = {"Authorization": f"Bearer {os.environ['PROXONYM_API_KEY']}"}
def api_get(path, params=None, attempts=5):
for _ in range(attempts):
r = requests.get(API + path, headers=HEADERS, params=params, timeout=30)
if r.status_code != 429:
r.raise_for_status()
return r.json()
time.sleep(int(r.headers.get("Retry-After", "5")))
raise RuntimeError(f"{path}: still rate limited after {attempts} attempts")
print(api_get("/usage", {"product": "residential", "granularity": "day"}))错误#
错误使用标准的 HTTP 状态码,并返回一个 JSON 响应体,其中包含稳定、便于程序解析的 code,以及便于阅读的 message:
{
"error": {
"code": "invalid_api_key",
"message": "The API key is missing, malformed or revoked."
}
}请依据 code 编写分支逻辑,切勿依据 message:消息文本可能会调整措辞,而错误码保持稳定。
| 状态 | 错误码 | 含义 | 处理方法 |
|---|---|---|---|
400 | invalid_request | 请求格式错误:JSON 无效、缺少必填参数,或参数值的类型错误 | 修正请求。重试无济于事 |
401 | invalid_api_key | API 密钥缺失、格式错误或已被撤销 | 检查请求头和密钥 |
403 | product_not_active, quota_exceeded | 密钥有效,但该产品没有有效套餐,或 SERP 套餐的请求数已用完 | 购买或续费套餐 |
404 | not_found | 路径、产品、子用户 ID 或白名单 IP 不存在 | 检查路径和 ID |
409 | already_exists | 该 IP 已在白名单中,或已有其他子用户使用该名称 | 使用现有资源,或改用其他值 |
422 | validation_failed, whitelist_full | 某个值格式正确但不被接受(例如 IP 无效、产品未知或日期范围过长),或者白名单名额已全部占用 | 修正该值,或先从白名单中移除一个 IP |
429 | rate_limited | 一分钟内的请求超过 60 次 | 等待 Retry-After 指定的秒数后重试 |
500 | internal_error | 服务端出现意外错误 | 使用指数退避重试 |
只有 429 和 500 值得原样重试。如果 500 持续出现,请记下端点、请求时间和完整的错误响应体:如果您使用的是独享数据中心套餐,可通过工单将这些信息发送给我们的团队。
账户#
读取账户详情、GB 余额和有效套餐。
获取账户信息
GET /account
返回账户信息、GB 余额以及所有有效套餐。已过期的套餐不包含在内。
参数
无。
请求示例
curl https://api.proxonym.com/v1/account \
-H "Authorization: Bearer $PROXONYM_API_KEY"响应示例
{
"id": "acc_7d3f9k2m",
"email": "you@company.example",
"created_at": "2026-03-14T08:21:47Z",
"credit_usd": 245.5,
"balances": {
"residential": {
"gb_remaining": 37.836,
"expires_at": "2026-10-12T14:03:51Z",
"packs": [
{
"gb_purchased": 40,
"gb_remaining": 17.836,
"purchased_at": "2026-09-12T14:03:51Z",
"expires_at": "2026-10-12T14:03:51Z"
},
{
"gb_purchased": 20,
"gb_remaining": 20.0,
"purchased_at": "2026-08-02T16:40:55Z",
"expires_at": null
}
]
},
"datacenter": {
"gb_remaining": 687.52,
"expires_at": "2026-10-18T09:12:40Z"
}
},
"plans": [
{
"id": "pl_4k8d2pqm",
"product": "unlimited",
"bandwidth_mbps": 200,
"gateway": "use.unl.proxonym.com",
"udp": false,
"started_at": "2026-09-25T10:00:00Z",
"expires_at": "2026-10-02T10:00:00Z"
},
{
"id": "pl_3n7q1wza",
"product": "datacenter",
"ips": 1000,
"bandwidth_gb": 1000,
"started_at": "2026-09-18T09:12:40Z",
"expires_at": "2026-10-18T09:12:40Z"
},
{
"id": "pl_6t2r9exb",
"product": "isp",
"ips": 20,
"started_at": "2026-09-20T15:30:00Z",
"expires_at": "2026-10-20T15:30:00Z"
},
{
"id": "pl_2h5j8kvc",
"product": "serp",
"requests_limit": 100000,
"requests_used": 41827,
"started_at": "2026-09-08T11:45:19Z",
"expires_at": "2026-10-08T11:45:19Z"
}
]
}响应字段
| 字段 | 类型 | 说明 |
|---|---|---|
id | string | 账户 ID |
email | string | 账户邮箱地址 |
created_at | string | 账户创建时间 |
credit_usd | number | 以美元计的账户余额,可用于购买套餐。充值金额和奖励额度都会计入其中 |
balances | object | 以产品为键的 GB 余额:residential(移动代理与其共用)和 datacenter(每月带宽额度)。没有余额的产品不会列出 |
balances.{product}.gb_remaining | number 或 null | 剩余流量(GB)。数据中心代理的不限量档位为 null |
balances.{product}.expires_at | string 或 null | 该余额中流量的最早到期时间。如果其中的流量均永不过期,则为 null |
balances.residential.packs[] | array | 每个仍有剩余流量的 GB 流量包对应一个条目,包含 gb_purchased、gb_remaining、purchased_at 和 expires_at(永不过期的流量包此值为 null) |
plans[] | array | 有效套餐。每个套餐都包含 id、product、status(active,静态 IP 准备期间则为 provisioning)、started_at 和 expires_at |
plans[].bandwidth_mbps, gateway, udp | 依次为 integer、string、boolean | 不限流量住宅代理:速度档位、网关服务器,以及 UDP 附加服务是否已开通 |
plans[].ips | integer | ISP、数据中心和独享代理:IP 数量 |
plans[].bandwidth_gb | integer 或 null | 数据中心代理:每月带宽档位(GB),不限量档位为 null |
plans[].requests_limit, requests_used | integer | SERP API:套餐包含的请求数,以及目前已使用的请求数 |
移动流量从住宅代理余额中扣除,因此没有 mobile 余额。住宅代理的 GB 流量包显示在 balances 下,而不是 plans 下。套餐绝不自动续费:请将 expires_at 与当前时间进行比较,以决定何时续费。
示例:余额不足时发出提醒
import os
import requests
r = requests.get(
"https://api.proxonym.com/v1/account",
headers={"Authorization": f"Bearer {os.environ['PROXONYM_API_KEY']}"},
timeout=30,
)
r.raise_for_status()
residential = r.json()["balances"].get("residential")
if residential is None or residential["gb_remaining"] < 5:
left = residential["gb_remaining"] if residential else 0
print(f"Residential balance is low: {left:.1f} GB left. Top up before jobs fail with 402.")用量#
读取您在一段时间内使用的流量或 SERP 请求数。
获取用量
GET /usage
返回单个产品在某一时间范围内的用量,包括总量和时间序列。
参数
| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
product | string,查询参数 | 是 | residential、mobile、unlimited、isp、datacenter、dedicated 或 serp |
from | string,查询参数 | 否 | 时间范围的起点(包含):UTC 时间的 ISO 8601 日期或时间戳。默认值:to 之前 7 天 |
to | string,查询参数 | 否 | 时间范围的终点(不包含)。默认值:当前时间 |
granularity | string,查询参数 | 否 | day(默认)或 hour。时间桶按 UTC 对齐 |
粒度为 day 时,时间范围最长 366 天;粒度为 hour 时,最长 31 天。范围超出上限,或 from 晚于 to 时,将返回 422,错误码为 validation_failed。移动代理的用量单独统计,但从住宅代理余额中扣除。
请求示例
curl -G https://api.proxonym.com/v1/usage \
-H "Authorization: Bearer $PROXONYM_API_KEY" \
-d product=residential \
-d from=2026-09-24 \
-d to=2026-10-01 \
-d granularity=day响应示例
{
"product": "residential",
"granularity": "day",
"from": "2026-09-24T00:00:00Z",
"to": "2026-10-01T00:00:00Z",
"total": {
"traffic_gb": 9.964
},
"series": [
{ "timestamp": "2026-09-24T00:00:00Z", "traffic_gb": 1.204 },
{ "timestamp": "2026-09-25T00:00:00Z", "traffic_gb": 1.587 },
{ "timestamp": "2026-09-26T00:00:00Z", "traffic_gb": 0.932 },
{ "timestamp": "2026-09-27T00:00:00Z", "traffic_gb": 1.411 },
{ "timestamp": "2026-09-28T00:00:00Z", "traffic_gb": 1.876 },
{ "timestamp": "2026-09-29T00:00:00Z", "traffic_gb": 1.309 },
{ "timestamp": "2026-09-30T00:00:00Z", "traffic_gb": 1.645 }
]
}响应字段
| 字段 | 类型 | 说明 |
|---|---|---|
product, granularity | string | 查询所使用的值 |
from, to | string | 解析后的时间范围,以 UTC 时间戳表示 |
total.traffic_gb | number | 该范围内的流量(GB)。仅适用于代理产品 |
total.requests | integer | 该范围内的 SERP API 请求数。仅适用于 serp |
series[] | array | 每个时间桶一个数据点,按时间顺序排列。没有用量的时间桶返回 0 |
series[].timestamp | string | 时间桶的起始时间 |
series[].traffic_gb 或 series[].requests | number 或 integer | 该时间桶内的用量,单位与 total 相同 |
对于 serp,总量和数据点统计的是请求数而不是 GB。例如,按小时查询 ?product=serp&from=2026-09-30T00:00:00Z&to=2026-09-30T03:00:00Z&granularity=hour 会返回:
{
"product": "serp",
"granularity": "hour",
"from": "2026-09-30T00:00:00Z",
"to": "2026-09-30T03:00:00Z",
"total": {
"requests": 1854
},
"series": [
{ "timestamp": "2026-09-30T00:00:00Z", "requests": 612 },
{ "timestamp": "2026-09-30T01:00:00Z", "requests": 587 },
{ "timestamp": "2026-09-30T02:00:00Z", "requests": 655 }
]
}代理列表#
下载分配给您静态套餐的代理。住宅代理、移动代理和不限流量住宅代理没有列表:它们通过网关连接,详见端点与端口。
列出代理
GET /proxies/{product}
返回某个产品下所有有效套餐的全部代理,格式为 JSON,或每行一个代理的纯文本。
参数
| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
product | string,路径参数 | 是 | datacenter、isp 或 dedicated |
format | string,查询参数 | 否 | json(默认)或 txt |
country | string,查询参数 | 否 | 只返回该国家的代理:小写的 ISO 3166-1 alpha-2 代码,例如 us |
请求示例
curl https://api.proxonym.com/v1/proxies/isp \
-H "Authorization: Bearer $PROXONYM_API_KEY"响应示例
此处仅保留三个条目;count 为完整数量。
{
"product": "isp",
"count": 20,
"proxies": [
{
"ip": "198.51.100.61",
"port": 6200,
"username": "isp_k8w2m4",
"password": "Tz6pW1qR8nVb3xYc",
"country": "us",
"location": "New York",
"expires_at": "2026-10-20T15:30:00Z"
},
{
"ip": "198.51.100.62",
"port": 6200,
"username": "isp_k8w2m4",
"password": "Tz6pW1qR8nVb3xYc",
"country": "us",
"location": "New York",
"expires_at": "2026-10-20T15:30:00Z"
},
{
"ip": "198.51.100.63",
"port": 6200,
"username": "isp_k8w2m4",
"password": "Tz6pW1qR8nVb3xYc",
"country": "us",
"location": "New York",
"expires_at": "2026-10-20T15:30:00Z"
}
]
}纯文本格式
使用 format=txt 时,响应为 text/plain,每行一个代理:数据中心代理为 ip:port(其中的端口为 HTTP 端口),ISP 和独享代理为 ip:port:username:password。
curl -G https://api.proxonym.com/v1/proxies/datacenter \
-H "Authorization: Bearer $PROXONYM_API_KEY" \
-d format=txt \
-d country=us198.51.100.23:3129
198.51.100.87:3129
198.51.100.142:3129代理字段
| 字段 | 产品 | 说明 |
|---|---|---|
ip | 全部 | 代理 IP 地址 |
port | ISP、独享 | HTTP 和 SOCKS5 共用的端口 |
http_port, socks5_port | 数据中心 | HTTP 端口 3129,SOCKS5 端口 1081 |
username, password | ISP、独享 | 该代理的凭据 |
country | 全部 | IP 所在国家,以小写的 ISO 3166-1 alpha-2 代码表示 |
location | ISP | 城市或运营商 IP 池,例如 New York 或 Comcast pool |
expires_at | ISP、独享 | 该 IP 的到期时间 |
数据中心代理在 JSON 中的条目形如 {"ip": "198.51.100.23", "http_port": 3129, "socks5_port": 1081, "country": "us"}。如果该产品没有有效套餐,API 会返回 403,错误码为 product_not_active。对于没有列表的产品(例如 residential),则返回 404:
{
"error": {
"code": "not_found",
"message": "No proxy list for product residential. Lists exist for datacenter, isp and dedicated."
}
}白名单#
白名单允许机器无需凭据即可连接您的共享数据中心代理。每个共享数据中心套餐包含 3 个名额,白名单条目对您的所有数据中心 IP 生效。背景知识:文档中的 IP 白名单。
列出白名单 IP
GET /whitelist
参数
无。
请求示例
curl https://api.proxonym.com/v1/whitelist \
-H "Authorization: Bearer $PROXONYM_API_KEY"响应示例
{
"limit": 3,
"ips": [
{ "ip": "192.0.2.10", "created_at": "2026-09-18T09:20:11Z" },
{ "ip": "192.0.2.57", "created_at": "2026-09-22T17:02:45Z" }
]
}limit 是您账户的名额数量,ips 列出各条目,按添加时间从早到晚排列。
添加 IP
POST /whitelist
参数
| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
ip | string,请求体参数 | 是 | 要连接的机器的公网 IP 地址,例如 192.0.2.44 |
请求示例
curl -X POST https://api.proxonym.com/v1/whitelist \
-H "Authorization: Bearer $PROXONYM_API_KEY" \
-H "Content-Type: application/json" \
-d '{"ip": "192.0.2.44"}'响应示例
状态码 201:
{
"ip": "192.0.2.44",
"created_at": "2026-10-01T09:30:00Z"
}如果 IP 已在名单中,会返回 409,错误码为 already_exists;如果地址无效,则返回 422,错误码为 validation_failed。当所有名额都已占用时,API 返回 422:
{
"error": {
"code": "whitelist_full",
"message": "All 3 whitelist slots are in use. Remove an IP before adding another."
}
}移除 IP
DELETE /whitelist/{ip}
参数
| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
ip | string,路径参数 | 是 | 要移除的白名单 IP |
请求示例
curl -X DELETE https://api.proxonym.com/v1/whitelist/192.0.2.10 \
-H "Authorization: Bearer $PROXONYM_API_KEY"响应示例
{
"ip": "192.0.2.10",
"deleted": true
}此后,来自该 IP 且未携带凭据的请求会失败并返回 407。如果 IP 不在名单中,则返回 404,错误码为 not_found。
子用户#
子用户是您账户下额外的代理凭据,每个子用户都可以设置可选的流量上限。子用户的流量从您的账户余额中扣除。背景知识:文档中的子用户。
子用户对象
{
"id": "su_3k9x2m7q",
"name": "price-monitor",
"username": "sub_k3v9q2xd",
"password": "Qm7vT2xK9pLr4sWz",
"traffic_limit_gb": 25,
"traffic_used_gb": 6.412,
"status": "active",
"created_at": "2026-09-14T08:05:22Z"
}| 字段 | 类型 | 说明 |
|---|---|---|
id | string | 子用户 ID,用于 API 路径中 |
name | string | 您为子用户设置的标签,在账户内唯一 |
username | string | 系统生成的代理用户名。支持与主用户名相同的选项,例如 sub_k3v9q2xd-country-us-session-a7k2 |
password | string | 系统生成的代理密码 |
traffic_limit_gb | number 或 null | 最大流量(GB)。null 表示除账户余额外不设上限 |
traffic_used_gb | number | 目前已使用的流量(GB) |
status | string | active 或 disabled。代理会对已停用的子用户返回 407 |
created_at | string | 子用户的创建时间 |
当 traffic_used_gb 达到 traffic_limit_gb 时,该子用户的请求会失败并返回 402,直到您提高上限为止。
列出子用户
GET /sub-users
参数
无。
请求示例
curl https://api.proxonym.com/v1/sub-users \
-H "Authorization: Bearer $PROXONYM_API_KEY"响应示例
{
"sub_users": [
{
"id": "su_3k9x2m7q",
"name": "price-monitor",
"username": "sub_k3v9q2xd",
"password": "Qm7vT2xK9pLr4sWz",
"traffic_limit_gb": 25,
"traffic_used_gb": 6.412,
"status": "active",
"created_at": "2026-09-14T08:05:22Z"
},
{
"id": "su_8d1f4n6p",
"name": "qa-team",
"username": "sub_p8w2n5tf",
"password": "Hx4bN9cR2vLq7mKs",
"traffic_limit_gb": null,
"traffic_used_gb": 1.207,
"status": "disabled",
"created_at": "2026-09-20T13:47:09Z"
}
]
}创建子用户
POST /sub-users
参数
| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
name | string,请求体参数 | 是 | 1 到 64 个字符的标签,在账户内唯一 |
traffic_limit_gb | number 或 null,请求体参数 | 否 | 流量上限(GB),必须大于 0。省略或传入 null 表示不设上限 |
请求示例
curl -X POST https://api.proxonym.com/v1/sub-users \
-H "Authorization: Bearer $PROXONYM_API_KEY" \
-H "Content-Type: application/json" \
-d '{"name": "eu-crawler", "traffic_limit_gb": 10}'响应示例
状态码 201,并返回系统生成的用户名和密码:
{
"id": "su_6v2c8r1t",
"name": "eu-crawler",
"username": "sub_t6r1y8bw",
"password": "Lp3sV8kQ1zXn6wRd",
"traffic_limit_gb": 10,
"traffic_used_gb": 0,
"status": "active",
"created_at": "2026-10-01T09:30:00Z"
}如果名称已被占用,会返回 409,错误码为 already_exists。新凭据可立即在网关上使用,并支持常规的用户名选项:
curl -x http://gw.proxonym.com:8000 \
-U "sub_t6r1y8bw-country-de:Lp3sV8kQ1zXn6wRd" \
https://api.ipify.org更新子用户
PATCH /sub-users/{id}
只需发送要修改的字段。
参数
| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
id | string,路径参数 | 是 | 子用户 ID |
name | string,请求体参数 | 否 | 新标签,1 到 64 个字符 |
traffic_limit_gb | number 或 null,请求体参数 | 否 | 新的流量上限(GB),传入 null 表示不设上限 |
status | string,请求体参数 | 否 | active 或 disabled |
reset_password | boolean,请求体参数 | 否 | 传入 true 将生成新密码,旧密码立即失效 |
请求示例
提高流量上限并重置密码:
curl -X PATCH https://api.proxonym.com/v1/sub-users/su_3k9x2m7q \
-H "Authorization: Bearer $PROXONYM_API_KEY" \
-H "Content-Type: application/json" \
-d '{"traffic_limit_gb": 40, "reset_password": true}'响应示例
{
"id": "su_3k9x2m7q",
"name": "price-monitor",
"username": "sub_k3v9q2xd",
"password": "Wd5nX8qT3vKz6pRm",
"traffic_limit_gb": 40,
"traffic_used_gb": 6.412,
"status": "active",
"created_at": "2026-09-14T08:05:22Z"
}删除子用户
DELETE /sub-users/{id}
删除子用户,其凭据立即失效。该子用户已使用的流量仍会保留在您的用量记录中。如果只想暂停子用户,请将其 status 设为 disabled。
参数
| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
id | string,路径参数 | 是 | 子用户 ID |
请求示例
curl -X DELETE https://api.proxonym.com/v1/sub-users/su_8d1f4n6p \
-H "Authorization: Bearer $PROXONYM_API_KEY"响应示例
{
"id": "su_8d1f4n6p",
"deleted": true
}如果 ID 不存在,则返回 404,错误码为 not_found。
SERP API#
Google SERP API(谷歌搜索结果 API)可针对任意国家或城市、桌面端或移动端,以解析后的 JSON 格式返回 Google 搜索结果。每次调用返回一页结果,并计为套餐中的一次请求。
搜索
GET https://serp.proxonym.com/v1/search
在 X-API-Key 请求头中发送您从控制台获取的 SERP API 密钥。错误格式与账户 API 相同:密钥缺失或无效时返回 401,错误码为 invalid_api_key;没有有效的 SERP 套餐时,API 返回 403,错误码为 product_not_active;套餐的请求数用完后,返回 403,错误码为 quota_exceeded。
参数
| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
q | string | 是 | 搜索查询词,需经过 URL 编码 |
gl | string | 否 | 搜索结果所属的国家,以小写的 ISO 3166-1 alpha-2 代码表示。默认值为 us |
hl | string | 否 | 界面语言代码,例如 en 或 de。默认值为 en |
location | string | 否 | 城市级位置,格式为 City,Region,例如 Chicago,Illinois。所填地点须位于 gl 指定的国家内 |
device | string | 否 | desktop(默认)或 mobile |
page | integer | 否 | 结果页码,从 1(默认)开始。每一页都是一次单独的请求 |
请求示例
curl -G https://serp.proxonym.com/v1/search \
-H "X-API-Key: $PROXONYM_SERP_KEY" \
--data-urlencode "q=running shoes" \
-d gl=us \
-d hl=en \
--data-urlencode "location=Chicago,Illinois" \
-d device=desktop \
-d page=1使用 Python 发送同样的请求:
import os
import requests
params = {
"q": "running shoes",
"gl": "us",
"hl": "en",
"location": "Chicago,Illinois",
"device": "desktop",
"page": 1,
}
r = requests.get(
"https://serp.proxonym.com/v1/search",
headers={"X-API-Key": os.environ["PROXONYM_SERP_KEY"]},
params=params,
timeout=60,
)
r.raise_for_status()
for result in r.json()["organic_results"]:
print(result["position"], result["title"], result["link"])响应示例
以下内容已做删减:
{
"search_parameters": {
"q": "running shoes",
"gl": "us",
"hl": "en",
"location": "Chicago,Illinois",
"device": "desktop",
"page": 1
},
"organic_results": [
{
"position": 1,
"title": "Running Shoes for Men and Women | Stride Supply",
"link": "https://www.stridesupply.example/running-shoes",
"snippet": "Shop road and trail running shoes in every size. Compare cushioning, drop and weight across 40 models."
},
{
"position": 2,
"title": "How to Choose Running Shoes: A Buyer's Guide",
"link": "https://www.runnersdesk.example/guides/choosing-running-shoes",
"snippet": "Gait, arch type and weekly mileage matter more than brand. Here is how to narrow the field."
},
{
"position": 3,
"title": "Running Shoes in Chicago, IL | Lakeshore Run Co.",
"link": "https://www.lakeshorerun.example/",
"snippet": "Gait analysis and fittings at our Lincoln Park store, open 7 days a week."
}
],
"ads": [
{
"position": 1,
"title": "Running Shoes Sale | Up to 40% Off",
"link": "https://www.shoeoutlet.example/running",
"snippet": "Last season's models in stock. Ships in 1 business day."
}
],
"people_also_ask": [
{
"question": "How often should you replace running shoes?",
"snippet": "Many runners replace their shoes every 300 to 500 miles.",
"link": "https://www.runnersdesk.example/guides/shoe-lifespan"
}
],
"related_searches": [
{ "query": "running shoes near me" },
{ "query": "trail running shoes" },
{ "query": "running shoes for flat feet" }
],
"local_results": [
{
"position": 1,
"title": "Lakeshore Run Co.",
"address": "2312 N Lincoln Ave, Chicago, IL",
"phone": "(312) 555-0142"
},
{
"position": 2,
"title": "Windy City Running",
"address": "845 W Randolph St, Chicago, IL",
"phone": "(312) 555-0187"
}
]
}响应字段
| 字段 | 类型 | 说明 |
|---|---|---|
search_parameters | object | 本次搜索的参数,已填入默认值 |
organic_results[] | array | 按页面顺序排列的自然搜索结果 |
organic_results[].position | integer | 在页面上的排名,从 1 开始 |
organic_results[].title | string | 结果标题 |
organic_results[].link | string | 结果 URL |
organic_results[].snippet | string | 标题下方显示的文字 |
ads[] | array | 付费结果(广告),包含 position、title、link 和 snippet |
people_also_ask[] | array | “相关问题”(People also ask)模块中的问题,包含 question、snippet 和 link |
related_searches[] | array | 相关搜索,每项包含 query |
local_results[] | array | 本地商家列表(Local Pack)结果,包含 position、title、address 和 phone |
页面上未出现的模块会以空数组返回。如需长期跟踪排名,请参阅搜索排名跟踪使用场景,以及我们的指南:如何抓取 Google 搜索结果。