当前位置：首页 > news >正文

Searx API完全手册：如何利用JSON/CSV接口构建自定义搜索应用

news 2026/7/27 19:39:41

Searx API完全手册：如何利用JSON/CSV接口构建自定义搜索应用

【免费下载链接】searxA privacy-respecting, hackable metasearch engine项目地址: https://gitcode.com/gh_mirrors/searx1/searx

Searx是一款注重隐私保护的元搜索引擎，通过其强大的API接口，开发者可以轻松构建自定义搜索应用。本文将详细介绍如何使用Searx的JSON和CSV接口，实现高效、安全的搜索功能集成。

快速了解Searx API接口

Searx提供了两种主要的API输出格式，满足不同开发需求：

JSON格式：适合需要结构化数据的应用，便于解析和处理
CSV格式：适合数据导出和表格处理场景

这些接口无需额外配置，只需在搜索请求中指定输出格式即可启用。

如何调用JSON接口获取搜索结果

基础JSON接口调用方法

要获取JSON格式的搜索结果，只需在搜索请求中添加format=json参数：

http://your-searx-instance/search?q=example&format=json

JSON响应结构解析

Searx的JSON响应包含以下核心字段：

query：搜索关键词
results：搜索结果数组，每个结果包含标题、URL、内容等信息

从源码 searx/webapp.py 中可以看到JSON响应的生成逻辑：

if request_data.get('format') == 'json': return Response(json.dumps({'query': query, 'results': results}), mimetype='application/json')

实际应用示例

以下是一个简单的Python示例，演示如何调用Searx JSON接口：

import requests import json def searx_search(query, searx_instance="http://localhost:8888"): url = f"{searx_instance}/search" params = { "q": query, "format": "json" } response = requests.get(url, params=params) return json.loads(response.text) # 使用示例 results = searx_search("开源项目") print(f"搜索到 {len(results['results'])} 个结果") for result in results['results'][:3]: print(f"标题: {result['title']}") print(f"链接: {result['url']}\n")

如何使用CSV接口导出搜索数据

CSV接口基本用法

要获取CSV格式的搜索结果，使用format=csv参数：

http://your-searx-instance/search?q=example&format=csv

CSV文件格式说明

Searx CSV文件包含以下列：标题、URL、内容、主机、引擎、分数。从 searx/webapp.py 可以看到CSV生成的关键代码：

elif request_data.get('format') == 'csv': csv = UnicodeWriter(cStringIO.StringIO()) keys = ('title', 'url', 'content', 'host', 'engine', 'score') if len(results): csv.writerow(keys) for row in results: row['host'] = row['parsed_url'].netloc csv.writerow([row.get(key, '') for key in keys]) csv.stream.seek(0) response = Response(csv.stream.read(), mimetype='application/csv') response.headers.add('Content-Disposition', 'attachment;Filename=searx_-_{0}.csv'.format('_'.join(query.split())))

CSV接口应用场景

CSV格式特别适合：

数据备份和存档
电子表格分析
数据导入到其他系统

高级API功能与参数

搜索结果过滤

Searx API支持通过URL参数过滤搜索结果：

category：指定搜索类别（如category=images只返回图片结果）
language：设置搜索语言（如language=en）
safesearch：启用安全搜索（safesearch=1）

分页与结果数量控制

虽然API本身不直接支持分页参数，但你可以通过修改Searx配置文件 searx/settings.py 调整默认结果数量。

自定义引擎选择

Searx允许通过API参数指定使用的搜索引擎：

http://your-searx-instance/search?q=example&format=json&engines=google,bing

构建自定义搜索应用的最佳实践

缓存搜索结果

为减轻服务器负担并提高响应速度，建议实现结果缓存机制：

import requests import json from datetime import datetime, timedelta cache = {} def cached_searx_search(query, ttl=3600): now = datetime.now() # 检查缓存是否存在且未过期 if query in cache and now - cache[query]['time'] < timedelta(seconds=ttl): return cache[query]['data'] # 缓存未命中，调用API data = searx_search(query) cache[query] = { 'data': data, 'time': now } return data

错误处理与重试机制

实现健壮的错误处理，确保应用稳定性：

def robust_searx_search(query, max_retries=3): retries = 0 while retries < max_retries: try: return searx_search(query) except Exception as e: retries += 1 if retries == max_retries: print(f"搜索失败: {str(e)}") return None print(f"重试 ({retries}/{max_retries})...") time.sleep(1)

尊重API使用限制

为确保服务稳定性，建议：

避免过于频繁的请求
合理设置请求间隔
在生产环境中使用自己的Searx实例

从零开始搭建Searx服务

安装步骤

克隆仓库：

git clone https://gitcode.com/gh_mirrors/searx1/searx

安装依赖：

cd searx pip install -r requirements.txt

启动服务：

python searx/webapp.py

服务默认在 http://localhost:8888 运行，你可以直接使用API接口。

常见问题与解决方案

API返回结果为空

可能原因及解决方法：

搜索引擎配置问题：检查 searx/engines/ 目录下的引擎配置
网络连接问题：确认服务器可以访问外部搜索引擎
查询过于特殊：尝试更通用的搜索词

如何添加自定义输出字段

修改 searx/webapp.py 中的JSON和CSV生成代码，添加所需字段。例如，要添加结果日期：

# 在JSON响应中添加日期字段 if request_data.get('format') == 'json': # 为每个结果添加日期 for result in results: result['date'] = extract_date(result['content']) return Response(json.dumps({'query': query, 'results': results}), mimetype='application/json')