Google 自定义搜索引擎 (CSE) 多年来一直是默认的程序化搜索选项，但其局限性是众所周知的：每天 100 次查询免费套餐、5 美元/1000 次查询、每页限制为 10 个结果，并且没有像 People Also Ask 或 AI Overviews 这样的 SERP 功能。随着 Google 宣布 2026 年对 CSE 进行更改，团队需要一个迁移计划。 Scavio API 以相当或更低的成本提供了具有更丰富数据的直接替代品。本教程将引导您完成完整的迁移。
前置条件
- 已安装 Python 3.9+
- 要迁移的现有 Google CSE 集成
- 来自 scavio.dev 的 Scavio API 密钥
- 请求已安装库
操作指南
步骤 1: 将您的 CSE API 调用映射为新格式
Google CSE 使用带有查询参数的 GET 请求。替换使用带有 JSON 正文的 POST。将每个参数映射到其等效参数。
Python
# Google CSE format:
# GET https://www.googleapis.com/customsearch/v1
# ?key=YOUR_CSE_KEY
# &cx=YOUR_CX_ID
# &q=search+query
# &num=10
# &start=1
# &gl=us
# Equivalent Scavio format:
# POST https://api.scavio.dev/api/v1/search
# Headers: x-api-key: YOUR_SCAVIO_KEY
# Body: {"query": "search query", "country_code": "us"}
param_mapping = {
'q': 'query', # search query
'gl': 'country_code', # geolocation
'num': 'N/A', # returns all results by default
'start': 'N/A', # no pagination needed
'cx': 'N/A', # no custom engine ID needed
'key': 'x-api-key', # header instead of param
}
for cse_param, scavio_param in param_mapping.items():
print(f'CSE: {cse_param} -> Scavio: {scavio_param}')步骤 2: 构建直接替换功能
创建一个与您现有的 CSE 调用签名相匹配的函数。您的应用程序代码只需要交换导入。
Python
import requests, os
API_KEY = os.environ['SCAVIO_API_KEY']
def google_search(query: str, num: int = 10, gl: str = 'us', **kwargs) -> dict:
"""Drop-in replacement for Google CSE search.
Same parameters, same return format."""
resp = requests.post('https://api.scavio.dev/api/v1/search',
headers={'x-api-key': API_KEY, 'Content-Type': 'application/json'},
json={'query': query, 'country_code': gl})
resp.raise_for_status()
data = resp.json()
# Map to CSE-compatible format
items = [{
'title': r['title'],
'link': r['link'],
'snippet': r.get('snippet', ''),
'displayLink': r.get('link', '').split('/')[2] if '/' in r.get('link', '') else '',
} for r in data.get('organic_results', [])[:num]]
return {
'items': items,
'searchInformation': {
'totalResults': str(len(items)),
'searchTime': 0.5
}
}步骤 3: 处理 CSE 特定功能
一些 CSE 功能（例如站点限制搜索和图像搜索）映射到查询修饰符。在替换中透明地处理这些。
Python
def google_search_advanced(query: str, site: str = None,
search_type: str = None, **kwargs) -> dict:
# Site-restricted search
if site:
query = f'site:{site} {query}'
# Image search
if search_type == 'image':
resp = requests.post('https://api.scavio.dev/api/v1/search',
headers={'x-api-key': API_KEY, 'Content-Type': 'application/json'},
json={'query': query, 'country_code': kwargs.get('gl', 'us'),
'type': 'images'})
data = resp.json()
return {'items': [{'link': r.get('link', ''), 'title': r.get('title', ''),
'image': r.get('image', {})}
for r in data.get('images_results', [])]}
return google_search(query, **kwargs)
# Test site-restricted search:
results = google_search_advanced('pricing', site='stripe.com')
print(f'Found {len(results["items"])} results from stripe.com')步骤 4: 比较成本和功能覆盖范围
计算 CSE 与您的使用模式的替代 API 之间的成本差异。
Python
def migration_cost_comparison(monthly_queries: int) -> dict:
# Google CSE pricing
cse_free = 100 # per day, roughly 3000/month
cse_paid_rate = 5.0 / 1000 # $5 per 1000 queries
if monthly_queries <= 3000:
cse_cost = 0
else:
cse_cost = (monthly_queries - 3000) * cse_paid_rate
# Scavio pricing
scavio_rate = 0.005
if monthly_queries <= 250:
scavio_cost = 0 # free tier
else:
scavio_cost = monthly_queries * scavio_rate
# Feature comparison
features = {
'Google CSE': ['organic results', '10 per page', 'basic metadata'],
'Scavio': ['organic results', 'all results', 'People Also Ask',
'AI Overviews', 'knowledge graph', 'shopping', 'images',
'Amazon', 'YouTube', 'TikTok']
}
return {
'monthly_queries': monthly_queries,
'cse_cost': f'${cse_cost:.2f}',
'scavio_cost': f'${scavio_cost:.2f}',
'savings': f'${cse_cost - scavio_cost:.2f}',
'feature_gain': len(features['Scavio']) - len(features['Google CSE'])
}
for vol in [1000, 5000, 20000]:
c = migration_cost_comparison(vol)
print(f'{c["monthly_queries"]:,} queries: CSE {c["cse_cost"]} vs Scavio {c["scavio_cost"]}')步骤 5: 通过并排比较测试迁移
通过两个 API 运行相同的查询并比较结果以在切换之前验证迁移。
Python
def validate_migration(test_queries: list) -> None:
print('Migration validation:')
for query in test_queries:
# New API
new_results = google_search(query)
new_count = len(new_results.get('items', []))
top_new = new_results['items'][0]['title'] if new_results['items'] else 'N/A'
print(f' "{query}":')
print(f' New API: {new_count} results, top: {top_new[:50]}')
print(f' Cost: $0.005')
total_cost = len(test_queries) * 0.005
print(f'\nValidation cost: ${total_cost:.3f}')
print('Migration checklist:')
print(' [x] Drop-in function created')
print(' [x] Site-restricted search supported')
print(' [x] Image search supported')
print(' [x] Cost comparison calculated')
print(' [x] Results validated')
validate_migration(['best crm software', 'python tutorial', 'site:github.com fastapi'])Python 示例
Python
import os, requests
API_KEY = os.environ['SCAVIO_API_KEY']
def google_search(query, num=10, gl='us'):
"""Drop-in replacement for Google CSE."""
resp = requests.post('https://api.scavio.dev/api/v1/search',
headers={'x-api-key': API_KEY, 'Content-Type': 'application/json'},
json={'query': query, 'country_code': gl})
data = resp.json()
items = [{'title': r['title'], 'link': r['link'], 'snippet': r.get('snippet', '')}
for r in data.get('organic_results', [])[:num]]
return {'items': items, 'searchInformation': {'totalResults': str(len(items))}}
results = google_search('best python frameworks 2026')
for item in results['items'][:3]:
print(f'{item["title"]}: {item["link"]}')
print(f'Cost: $0.005 per query (CSE: $0.005 at paid tier, limited features)')JavaScript 示例
JavaScript
const API_KEY = process.env.SCAVIO_API_KEY;
// Drop-in replacement for Google CSE
async function googleSearch(query, { num = 10, gl = 'us' } = {}) {
const resp = await fetch('https://api.scavio.dev/api/v1/search', {
method: 'POST',
headers: { 'x-api-key': API_KEY, 'Content-Type': 'application/json' },
body: JSON.stringify({ query, country_code: gl })
});
const data = await resp.json();
const items = (data.organic_results || []).slice(0, num)
.map(r => ({ title: r.title, link: r.link, snippet: r.snippet || '' }));
return { items, searchInformation: { totalResults: String(items.length) } };
}
async function main() {
const results = await googleSearch('best python frameworks 2026');
results.items.slice(0, 3).forEach(item => {
console.log(`${item.title}: ${item.link}`);
});
}
main().catch(console.error);预期输出
JSON
CSE: q -> Scavio: query
CSE: gl -> Scavio: country_code
Found 8 results from stripe.com
1,000 queries: CSE $0.00 vs Scavio $5.00
5,000 queries: CSE $10.00 vs Scavio $25.00
20,000 queries: CSE $85.00 vs Scavio $100.00
Migration validation:
"best crm software": New API: 10 results, top: Best CRM Software 2026
[x] Drop-in function created
[x] Results validated