新品不限流量住宅代理:固定价格,流量不计量。 低至 $33.25/天

API 参考

Proxonym API 参考

通过 JSON REST API 管理余额、用量、代理列表、IP 白名单和子用户,并通过 SERP API 获取解析好的 Google 搜索结果。

  • 基础 URLhttps://api.proxonym.com/v1
  • 身份验证Authorization: Bearer API_KEY
  • 格式JSON
  • 速率限制60 / min

概览#

借助 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}删除子用户
GEThttps://serp.proxonym.com/v1/searchGoogle 搜索结果(解析后的 JSON)

第一次调用

在控制台中创建 API 密钥,将其导出为环境变量,然后请求账户信息:

Shell
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:

Shell
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 密钥不是代理凭据。代理连接使用的是您的代理用户名和密码;请参阅代理身份验证。

轮换密钥

  1. 在控制台中创建新密钥。
  2. 将其部署到所有调用 API 的服务。
  3. 确认使用新密钥的调用均已成功,然后撤销旧密钥。

请定期轮换密钥;如果密钥可能已泄露,请立即撤销。使用已撤销密钥的请求会失败并返回 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 中指定的秒数后再重试。为避免超出限制:

  • 缓存变化缓慢的数据,例如代理列表和白名单。
  • 每隔几分钟(而不是几秒)轮询一次用量。最细的统计粒度为一小时。
  • 将批量任务(例如创建大量子用户)分散到几分钟内完成。
Python
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:

JSON
{
  "error": {
    "code": "invalid_api_key",
    "message": "The API key is missing, malformed or revoked."
  }
}

请依据 code 编写分支逻辑,切勿依据 message:消息文本可能会调整措辞,而错误码保持稳定。

状态错误码含义处理方法
400invalid_request请求格式错误:JSON 无效、缺少必填参数,或参数值的类型错误修正请求。重试无济于事
401invalid_api_keyAPI 密钥缺失、格式错误或已被撤销检查请求头和密钥
403product_not_active, quota_exceeded密钥有效,但该产品没有有效套餐,或 SERP 套餐的请求数已用完购买或续费套餐
404not_found路径、产品、子用户 ID 或白名单 IP 不存在检查路径和 ID
409already_exists该 IP 已在白名单中,或已有其他子用户使用该名称使用现有资源,或改用其他值
422validation_failed, whitelist_full某个值格式正确但不被接受(例如 IP 无效、产品未知或日期范围过长),或者白名单名额已全部占用修正该值,或先从白名单中移除一个 IP
429rate_limited一分钟内的请求超过 60 次等待 Retry-After 指定的秒数后重试
500internal_error服务端出现意外错误使用指数退避重试

只有 429 和 500 值得原样重试。如果 500 持续出现,请记下端点、请求时间和完整的错误响应体:如果您使用的是独享数据中心套餐,可通过工单将这些信息发送给我们的团队。

账户#

读取账户详情、GB 余额和有效套餐。

获取账户信息

GET /account

返回账户信息、GB 余额以及所有有效套餐。已过期的套餐不包含在内。

参数

无。

请求示例

Shell
curl https://api.proxonym.com/v1/account \
  -H "Authorization: Bearer $PROXONYM_API_KEY"

响应示例

JSON
{
  "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"
    }
  ]
}

响应字段

字段类型说明
idstring账户 ID
emailstring账户邮箱地址
created_atstring账户创建时间
credit_usdnumber以美元计的账户余额,可用于购买套餐。充值金额和奖励额度都会计入其中
balancesobject以产品为键的 GB 余额:residential(移动代理与其共用)和 datacenter(每月带宽额度)。没有余额的产品不会列出
balances.{product}.gb_remainingnumber 或 null剩余流量(GB)。数据中心代理的不限量档位为 null
balances.{product}.expires_atstring 或 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[].ipsintegerISP、数据中心和独享代理:IP 数量
plans[].bandwidth_gbinteger 或 null数据中心代理:每月带宽档位(GB),不限量档位为 null
plans[].requests_limit, requests_usedintegerSERP API:套餐包含的请求数,以及目前已使用的请求数

移动流量从住宅代理余额中扣除,因此没有 mobile 余额。住宅代理的 GB 流量包显示在 balances 下,而不是 plans 下。套餐绝不自动续费:请将 expires_at 与当前时间进行比较,以决定何时续费。

