# SERP API 参考：GET /search 和 GET /credits

> SerpCrypto SERP API 参考：GET /search 参数、引擎、默认值、响应区块、错误码以及 GET /credits，附 curl、Python 和 Node.js 示例。

- URL: https://serpcrypto.com/zh/docs/search/
- 最后更新: 2026-10-22
- 发布者: SerpCrypto (https://serpcrypto.com)

SerpCrypto API 版本 1 的全部参数、默认值和错误码。基础 URL：`https://serpcrypto.com/api/v1`。所有请求都使用 HTTPS；所有响应都是 UTF-8 编码的 JSON。

**快速回答 — SerpCrypto 搜索 endpoint 接受哪些参数？**

`GET https://serpcrypto.com/api/v1/search` 接受一个必填参数 `q`，以及九个可选参数：`engine`、`gl`、`hl`、`location`、`google_domain`、`device`、`page`、`safe` 和 `period`。**SerpCrypto** 返回 JSON，在全部 6 个引擎上每次成功搜索扣 1 积分；出错免费。积分包 10,000 次搜索 起售价 US$7.50，用加密货币支付，无需 KYC。

## 如何通过身份验证？

用以下两种方式之一发送你的密钥。推荐方式是用 header `Authorization: Bearer YOUR_KEY`。另一种是用查询参数 `api_key=YOUR_KEY`，适合在浏览器标签页里快速测试。

密钥缺失、错误或已吊销会返回 `401 invalid_api_key`，且不扣费。你可以在 dashboard 中随时创建和撤销的 API 密钥，这样你可以为每个脚本或服务器分配各自的密钥，吊销其中一个而不影响其他。

## 执行一次搜索

`GET /api/v1/search`

在所选引擎上执行一次搜索，并将结果页以 JSON 返回。无论使用哪个引擎，一次成功搜索都消耗 1 积分；出错不消耗。参数放在查询字符串中，需 URL 编码。示例向 Google 查询德克萨斯州奥斯汀的咖啡烘焙商；其中的 ID、数量和结果仅为示例。

认证：API 密钥放在 `Authorization: Bearer API_KEY` header 中。

**参数**

| 名称 | 位置 | 类型 | 是否必填 | 描述 |
| --- | --- | --- | --- | --- |
| `q` | query | string | 是 | 搜索查询，按人们实际输入的方式来写。引号或 `site:` 等搜索运算符属于查询的一部分。 |
| `engine` | query | string | 否 | `google`（默认）、`google_news`、`google_images`、`google_maps`、`google_shopping` 或 `bing`。 |
| `gl` | query | string | 否 | 结果的国家/地区：小写的 ISO 3166-1 alpha-2 代码，例如 `us`、`de` 或 `br`。默认 `us`。 |
| `hl` | query | string | 否 | 界面语言，例如 `en`、`de` 或 `pt-BR`。默认 `en`。 |
| `location` | query | string | 否 | 城市级地点，写作 `City, Region, Country`，例如 `Austin, Texas, United States`。参见[地点](https://serpcrypto.com/zh/docs/locations/)。 |
| `google_domain` | query | string | 否 | 要搜索的 Google 域名，例如 `google.de`。默认：`gl` 国家对应的域名。当 `engine=bing` 时忽略。 |
| `device` | query | string | 否 | `desktop`（默认）或 `mobile`。 |
| `page` | query | integer | 否 | 结果页，从 1（默认）到 10。每个结果页都是一次单独的查询，并消耗 1 积分。 |
| `safe` | query | string | 否 | `active` 会过滤掉露骨结果；`off`（默认）则不会。 |
| `period` | query | string | 否 | 仅返回最近一小时（`h`）、一天（`d`）、一周（`w`）、一个月（`m`）或一年（`y`）内的结果。 |
| `api_key` | query | string | 否 | 你的密钥，用于不发送 `Authorization` 请求头的情况。 |

**响应** `200`

```json
{
  "search_metadata": {
    "id": "srch_7f3a9c2e41b8",
    "status": "success",
    "engine": "google",
    "created_at": "2026-10-22T09:14:05Z",
    "credits_used": 1
  },
  "search_parameters": {
    "engine": "google",
    "q": "coffee roasters",
    "gl": "us",
    "hl": "en",
    "location": "Austin, Texas, United States",
    "google_domain": "google.com",
    "device": "desktop",
    "page": 1
  },
  "search_information": {
    "total_results": 18600000,
    "query_displayed": "coffee roasters"
  },
  "local_results": [
    {
      "position": 1,
      "title": "Example Coffee Roasters",
      "address": "123 Example St, Austin, TX",
      "rating": 4.7,
      "reviews": 312,
      "type": "Coffee roasters"
    }
  ],
  "organic_results": [
    {
      "position": 1,
      "title": "The 12 best coffee roasters in Austin",
      "link": "https://www.example.com/austin/coffee-roasters",
      "displayed_link": "www.example.com › austin › coffee",
      "snippet": "From light Nordic roasts to dark espresso blends, these local roasters…",
      "date": "Sep 30, 2026"
    },
    {
      "position": 2,
      "title": "Example Roasting Co. | Fresh beans, roasted in Austin",
      "link": "https://www.example.org/",
      "displayed_link": "www.example.org",
      "snippet": "Small-batch coffee roasted every weekday and shipped the same day…"
    }
  ],
  "people_also_ask": [
    {
      "question": "What is the oldest coffee roaster in Austin?",
      "snippet": "…",
      "title": "Austin coffee history",
      "link": "https://www.example.net/austin-coffee-history"
    }
  ],
  "related_searches": [
    {
      "query": "coffee roasters near me"
    },
    {
      "query": "coffee roasters austin wholesale"
    }
  ],
  "pagination": {
    "current": 1,
    "next_page": 2
  }
}
```

*curl*

```bash
curl -sG "https://serpcrypto.com/api/v1/search" \
  -H "Authorization: Bearer $SERPCRYPTO_API_KEY" \
  --data-urlencode "q=coffee roasters" \
  --data-urlencode "location=Austin, Texas, United States" \
  -d gl=us -d hl=en -d device=desktop
```

*Python*

```python
import os

import requests

r = requests.get(
    "https://serpcrypto.com/api/v1/search",
    params={
        "q": "coffee roasters",
        "location": "Austin, Texas, United States",
        "gl": "us",
        "hl": "en",
    },
    headers={"Authorization": "Bearer " + os.environ["SERPCRYPTO_API_KEY"]},
    timeout=60,
)
r.raise_for_status()
print(r.json()["organic_results"][0]["link"])
```

*Node.js*

```javascript
const params = new URLSearchParams({
  q: "coffee roasters",
  location: "Austin, Texas, United States",
  gl: "us",
  hl: "en",
});
const res = await fetch("https://serpcrypto.com/api/v1/search?" + params, {
  headers: { Authorization: "Bearer " + process.env.SERPCRYPTO_API_KEY },
});
const data = await res.json();
console.log(data.organic_results?.[0]?.link);
```

## 有哪些 engine 值，各自返回什么？

响应结构（`search_metadata`、`search_parameters`、`search_information`）在每个 engine 上都一样。只有页面显示某个区块时，该区块才会出现。

| `engine` | 来源 | 答案中的主要区块 |
| --- | --- | --- |
| `google` | Google 搜索结果 | `ai_overview`、`organic_results`、`ads`、`people_also_ask`、`local_results`、`knowledge_graph`、`top_stories`、`inline_videos`、`shopping_results`、`related_searches`、`pagination` |
| `google_news` | Google News | `news_results`：标题、链接、来源、日期、摘要、缩略图 |
| `google_images` | Google Images | `images_results`：原始 URL 和尺寸、缩略图、来源页面 |
| `google_maps` | Google Maps | `local_results`：名称、地址、电话、网站、评分、评论数、类别、营业时间、坐标 |
| `google_shopping` | Google Shopping | `shopping_results`：标题、价格、提取价格、货币、商家、配送、评分 |
| `bing` | Bing | `organic_results`、`related_searches` |

## 查看你的积分

`GET /api/v1/credits`

返回账户剩余的积分、自 UTC 零点以来已使用的积分，以及你的账户可同时运行的查询数量。此调用免费。以下数值仅为示例。

认证：API 密钥放在 `Authorization: Bearer API_KEY` header 中。

**响应** `200`

```json
{
  "credits_remaining": 84210,
  "credits_used_today": 1290,
  "concurrency_limit": 10
}
```

*curl*

```bash
curl -s "https://serpcrypto.com/api/v1/credits" \
  -H "Authorization: Bearer $SERPCRYPTO_API_KEY"
```

*Python*

```python
import os

import requests

r = requests.get(
    "https://serpcrypto.com/api/v1/credits",
    headers={"Authorization": "Bearer " + os.environ["SERPCRYPTO_API_KEY"]},
    timeout=30,
)
r.raise_for_status()
print(r.json()["credits_remaining"])
```

*Node.js*

```javascript
const res = await fetch("https://serpcrypto.com/api/v1/credits", {
  headers: { Authorization: "Bearer " + process.env.SERPCRYPTO_API_KEY },
});
const { credits_remaining } = await res.json();
console.log(credits_remaining);
```

## API 可能返回哪些错误？

每个错误的响应体都是 `{"error": {"code": "…", "message": "…"}}`。[错误页面](https://serpcrypto.com/zh/docs/errors/) 解释了每个错误，并给出重试 code。

| HTTP | `code` | 发生时机 | 是否计费 |
| --- | --- | --- | --- |
| 400 | `invalid_parameter` | 缺少必需参数，或参数值超出允许范围 | 否 |
| 401 | `invalid_api_key` | 密钥缺失、错误或已撤销 | 否 |
| 402 | `insufficient_credits` | 账户积分已用完 | 否 |
| 429 | `concurrency_limit` | 你的账户同时运行的查询过多 | 否 |
| 502 | `search_failed` | 本次请求的 engine 或采集失败；请重试 | 否 |
| 504 | `search_timeout` | 未及时返回答案；请重试 | 否 |

## 具体如何计费？

- **一次成功的查询 = 1 积分**，在每个 engine 上都一样，包括 Google Maps 和 Google Shopping。
- **每个结果页都是一次查询。** 每页约 10 条自然结果，这是 Google 自 2025 年 9 月起不再支持 num=100 后的返回方式；每多一页就多消耗 1 积分。
- **错误免费：** 所有 HTTP 状态码不是 200 的响应都不消耗积分。
- **查看积分免费。**

预付的搜索积分永不过期：未使用的查询会一直留在你的账户中，直到你使用它们。积分包从 US$7.50 买 10,000 次搜索 起，最大的一档为 US$0.30/千次搜索；详见[价格](https://serpcrypto.com/zh/pricing/)。

## 查询应该怎样编码？

以 URL 编码形式发送 `q`，和其他 query-string 值一样：空格变成 `%20` 或 `+`，带重音的字母按 UTF-8 编码。curl 用 `--data-urlencode` 完成，Python 的 `requests` 和 `httpx` 用 `params=` 完成，Node.js 用 `URLSearchParams` 完成。

查询要按用户在搜索框中输入的原文来写。引号、减号或 `site:` 都保留在 `q` 内；由 engine 决定如何处理它们，就像对待普通访客一样。

## API 有版本吗？

有。版本是路径的一部分：`/api/v1/`。新字段或新区块可能出现在版本 1 的响应中，因此你的代码应忽略不认识的键。删除或重命名字段会通过路径中的新版本引入，而不会改动 `v1`。

## API 参考常见问题

### 我可以发送带 JSON body 的 POST 请求吗？

版本 1 不行：两个 endpoint 都只接受 GET 请求，参数放在 query string 里。这样每次调用都能用 curl 或浏览器轻松复现，也便于在没有 body 的情况下记录日志。

### 一次搜索返回多少条结果？

每页约 10 条自然结果，这是 Google 自 2025 年 9 月起不再支持 num=100 后的返回方式；每多一页就多消耗 1 积分。要收集 30 条结果，请分别请求 `page=1`、`page=2` 和 `page=3`：三次搜索，三个积分。

### 积分用完了会怎样？

下一次搜索会返回 `402 insufficient_credits`，且不消耗任何积分。在[定价页面](https://serpcrypto.com/zh/pricing/)用余额再买一个积分包即可；你的密钥继续有效，搜索会立即恢复。

### 我可以在多台服务器上使用同一个密钥吗？

可以。密钥不与 IP 地址绑定。受限的是账户上同时运行的搜索数量：`GET /credits` 中的 `concurrency_limit` 给出了具体数值。

---

SerpCrypto: SerpCrypto 是面向开发者和 AI Agent 的 SERP API，可将 Google 和 Bing 搜索结果以 JSON 返回，用加密货币支付，无需上传证件。预付费搜索积分自 US$0.30/千次搜索 起永不过期。无需 KYC——无需证件、无需自拍、无需材料。加密货币支付。