9cc69da758
- Add structured `search [engine] [query]` CLI: --limit/--lang/--region/--site/--file, --format (json|text|markdown|ndjson), --extract N, --search-timeout; Envelope and route logs to stderr with a --quiet default (fixes stdout pollution) - Unify engines behind a single engineSpec registry (CLI + serve share it) - Unify the extract knob to bool-or-int `extract=N` (drop extract_top); CLI and HTTP share core batch extraction, raw/rendered fetch, and clamp helpers - Engines: Ecosia CF captcha detection (raw + browser), Yandex progressive-result wait, Google PAA poll + Has() existence probes, Bing title/desc attribute fallbacks - Proxy: rotate challenged proxies out of the tag pool for one retry (X-Proxy-Attempts); browser health-ping skip window; opt-in WaitStable
OpenSERP Examples
Short, copy-pasteable examples for using OpenSERP from JavaScript and Python. Each one runs against a local server by default and works the same against the hosted API by swapping in an API key.
Start a server
Most examples expect OpenSERP running on http://localhost:7000.
# Docker
docker run -p 127.0.0.1:7000:7000 -it karust/openserp serve -a 0.0.0.0 -p 7000
# Or from source
go build -o openserp . && ./openserp serve
Prefer not to run a server? Skip ahead to Using the hosted API.
Try it without code
A search is a single HTTP GET, so you can check the server with curl:
# One engine
curl "http://localhost:7000/google/search?text=open+source+search+api&limit=10"
# Several engines at once
curl "http://localhost:7000/mega/search?text=open+source+search+api&engines=bing,duckduckgo&limit=10"
SDKs and integrations
| Tool | Package | Install |
|---|---|---|
| JavaScript / TypeScript | @openserp/sdk |
npm install @openserp/sdk |
| Python | openserp |
pip install openserp |
| MCP server (AI agents) | @openserp/mcp |
npx @openserp/mcp |
| n8n community node | @openserp/n8n-nodes-openserp |
Install via n8n community nodes |
Examples by question
Getting started
- How do I run a search from code? — JavaScript · Python
- How do I compare results across several engines? — JavaScript
- How do I search a list of keywords and export them? — Python
AI and LLM grounding
- How do I ground an LLM answer in fresh search results? — JavaScript
- How do I give a search tool to an agent? — Python
- I want this inside Claude, Cursor, or another MCP client. —
@openserp/mcp
SEO
- Who are my real competitors for a set of keywords? — JavaScript
- Where does my domain rank for each keyword? — Python
Content extraction
- How do I search and read the page content in one call? — JavaScript
- How do I turn a URL into clean Markdown? — Python
Images
- How do I search images and preview them? — JavaScript
Automation
- I want to wire OpenSERP into a no-code workflow. —
@openserp/n8n-nodes-openserp
Using the hosted API
Every example points at a local server. To use the managed API instead, get a key from openserp.org/dashboard/keys and construct the client with it — no base URL needed:
const client = new OpenSERP({ apiKey: "<YOUR_API_TOKEN>" });
client = OpenSERP(api_key="<YOUR_API_TOKEN>")
The endpoints and response shape are identical, so example code moves between
self-hosted and hosted by changing only that one line. Set either baseUrl
(self-hosted) or apiKey (hosted) — not both.