如何使用SERP API:Google SERP API集成与API密钥设置指南

逐步设置Google SERP API:获取并存储API密钥,进行首次搜索,实现结果本地化,处理错误并使用经过测试的Python代码跟踪排名。

SERP API 会替你执行一次搜索引擎查询，并以结构化 JSON 的形式返回结果页面：包含位置信息的自然搜索结果、广告、精选摘要、本地结果等等。你无需为 Google 构建抓取程序并持续维护它们，只需发送一次请求，读取所需字段即可。

本指南将带你从零开始完成设置：获取并保存 API 密钥、执行首次搜索、针对正确的位置和设备获取结果、处理错误，并将结果转化为排名检测工具。本文以 Shifter 的 SERP API 为例；大多数 SERP API 的工作方式都类似。

第一步：获取你的 API 密钥

每个请求都需要携带一个 API 密钥。在 Shifter 的控制面板中，打开 SERP API，然后进入 API Keys，复制一个有效密钥。

请像对待密码一样对待这个密钥：

不要将其写入代码或仓库中。 将其存储在环境变量或密钥管理工具中。
尽可能为开发环境和生产环境使用不同的密钥，这样泄露的测试密钥就不会影响生产环境。
如果密钥可能已泄露，请及时轮换，并在所有使用它的地方进行更新。

export SHIFTER_SERP_KEY="your-key-here"

第二步：执行你的首次搜索

该 API 只有一个端点，https://serp.shifter.io/v1。通过 engine 参数选择搜索引擎，并通过 q 参数传入查询内容：

curl "https://serp.shifter.io/v1?engine=google&api_key=$SHIFTER_SERP_KEY&q=residential+proxies"

响应内容为 JSON 格式。对于 Google 搜索，organic_results 字段保存着普通搜索结果，每条结果包含 position、title、link、displayed_link 和 snippet。其他部分，例如广告和本地结果，会在结果页面存在这些内容时出现。

同一个端点也适用于其他搜索引擎和 Google 的不同功能：将 engine 改为 bing 或 yandex 即可使用对应的搜索引擎，改为 google_maps、google_news 或 google_shopping 则可获取其他类型的 Google 结果。本指南后续内容适用于所有情况，只是响应中的字段会有所不同。

第三步：针对正确的地点和设备获取结果

搜索结果会因地点、语言和设备的不同而有很大差异。如果排名检测没有固定这些因素，每次测量到的其实是不同的结果页面。

参数	设定内容	示例
`location`	搜索发起的地点	`Austin,Texas,United States`
`gl`	结果所属国家	`us`
`hl`	界面语言	`en`
`device`	桌面、移动或平板结果	`mobile`

请完整拼写地点信息（城市、地区、国家），因为像 “Springfield” 这样的简短名称存在歧义。我们关于面向本地 SEO 的地理定位 SERP API 的指南解释了为何位置精确度如此重要。

第四步：处理错误

请求失败的原因有些是暂时性的，有些则不是：

重试速率限制和临时性服务器错误，并且每次重试之间的等待时间逐渐增加。
停止并修复身份验证错误和格式错误的请求；重试这些错误只会重复失败。
为每个请求设置超时时间，这样一个响应缓慢的搜索就不会拖慢整个运行流程。

整合到一起

下面的辅助函数从环境变量中读取密钥，始终发送位置、语言和设备信息，对值得重试的错误进行重试，并包含一个用于查找某个域名在自然搜索结果中排名位置的函数：

import os
import time
from urllib.parse import urlparse

import requests

API = "https://serp.shifter.io/v1"
RETRY = {408, 429, 500, 502, 503}


def google_search(query, location, gl="us", hl="en", device="desktop", session=None, attempts=3):
    """One Google search as seen from `location`, returned as parsed JSON."""
    session = session or requests.Session()
    params = {"engine": "google", "api_key": os.environ["SHIFTER_SERP_KEY"], "q": query,
              "location": location, "gl": gl, "hl": hl, "device": device}
    for attempt in range(1, attempts + 1):
        response = session.get(API, params=params, timeout=60)
        if response.status_code == 200:
            return response.json()
        if response.status_code not in RETRY or attempt == attempts:
            raise RuntimeError(f"{query!r}: HTTP {response.status_code} {response.text[:200]}")
        time.sleep(2 * attempt)


def rank_of(serp, domain):
    """Position of the first organic result on `domain`, or None if it is not there."""
    for result in serp.get("organic_results", []):
        host = urlparse(result["link"]).netloc.lower()
        if host == domain or host.endswith("." + domain):
            return result["position"]
    return None

检查某个网站在两个关键词上的排名，以奥斯汀地区的移动端视角查看：

from serp import google_search, rank_of

keywords = ["emergency plumber", "water heater repair"]
for keyword in keywords:
    serp = google_search(keyword, location="Austin,Texas,United States", device="mobile")
    print(keyword, rank_of(serp, "example-plumbing.com"))