SEODataForSEO5 credits

serp_rank

查看某域名针对某个关键词在 Google 自然结果中的排名——真实的 SERP 排名位置，而非 Custom Search 的排序。返回目标的自然排名、排名 URL 以及其占据的每一个位置。由 DataForSEO 提供支持。

使用场景

关键词排名追踪

持续监控您的页面在目标关键词上的排名，及早发现排名下滑

竞争对手 SERP 监控

追踪竞争对手域名在对您业务至关重要的关键词上的排名

SEO 排名审计

审计一组关键词的自然排名，以确定页面优化和内容工作的优先级

本地与设备 SEO 检查

按地理位置以及 desktop 与 mobile 对比排名，从而发现地域或设备差异

排名追踪仪表盘

将每日自然排名数据接入您自己的仪表盘和报表流水线

Endpoint

POST/api/v1/tools/serp_rank

Auth Required

Free 计划 1 req/s

5 credits

Parameters

Name	Type	Required	Default	Description
keyword	string	Required	-	要查询排名的搜索关键词 Example: managed wordpress hosting
target	string	Required	-	要在结果中定位的域名或 URL。按主机匹配，而非精确 URL：URL 会被归约为其主机，该主机或其子域名上的任何页面都计入 Example: example.com
depth	number	Optional	30	要扫描的结果数量（10-200，默认 30）；扫描越深耗时越长。任何深度均固定消耗 5 credits Example: 100
device	string	Optional	desktop	要模拟的设备："desktop" 或 "mobile" Example: mobile
location_name	string	Optional	United States	地理位置，例如 'United States' 或 'London,England,United Kingdom' Example: United States
location_code	number	Optional	-	数字形式的 DataForSEO 地理位置代码（会覆盖 location_name） Example: 2840
language_code	string	Optional	en	语言代码（例如 'en'） Example: en

serp_rank 测量的是真实的自然排名位置，而非 Custom Search 的排序。depth 控制扫描多少结果；任何深度均收取 5 credits。使用 location_name/location_code 和 device 来检查特定地域和设备的排名。每次查询只是一个样本：同一查询在几分钟内可能得到不同的结果集，因此在判断排名变化前，请比较多次查询的结果，最好分布在不同日期。

请求示例

terminalBash

curl -X POST https://crawlforge.dev/api/v1/tools/serp_rank \
  -H "X-API-Key: cf_test_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "keyword": "managed wordpress hosting",
    "target": "example.com",
    "depth": 100,
    "device": "desktop",
    "location_name": "United States",
    "language_code": "en"
  }'

响应示例

200 OK6,200ms

{
  "success": true,
  "data": {
    "keyword": "managed wordpress hosting",
    "target": "example.com",
    "location": "United States",
    "language": "en",
    "device": "desktop",
    "depth": 30,
    "found": true,
    "rank": 3,
    "url": "https://example.com/",
    "all_positions": [
      3,
      27
    ],
    "results_scanned": 30,
    "se_results_count": 1370000,
    "check_url": "https://www.google.com/search?q=managed+wordpress+hosting&num=30&hl=en&gl=US",
    "checked_at": "2026-07-01T14:30:00Z"
  },
  "credits_used": 5,
  "credits_remaining": 995,
  "processing_time": 6200
}

Field Descriptions

data.rank最佳自然排名位置（如果在 depth 范围内未找到目标，则为 null）

data.url占据最佳排名位置的 URL

data.all_positions目标在扫描的 depth 范围内占据的每一个自然排名位置

data.found目标是否出现在扫描的 depth 范围内

data.se_results_countGoogle 对该查询给出的结果总数。两次查询的数字相差很大，说明来自不同的结果集

data.check_urlDataForSEO 查询的 Google 结果页，可自行查看该 SERP

credits_used每次查询固定消耗 5 credits，与深度无关

processing_time查询通常需要 5-15 秒

错误处理

缺少 keyword 或 target（400 Bad Request）

keyword 和 target 均为必填项。请提供搜索关键词以及域名或 URL。

depth 无效（400 Bad Request）

depth 必须介于 10 到 200 之间。更大的 depth 会扫描更多结果。

device 无效（400 Bad Request）

device 必须为 "desktop" 或 "mobile"。

配额超限（429 Too Many Requests）

SERP 提供商设有每日限额。升级您的套餐以获得更高配额。

服务商超时（504 Gateway Timeout）

SERP 查询会实时请求 Google，在高负载时可能超过时间限制。不会扣除额度，请重试。

查询不可用（502 / 503）

SERP 服务商无法访问、已达速率限制，或此部署未配置该功能。不会扣除额度。

专业提示：

target 按主机匹配，而非精确 URL：传入 https://example.com/pricing 时，返回的是 example.com 或其子域名上任意页面的最佳排名，url 字段给出占据该排名的页面。传入子域名（blog.example.com）可缩小匹配范围。当地理位置名称存在歧义时，使用 location_code 进行精确的地理定向。

Credit 费用

5 credits

每次查询 5 credits

扫描最多 100 条结果的固定费用。仅对成功的查询扣除 credits。

包含内容：

真实的自然 SERP 排名位置（而非 Custom Search 排序）

排名 URL 以及目标占据的每一个位置

地理位置和语言定向

desktop 和 mobile 设备模拟

扫描深度最多 200 条结果

套餐推荐：

Free 套餐： 1,000 个一次性试用 credits = 200 次查询

Hobby 套餐： 5,000 credits = 1,000 次查询（$19/mo）

Professional 套餐： 100,000 credits = 20,000 次查询（$99/mo）