mirror of
https://github.com/karust/openserp.git
synced 2026-08-12 11:53:29 +08:00
ecacfab4d6
- Implement integration tests for Baidu, Bing, DuckDuckGo, Google, and Yandex. - Refactor test utility functions to avoid core import cycles.
188 lines
6.4 KiB
Markdown
188 lines
6.4 KiB
Markdown
# OpenSERP (Search Engine Results)
|
||
|
||
|
||
|
||
[](https://goreportcard.com/report/github.com/karust/openserp)
|
||
[](https://pkg.go.dev/github.com/karust/openserp)
|
||
[](https://github.com/karust/openserp/releases)
|
||
[](https://github.com/karust/openserp/actions/workflows/ci.yml)
|
||
|
||
<!-- [](https://hub.docker.com/repository/docker/karust/openserp) -->
|
||
|
||
**OpenSERP** is an API and CLI for accessing search engine results from **Google, Yandex, Baidu, Bing, and DuckDuckGo**.
|
||
A developer-friendly alternative to paid SERP API services!
|
||
|
||
**Official website:** [openserp.org](https://openserp.org)
|
||
|
||
> 💡 OpenSerp is free and open-source. Only links listed in this repository and on the official website are associated with the project.
|
||
|
||
## Features
|
||
|
||
- 🔍 **Multi-engine** - search with dedicated endpoints for each engine
|
||
- 🌐 **Megasearch** - cross-engine aggregation with deduplication
|
||
- 🖼 **Images** - image search is also available
|
||
- 🎯 **Advanced filters** - language, date range, file type, and site queries
|
||
- 🌍 **Configurable** - proxy, cache, and resilient mode support
|
||
- 🐳 **Docker-ready** - local and container deployment
|
||
|
||
## Quick Start⚡️
|
||
|
||
### Docker (Recommended)
|
||
|
||
```bash
|
||
# Run the API server via prebuilt image
|
||
docker run -p 127.0.0.1:7000:7000 -it karust/openserp serve -a 0.0.0.0 -p 7000
|
||
|
||
# Or use docker-compose
|
||
docker compose up --build
|
||
```
|
||
|
||
### From source
|
||
|
||
```bash
|
||
git clone https://github.com/karust/openserp.git
|
||
cd openserp
|
||
go build -o openserp .
|
||
./openserp serve
|
||
```
|
||
|
||
## 🌐 Megasearch & Megaimage
|
||
|
||
Search all engines at once:
|
||
|
||
```bash
|
||
curl "http://127.0.0.1:7000/mega/search?text=golang&limit=10"
|
||
```
|
||
|
||
Search only selected engines:
|
||
|
||
```bash
|
||
curl "http://127.0.0.1:7000/mega/search?text=golang&engines=duckduckgo,bing&limit=15"
|
||
```
|
||
|
||
Advanced filtering:
|
||
|
||
```bash
|
||
curl "http://127.0.0.1:7000/mega/search?text=Donald+Trump&engines=duckduckgo,bing&limit=20&date=20251005..20251005&lang=EN"
|
||
```
|
||
|
||
API response example:
|
||
|
||
```json
|
||
[
|
||
{
|
||
"rank": 1,
|
||
"url": "https://en.wikipedia.org/wiki/Golden_Retriever",
|
||
"title": "Golden Retriever - Wikipedia",
|
||
"description": "The Golden Retriever is a Scottish breed of retriever dog of medium size. It is characterised by a gentle and affectionate nature and a striking golden coat.",
|
||
"ad": false,
|
||
"engine": "duckduckgo"
|
||
},
|
||
{
|
||
"rank": 2,
|
||
"url": "https://www.bing.com/ck/a?!&&p=6f15ac4589858d0a104cd6f55cc8",
|
||
"title": "Golden Retriever Dog Forums",
|
||
"description": "Oct 20, 2024 · Back in the 1970s, Golden Retrievers routinely lived until 16 and 17 years old, they are now...",
|
||
"ad": false,
|
||
"engine": "bing"
|
||
},
|
||
{
|
||
"rank": 3,
|
||
"url": "http://www.baidu.com/link?url==2544q3ugc68j0scVxdpWCSX-gl2AmuCy1l7uRR3loIfS1",
|
||
"title": "golden retrievers是什么意思",
|
||
"description": "2025年9月21日golden retrievers 读音:美英 golden retrievers基本解释 金毛猎犬 分词解释 golden金(黄)色的...",
|
||
"ad": false,
|
||
"engine": "baidu"
|
||
}
|
||
]
|
||
```
|
||
|
||
Image search:
|
||
|
||
```bash
|
||
curl "http://127.0.0.1:7000/mega/image?text=golang logo&limit=20"
|
||
```
|
||
|
||
List available engines:
|
||
|
||
```bash
|
||
curl "http://127.0.0.1:7000/mega/engines"
|
||
```
|
||
|
||
**Available engines:** `google`, `yandex`, `baidu`, `bing`, `duckduckgo`
|
||
|
||
## 🔍 Individual Engine APIs
|
||
|
||
Common query parameters:
|
||
|
||
| Parameter | Description | Example |
|
||
| --------- | -------------------- | --------------------------------- |
|
||
| `text` | Search query | `golang programming` |
|
||
| `lang` | Language code | `EN`, `DE`, `RU`, `ES` |
|
||
| `date` | Date range | `20230101..20231231` |
|
||
| `file` | File extension | `PDF`, `DOC`, `XLS` |
|
||
| `site` | Site-specific search | `github.com`, `stackoverflow.com` |
|
||
| `limit` | Number of results | `10`, `25`, `50` |
|
||
|
||
Engine-specific parameters:
|
||
|
||
| Parameter | Supported engines | Notes |
|
||
| --------- | ----------------------------------- | ------------------------------------------------------------------ |
|
||
| `start` | `google`, `bing`, `yandex`, `baidu` | Web search pagination offset. |
|
||
| `filter` | `google` | Duplicate filter (`true` hides similar, `false` includes similar). |
|
||
| `answers` | `google` | Include Google answer boxes in output with negative ranks. |
|
||
|
||
Examples:
|
||
|
||
```bash
|
||
curl "http://127.0.0.1:7000/duck/search?text=golang&limit=7"
|
||
curl "http://127.0.0.1:7000/google/search?text=golang&lang=EN&limit=10"
|
||
curl "http://127.0.0.1:7000/bing/search?text=golang&limit=10&start=20"
|
||
curl "http://127.0.0.1:7000/yandex/search?text=golang&limit=10&start=10"
|
||
curl "http://127.0.0.1:7000/bing/image?text=golang&limit=20"
|
||
```
|
||
|
||
## 🌍 Proxy Support
|
||
|
||
OpenSERP supports HTTP and SOCKS5 proxies.
|
||
|
||
Simple global proxy:
|
||
|
||
```bash
|
||
./openserp serve --proxy socks5://127.0.0.1:1080
|
||
./openserp search bing "query" --proxy http://user:pass@127.0.0.1:8080
|
||
```
|
||
|
||
Advanced proxy configuration is available in [config.yaml](./config.yaml).
|
||
You can enable tagged proxy pools and per-request override via `X-Use-Proxy: <tag>` or `X-Use-Proxy: direct`.
|
||
|
||
## Health & Stats
|
||
|
||
```bash
|
||
curl -i "http://127.0.0.1:7000/health"
|
||
curl "http://127.0.0.1:7000/stats"
|
||
curl "http://127.0.0.1:7000/stats/cache"
|
||
curl "http://127.0.0.1:7000/stats/proxy"
|
||
curl "http://127.0.0.1:7000/stats/cb"
|
||
```
|
||
|
||
Useful response headers in server mode: `X-Cache`, `X-Fallback-Engine`,`X-Proxy-Mode`, `X-Proxy-Tag`, `X-Proxy-Used`
|
||
|
||
## License
|
||
|
||
This project is licensed under the MIT License. See [LICENSE](LICENSE).
|
||
|
||
## 🤝 Contributing
|
||
|
||
Contributions are welcome. Please feel free to submit a pull request.
|
||
|
||
## 👾 Issues & Support
|
||
|
||
If you encounter issues or have questions:
|
||
|
||
- Open an issue on GitHub
|
||
- Check existing issues for similar reports
|
||
- Review the documentation and example config
|
||
|
||
###### _"OpenSerp" is the name of this open-source project. Use of the name in a way that implies affiliation, endorsement, or official status is not permitted._
|