示例:余额不足时发出提醒

Python
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

返回单个产品在某一时间范围内的用量,包括总量和时间序列。

参数

名称类型必填说明
productstring,查询参数是residential、mobile、unlimited、isp、datacenter、dedicated 或 serp
fromstring,查询参数否时间范围的起点(包含):UTC 时间的 ISO 8601 日期或时间戳。默认值:to 之前 7 天
tostring,查询参数否时间范围的终点(不包含)。默认值:当前时间
granularitystring,查询参数否day(默认)或 hour。时间桶按 UTC 对齐

粒度为 day 时,时间范围最长 366 天;粒度为 hour 时,最长 31 天。范围超出上限,或 from 晚于 to 时,将返回 422,错误码为 validation_failed。移动代理的用量单独统计,但从住宅代理余额中扣除。

请求示例

Shell
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

响应示例

JSON
{
  "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, granularitystring查询所使用的值
from, tostring解析后的时间范围,以 UTC 时间戳表示
total.traffic_gbnumber该范围内的流量(GB)。仅适用于代理产品
total.requestsinteger该范围内的 SERP API 请求数。仅适用于 serp
series[]array每个时间桶一个数据点,按时间顺序排列。没有用量的时间桶返回 0
series[].timestampstring时间桶的起始时间
series[].traffic_gb 或 series[].requestsnumber 或 integer该时间桶内的用量,单位与 total 相同

对于 serp,总量和数据点统计的是请求数而不是 GB。例如,按小时查询 ?product=serp&from=2026-09-30T00:00:00Z&to=2026-09-30T03:00:00Z&granularity=hour 会返回:

JSON
{
  "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,或每行一个代理的纯文本。

参数

名称类型必填说明
productstring,路径参数是datacenter、isp 或 dedicated
formatstring,查询参数否json(默认)或 txt
countrystring,查询参数否只返回该国家的代理:小写的 ISO 3166-1 alpha-2 代码,例如 us

请求示例

Shell
curl https://api.proxonym.com/v1/proxies/isp \
  -H "Authorization: Bearer $PROXONYM_API_KEY"

响应示例

此处仅保留三个条目;count 为完整数量。

JSON
{
  "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。

Shell
curl -G https://api.proxonym.com/v1/proxies/datacenter \
  -H "Authorization: Bearer $PROXONYM_API_KEY" \
  -d format=txt \
  -d country=us
文本
198.51.100.23:3129
198.51.100.87:3129
198.51.100.142:3129

代理字段

字段产品说明
ip全部代理 IP 地址
portISP、独享HTTP 和 SOCKS5 共用的端口
http_port, socks5_port数据中心HTTP 端口 3129,SOCKS5 端口 1081
username, passwordISP、独享该代理的凭据
country全部IP 所在国家,以小写的 ISO 3166-1 alpha-2 代码表示
locationISP城市或运营商 IP 池,例如 New York 或 Comcast pool
expires_atISP、独享该 IP 的到期时间

数据中心代理在 JSON 中的条目形如 {"ip": "198.51.100.23", "http_port": 3129, "socks5_port": 1081, "country": "us"}。如果该产品没有有效套餐,API 会返回 403,错误码为 product_not_active。对于没有列表的产品(例如 residential),则返回 404:

JSON
{
  "error": {
    "code": "not_found",
    "message": "No proxy list for product residential. Lists exist for datacenter, isp and dedicated."
  }
}

白名单#

白名单允许机器无需凭据即可连接您的共享数据中心代理。每个共享数据中心套餐包含 3 个名额,白名单条目对您的所有数据中心 IP 生效。背景知识:文档中的 IP 白名单。

列出白名单 IP

GET /whitelist

参数

无。

请求示例

Shell
curl https://api.proxonym.com/v1/whitelist \
  -H "Authorization: Bearer $PROXONYM_API_KEY"

响应示例

JSON
{
  "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

参数

名称类型必填说明
ipstring,请求体参数是要连接的机器的公网 IP 地址,例如 192.0.2.44

请求示例

Shell
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:

JSON
{
  "ip": "192.0.2.44",
  "created_at": "2026-10-01T09:30:00Z"
}

如果 IP 已在名单中,会返回 409,错误码为 already_exists;如果地址无效,则返回 422,错误码为 validation_failed。当所有名额都已占用时,API 返回 422:

JSON
{
  "error": {
    "code": "whitelist_full",
    "message": "All 3 whitelist slots are in use. Remove an IP before adding another."
  }
}

移除 IP

DELETE /whitelist/{ip}

参数

名称类型必填说明
ipstring,路径参数是要移除的白名单 IP

请求示例

Shell
curl -X DELETE https://api.proxonym.com/v1/whitelist/192.0.2.10 \
  -H "Authorization: Bearer $PROXONYM_API_KEY"

响应示例

JSON
{
  "ip": "192.0.2.10",
  "deleted": true
}

此后,来自该 IP 且未携带凭据的请求会失败并返回 407。如果 IP 不在名单中,则返回 404,错误码为 not_found。

子用户#

子用户是您账户下额外的代理凭据,每个子用户都可以设置可选的流量上限。子用户的流量从您的账户余额中扣除。背景知识:文档中的子用户。

子用户对象

JSON
{
  "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"
}
字段类型说明
idstring子用户 ID,用于 API 路径中
namestring您为子用户设置的标签,在账户内唯一
usernamestring系统生成的代理用户名。支持与主用户名相同的选项,例如 sub_k3v9q2xd-country-us-session-a7k2
passwordstring系统生成的代理密码
traffic_limit_gbnumber 或 null最大流量(GB)。null 表示除账户余额外不设上限
traffic_used_gbnumber目前已使用的流量(GB)
statusstringactive 或 disabled。代理会对已停用的子用户返回 407
created_atstring子用户的创建时间

当 traffic_used_gb 达到 traffic_limit_gb 时,该子用户的请求会失败并返回 402,直到您提高上限为止。

列出子用户

GET /sub-users

参数

无。

请求示例

Shell
curl https://api.proxonym.com/v1/sub-users \
  -H "Authorization: Bearer $PROXONYM_API_KEY"

响应示例

JSON
{
  "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

参数

名称类型必填说明
namestring,请求体参数是1 到 64 个字符的标签,在账户内唯一
traffic_limit_gbnumber 或 null,请求体参数否流量上限(GB),必须大于 0。省略或传入 null 表示不设上限

请求示例

Shell
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,并返回系统生成的用户名和密码:

JSON
{
  "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。新凭据可立即在网关上使用,并支持常规的用户名选项:

Shell
curl -x http://gw.proxonym.com:8000 \
  -U "sub_t6r1y8bw-country-de:Lp3sV8kQ1zXn6wRd" \
  https://api.ipify.org

更新子用户

PATCH /sub-users/{id}

只需发送要修改的字段。

参数

名称类型必填说明
idstring,路径参数是子用户 ID
namestring,请求体参数否新标签,1 到 64 个字符
traffic_limit_gbnumber 或 null,请求体参数否新的流量上限(GB),传入 null 表示不设上限
statusstring,请求体参数否active 或 disabled
reset_passwordboolean,请求体参数否传入 true 将生成新密码,旧密码立即失效

请求示例

提高流量上限并重置密码:

Shell
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}'

响应示例

JSON
{
  "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。

参数

名称类型必填说明
idstring,路径参数是子用户 ID

请求示例

Shell
curl -X DELETE https://api.proxonym.com/v1/sub-users/su_8d1f4n6p \
  -H "Authorization: Bearer $PROXONYM_API_KEY"

响应示例

JSON
{
  "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。

参数

名称类型必填说明
qstring是搜索查询词,需经过 URL 编码
glstring否搜索结果所属的国家,以小写的 ISO 3166-1 alpha-2 代码表示。默认值为 us
hlstring否界面语言代码,例如 en 或 de。默认值为 en
locationstring否城市级位置,格式为 City,Region,例如 Chicago,Illinois。所填地点须位于 gl 指定的国家内
devicestring否desktop(默认)或 mobile
pageinteger否结果页码,从 1(默认)开始。每一页都是一次单独的请求

请求示例

Shell
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 发送同样的请求:

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"])

响应示例

以下内容已做删减:

JSON
{
  "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_parametersobject本次搜索的参数,已填入默认值
organic_results[]array按页面顺序排列的自然搜索结果
organic_results[].positioninteger在页面上的排名,从 1 开始
organic_results[].titlestring结果标题
organic_results[].linkstring结果 URL
organic_results[].snippetstring标题下方显示的文字
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 搜索结果。