examples

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.