OpenSERP is a free, open-source SERP API and CLI for Google, Yandex, Baidu, Bing, DuckDuckGo, and Ecosia.
No API keys, no per-search billing: one command gives you live, structured search results on localhost - including engines the paid APIs don't cover. Use it as a search tool for LLMs and agents, or as a backend for SEO rank tracking. If you'd rather not run infrastructure, there is a hosted version with the same API.
- Dedicated endpoints for six engines, same JSON schema across all of them
- Megasearch - one query across several engines at once, merged and deduped
- URL extraction - search results plus clean markdown of the target pages in one call
- SERP features: AI summaries, answer boxes, people-also-ask, related searches
- Image search, filters (language, date range, file type, site), JSON/Markdown/Text/NdJSON output
- Proxies, cache, resilient mode, prebuilt Docker images
Prebuilt images are published to docker hub: karust/openserp.
# Run the API server via prebuilt image
docker run --rm -p 127.0.0.1:7000:7000 karust/openserp:latest serve -a 0.0.0.0 -p 7000
# Or
docker compose upgo install github.com/karust/openserp@latest
openserp search duckduckgo "open source serp api" --format markdowngit clone https://github.com/karust/openserp.git
cd openserp
go build -o openserp .
./openserp serve# mode=any returns the first engine that responds
curl "http://127.0.0.1:7000/mega/search?engines=bing,google&text=golang+vs+rust&extract=1&mode=any"Example JSON response
{
"query": {
"text": "golang vs rust",
"engines_requested": ["bing", "google"]
},
"meta": {
"request_id": "019ecdc0-a66d-79a4-9d2b-9e9b480d495e",
"requested_at": "2026-06-16T00:06:55Z",
"took_ms": 720,
"engines_responded": ["bing"],
"engines_failed": [],
"version": "2.1"
},
"results": [
{
"id": "s_5a8273f16b19ab64",
"rank": 1,
"type": "organic",
"title": "The Go Programming Language",
"url": "https://go.dev/",
"display_url": "go.dev",
"snippet": "Get Started Playground Tour Stack Overflow Help Packages Standard Library …",
"domain": "go.dev",
"favicon": "https://go.dev/favicon.ico",
"position": {
"absolute": 1
},
"engine": "bing",
"domain_info": {
"tld": "dev",
"sld": "go",
"category": ""
},
"extracted": {
"title": "Build simple, secure, scalable systems with Go",
"format": "markdown",
"content": "## Build simple, secure, scalable systems with Go\n\n\n\n- “At the time, no single team member knew Go, but **within a month, everyone was writing in Go** and we were building out the endpoints. ........",
"mode_used": "fast",
"fetched_at": "2026-06-16T00:06:56Z"
}
},
{
"id": "s_1a364ebcb3035539",
"rank": 2,
"type": "organic",
"title": "Go (programming language) - Wikipedia",
"url": "https://en.wikipedia.org/wiki/Go_(programming_language)",
"display_url": "en.wikipedia.org › wiki › Go_(programming_language)",
"snippet": "In Go's package system, each package has a path (e.g., \"compress/bzip2\" or \"golang.org/x/net/html\") and a name (e.g., bzip2 or html). …",
"domain": "en.wikipedia.org",
"favicon": "https://en.wikipedia.org/favicon.ico",
"position": {
"absolute": 2
},
"engine": "bing",
"domain_info": {
"tld": "org",
"sld": "wikipedia",
"category": ""
},
"classification": {
"content_type": "article",
"source_hint": "encyclopedia"
}
},
...
],
"serp_features": [],
"pagination": {
"page": 1,
"has_more": false,
"next_start": 10
},
"clusters": [
{
"id": "c_f20b23a020101dce",
"canonical_url": "https://go.dev/",
"domain": "go.dev",
"title": "The Go Programming Language",
"occurrences": [
{
"engine": "bing",
"rank": 1,
"result_id": "s_5a8273f16b19ab64"
}
],
"engines_count": 1,
"best_rank": 1,
"score": 0.5
},
...
]
}Official client packages. Each works against your self-hosted server (set baseUrl) or the hosted API (set apiKey):
| Type | Package | Source | Install |
|---|---|---|---|
| JavaScript / TypeScript SDK | @openserp/sdk | openserpapi/sdk-js | npm install @openserp/sdk |
| Python SDK | openserp | openserpapi/sdk-python | pip install openserp |
| MCP server (AI agents) | @openserp/mcp | openserpapi/mcp | npx @openserp/mcp |
| n8n community node | @openserp/n8n-nodes-openserp | openserpapi/n8n | Install via n8n community nodes |
See examples for small JavaScript and Python use cases covering search, AI grounding, SEO, content extraction, and image search.
import{OpenSERP}from"@openserp/sdk";// Use your self-hosted serverconstclient=newOpenSERP({baseUrl: "http://localhost:7000"});const{ results }=awaitclient.search({engine: "google",text: "openserp",limit: 5});Available engine names: google, yandex, baidu, bing, duckduckgo, ecosia.
Dedicated engine endpoints:
curl "http://127.0.0.1:7000/google/search?text=golang&limit=10"Image search:
curl "http://127.0.0.1:7000/bing/image?text=golang+logo&limit=10"Megasearch:
curl "http://127.0.0.1:7000/mega/search?text=golang&limit=10"/mega/search returns the same envelope as engine endpoints plus clusters: results are deduplicated by normalized URL, and clusters keep the per-engine occurrences and ranks.
| Mode | Best for | Behavior |
|---|---|---|
balanced | Most multi-engine SERP workflows | Queries engines in parallel and merges results |
fast | Lowest latency | Uses the fastest available engine |
any | Fallback-style availability checking | Tries engines sequentially until one responds |
More megasearch examples
# Fast mode
curl "http://127.0.0.1:7000/mega/search?text=golang&mode=fast&engines=google,bing,yandex"# Any mode
curl "http://127.0.0.1:7000/mega/search?text=golang&mode=any&engines=google,yandex,bing"# Balanced mode with aggregation controls
curl "http://127.0.0.1:7000/mega/search?text=golang&mode=balanced&dedupe=true&merge=true"# Advanced filtering
curl "http://127.0.0.1:7000/mega/search?text=golang&engines=google,bing&limit=20&date=20250101..20251231&lang=EN®ion=US"# Image megasearch
curl "http://127.0.0.1:7000/mega/image?text=golang+logo&limit=20"List engines:
curl "http://127.0.0.1:7000/mega/engines"URL extraction:
# Extract one URL as JSON
curl "http://127.0.0.1:7000/extract?url=https://example.com&mode=auto"# Return clean page markdown
curl "http://127.0.0.1:7000/extract?url=https://example.com&format=markdown"# Extract several URLs at once - returns a bare [{page_content, metadata}] array# (Open WebUI external loader compatible); failed URLs become items with metadata.error
curl -X POST "http://127.0.0.1:7000/extract/batch" \
-H "Content-Type: application/json" \
-d '{"urls":["https://example.com","https://go.dev"],"mode":"fast"}'# Embed extracted content under the top search results
curl "http://127.0.0.1:7000/google/search?text=llm+observability&extract=2&format=markdown"No server required - query an engine straight from the terminal. The CLI shares the same engines, formats, and filters as the API.
openserp search ecosia "weather in london" --format markdownCLI output and more examples
# Search results for "weather in london"**Query:** weather in london - **Engines:** ecosia - **Took:** 866ms
## Results### 1. London - BBC Weather**bbc.com › weather › 2643743** - organic
Latest forecast for London ... Tonight will continue dry, and there will be mainly clear skies. Just a few patches of cloud drifting in from the north at times.
-> https://www.bbc.com/weather/2643743### 2. London (Greater London) weather - Met Office**weather.metoffice.gov.uk › forecast › gcpvj0v07** - organic
Remaining warm with light winds and dry. Possibly cloudy at times Monday and Tuesday, then Wednesday sunnier conditions are likely.
-> https://weather.metoffice.gov.uk/forecast/gcpvj0v07### 3. London, London, United Kingdom Weather Forecast**accuweather.com › en › gb › london › ec4a-2 › wea…** - organic
London, London, United Kingdom Weather Forecast, with current conditions, wind, air quality, and what to expect for the next 3 days.
-> https://www.accuweather.com/en/gb/london/ec4a-2/weather-forecast/328328More CLI examples:
# JSON is the default format
openserp search google "golang generics" --limit 20
# Plain text, German results
openserp search yandex "wetter berlin" --format text --lang DE --region DE
# Restrict to a site and stream NdJSON
openserp search bing "release notes" --site github.com --format ndjson
# Embed clean page content from the top 2 results
openserp search google "llm observability" --extract 2 --format markdown
# Browserless (raw HTTP) mode through a proxy# (raw mode: google, yandex, baidu, ecosia)
openserp search ecosia "weather in london" --raw --proxy http://user:pass@127.0.0.1:8080Run openserp search --help for the full flag list. Engine names: google, yandex, baidu, bing, duckduckgo, ecosia.
Common parameters:
| Parameter | Description | Example |
|---|---|---|
text | Search query | golang programming |
lang | Language code | EN, DE, RU, ES |
region | Market/location hint. Countries/locales work across engines; Google also accepts city names via uule; Yandex accepts numeric lr. | DE, en-GB, Berlin, 213 |
date | Date range | 20250101..20251231 |
file | File extension | pdf, doc, xls |
site | Site-specific search | github.com |
limit | Number of organic results, max 100. When omitted or <=10, only the first SERP page is parsed. | 25, 50 |
start | Pagination offset | 0, 10, 20 |
format | Output format | json, markdown, text, ndjson |
extract | Fetch and embed target-page content for top web results. Bool or int depth: 0/false off, true/1 top result, N top N (1-5). extract_mode/min_runes imply extract=true unless extract=0 | 1, 3, true |
extract_mode | Extraction strategy: raw HTTP first, raw only, or browser-rendered | auto, fast, rendered |
Engine-specific parameters:
| Parameter | Supported engines | Notes |
|---|---|---|
filter | google | Duplicate filter: true hides similar results, false includes them. |
features | browser Search | Populate serp_features[] from the live page. Defaults to true. |
OpenSERP supports HTTP and SOCKS5 proxies.
Simple global proxy:
./openserp serve --proxy socks5://127.0.0.1:1080
./openserp search bing "query" --proxy http://user:pass@127.0.0.1:8080Advanced proxy configuration is available in config.yaml. You can enable tagged proxy pools and per-request override via X-Use-Proxy: <tag> or X-Use-Proxy: direct.
Once the server is running, the interactive docs are available locally:
- Swagger UI:
http://127.0.0.1:7000/docs- full schemas, error shapes, and the/health,/ready,/stats/*endpoints - OpenAPI YAML:
http://127.0.0.1:7000/openapi.yaml
To browse the spec without running the server, see docs/openapi.yaml. For a higher-level overview of how OpenSERP works internally, see the architecture docs.
- Self-hosted (this repo) - free, MIT-licensed, full control over runtime, proxies, cache, and scaling.
- OpenSERP Cloud - same endpoints and response schema, no infrastructure to run.
Client code migrates in either direction, so you are never locked in.
This project is licensed under the MIT License. See LICENSE.
Contributions are welcome. See docs/CONTRIBUTING.md.
- GitHub Issues - bugs, feature ideas, and reproducible issues.
- feedback@openserp.org - private notes, longer feedback, or anything that does not fit GitHub Issues.
- Telegram - OpenSERP news, release notes, and project updates.
OpenSERP is free and open-source. Only links listed in this repository and on openserp.org are associated with the project.