Serper.dev 搜索技能

快速、低成本的 Google 搜索 API，返回结构清晰的 JSON 数据。是构建线索生成（lead generation）流水线的最佳选择。

凭证配置

需在环境变量中设置 SERPER_API_KEY。 可在 serper.dev 免费获取密钥（含 2,500 次搜索配额）。

SERPER_API_KEY=your_key_here

快速上手

import requests, os

def serper_search(query: str, num: int = 10, gl: str = "us") -> list[dict]:
    """
    通过 Serper.dev 执行 Google 搜索。
    返回结果列表，每项包含：{title, link, snippet, displayedLink, domain}
    """
    headers = {
        "X-API-KEY": os.environ["SERPER_API_KEY"],
        "Content-Type": "application/json"
    }
    payload = {"q": query, "num": num, "gl": gl}
    r = requests.post("https://google.serper.dev/search", headers=headers, json=payload)
    r.raise_for_status()
    
    results = r.json().get("organic", [])
    # 添加标准化域名提取逻辑
    import tldextract
    for result in results:
        ext = tldextract.extract(result["link"])
        result["domain"] = f"{ext.domain}.{ext.suffix}"
    return results

线索生成场景用法

import tldextract

EXCLUDE_DOMAINS = {
    "yelp.com", "facebook.com", "tripadvisor.com", "houzz.com",
    "thumbtack.com", "homeadvisor.com", "angi.com", "angieslist.com",
    "bbb.org", "yellowpages.com", "manta.com", "bark.com",
    "google.com", "nextdoor.com", "linkedin.com", "instagram.com"
}

def search_business_leads(niche: str, city: str, num_queries: int = 3) -> list[str]:
    """
    针对“细分领域 + 城市”组合执行多个查询。
    返回去重后的、直接指向企业官网的 URL 列表。
    """
    query_templates = [
        f'"{niche} {city}"',
        f'"{niche} company {city}"',
        f'"{niche} service {city}"',
        f'"{city} {niche} contractor"',
    ]
    
    seen_domains = set()
    urls = []
    
    for template in query_templates[:num_queries]:
        query = template + " -yelp -facebook -tripadvisor -houzz -thumbtack -homeadvisor"
        results = serper_search(query, num=10)
        
        for r in results:
            domain = r["domain"]
            if domain not in EXCLUDE_DOMAINS and domain not in seen_domains:
                seen_domains.add(domain)
                urls.append(r["link"])
    
    return urls

可用端点

Places 端点（本地企业发现替代方案）

def serper_places(query: str, gl: str = "us") -> list[dict]:
    """
    搜索 Google 地图 / 本地地点（Places）。
    返回字段：{title, address, phone, website, rating, reviews}
    """
    headers = {"X-API-KEY": os.environ["SERPER_API_KEY"], "Content-Type": "application/json"}
    payload = {"q": query, "gl": gl}
    r = requests.post("https://google.serper.dev/places", headers=headers, json=payload)
    return r.json().get("places", [])

# Places 接口直接返回网站 URL 和电话号码——非常适合线索生成！
# 使用示例：results = serper_places("landscaping company Portland OR")
# 每个结果字段包括：{title, address, phone, website, rating, ratingCount}

响应结构

{
  "organic": [
    {
      "title": "Green Valley Landscaping | Portland OR",
      "link": "https://www.greenvalleylandscaping.com",
      "snippet": "Professional landscaping services in Portland...",
      "displayedLink": "www.greenvalleylandscaping.com",
      "position": 1
    }
  ],
  "searchParameters": {"q": "landscaping portland OR", "gl": "us", "num": 10}
}

价格参考

速率限制与最佳实践

• 未明确声明硬性速率限制，但仍请合理调用
• 高频连续调用之间建议添加 0.5 秒延迟
• 缓存结果，避免对相同“细分领域 + 城市”重复查询
• 推荐使用默认 num=10；单次请求最大支持 num=100
• gl 参数用于指定国家/地区代码，例如："us"、"gb"、"au"、"ca" 等

错误处理

def serper_search_safe(query: str, num: int = 10) -> list[dict]:
    try:
        return serper_search(query, num)
    except requests.exceptions.HTTPError as e:
        if e.response.status_code == 429:
            print("请求超限 — 等待 5 秒后重试")
            import time; time.sleep(5)
            return serper_search(query, num)
        print(f"Serper 错误：{e}")
        return []
    except Exception as e:
        print(f"未预期错误：{e}")
        return []