接口名称：关键字搜索接口
接口简介
本接口提供基于关键字的商品/内容检索功能，支持分页返回匹配结果，适用于电商、资讯等场景的搜索需求。
接口功能
通过关键词检索平台内容
支持分页参数设置
返回匹配结果的列表和分页信息
请求方式
URL: https://api.xiyu.com/v1/search
Method: GET
鉴权方式: Bearer Token (需在Header中携带)
请求参数
参数名 类型 必填 说明
keyword string 是 搜索关键词（2-50字符）
page int 否 页码（默认1）
limit int 否 每页条数（默认10，最大50）
返回数据示例
json
Copy Code
{
"code": 200,
"message": "success",
"data": {
"total": 85,
"page": 1,
"results": [
{
"id": "PROD001",
"title": "西域特色干果礼盒",
"price": 129.00,
"category": "食品"
},
{
"id": "ART002",
"title": "西域文化历史探秘",
"author": "文化研究所",
"type": "文章"
}
]
}
}
示例代码
Python 示例
python
Copy Code
import requests
def search_xiyu(keyword, page=1, limit=10):
url = "https://api.xiyu.com/v1/search"
headers = {
"Authorization": "Bearer YOUR_API_TOKEN"
}
params = {
"keyword": keyword,
"page": page,
"limit": limit
}
try:
response = requests.get(url, headers=headers, params=params)
response.raise_for_status()
return response.json()
except requests.exceptions.RequestException as e:
print(f"搜索失败: {e}")
return None
使用示例
result = search_xiyu("西域文化", page=1)
if result and result["code"] == 200:
for item in result["data"]["results"]:
print(f"{item['title']} ({item.get('category', '内容')})")
JavaScript 示例
javascript
Copy Code
async function searchXiyu(keyword, page = 1, limit = 10) {
const url = new URL('https://api.xiyu.com/v1/search');
url.searchParams.append('keyword', keyword);
url.searchParams.append('page', page);
url.searchParams.append('limit', limit);
try {
const response = await fetch(url, {
headers: {
'Authorization': 'Bearer YOUR_API_TOKEN'
}
});
if (!response.ok) {
throw new Error(`HTTP error! status: ${response.status}`);
}
const data = await response.json();
return data;
} catch (error) {
console.error('搜索请求失败:', error);
return null;
}
}
// 使用示例
searchXiyu('干果礼盒')
.then(result => {
if (result && result.code === 200) {
result.data.results.forEach(item => {
console.log(`{item.title} - 价格: {item.price || '免费'}`);
});
}
});
错误处理
错误码 说明 解决方案
401 认证失败 检查API Token是否有效
400 参数不合法 验证keyword长度和类型
429 请求频率过高 降低调用频率
500 服务器内部错误 联系平台技术支持
注意事项
建议对keyword进行前端输入校验（长度、特殊字符过滤）
使用HTTPS保证传输安全
推荐设置合理的请求间隔（≥200ms）
注意API调用次数限制（详见平台配额说明）
以上示例展示了如何调用西域平台的关键字搜索接口，开发者可根据实际需求调整参数处理和结果解析逻辑。建议在生产环境中添加重试机制和更完善的错误处理。