@openserp/sdk

npm install @openserp/sdk

Cloud:

import { OpenSERP } from "@openserp/sdk";

const client = new OpenSERP({ apiKey: process.env.OPENSERP_API_KEY });
const { results } = await client.search({ engine: "google", text: "openserp" });

console.log(results[0]?.title, results[0]?.url);

Self-hosted:

import { OpenSERP } from "@openserp/sdk";

const client = new OpenSERP({ baseUrl: "http://localhost:7000" });
const { results } = await client.search({ engine: "bing", text: "openserp" });

console.log(results[0]?.title, results[0]?.url);

Universal TypeScript / JavaScript SDK for the OpenSERP multi-engine SERP API - Google, Bing, Yandex, Baidu, DuckDuckGo, and Ecosia results in a single call. Works against the self-hosted open source server and against OpenSERP Cloud with the same code.

Use it for AI grounding, RAG pipelines, LLM tool use, agent tool use, LangChain / LlamaIndex integrations, SEO rank tracking, competitor analysis, and search-powered automations. Open-source alternative to SerpAPI, DataForSEO, ScrapingBee, Bright Data SERP, Oxylabs SERP, and Zenserp.

Also available for Python: openserp.

Alpha - the API may change before 1.0.0. Pin a version in production.

Contents

• Install
• Why OpenSERP
• Quickstart - OSS (self-hosted)
• Quickstart - Cloud
• Why two backends?
• Search
• Extract
• Images
• Endpoint availability
• Telemetry
• Error handling
• Retry hook
• Use cases

Install

npm install @openserp/sdk

yarn add @openserp/sdk

pnpm add @openserp/sdk

bun add @openserp/sdk

ESM and CommonJS builds are both shipped. Requires Node 18+ and a global fetch (any modern runtime).

Why OpenSERP

| Need | OpenSERP fit | | --- | --- | | Local development | Run the OSS server and use the same SDK surface as Cloud. | | AI grounding | Pull fresh SERP snippets and optional extracted page text for prompts, RAG, or agents. | | SEO checks | Query Google, Bing, Yandex, Baidu, DuckDuckGo, and Ecosia with typed params. | | Migration path | Start self-hosted, then switch to Cloud by adding OPENSERP_API_KEY. |

Compared with hosted-only SERP APIs, OpenSERP keeps the client contract portable. You can test locally without an API key, then use the hosted API when you want managed infrastructure.

Quickstart - OSS (self-hosted)

Run the open source server locally, no API key required:

docker run -p 7000:7000 karust/openserp serve

import { OpenSERP } from "@openserp/sdk";

const client = new OpenSERP({
  baseUrl: "http://localhost:7000",
});

const results = await client.search({
  engine: "google",
  text: "openserp",
  limit: 10,
  region: "US",
  lang: "EN",
});

console.log(results.results[0]?.title);

Quickstart - Cloud

Get an API key from the API keys section in the dashboard. When apiKey is set, the SDK defaults baseUrl to https://api.openserp.org/v1 and sends Authorization: Bearer ... for you.

import { OpenSERP } from "@openserp/sdk";

const client = new OpenSERP({
  apiKey: process.env.OPENSERP_API_KEY,
  timeoutMs: 30_000,
});

const results = await client.search({
  engine: "google",
  text: "openserp",
});

console.log(client.lastResponse?.credits); // { used, remaining }

If both baseUrl and apiKey are set, baseUrl wins and the key is still sent. Use this for an authenticated self-hosted deployment. Add backend: "oss" when you also need OSS-only methods such as stats() or health().

Why two backends?

OpenSERP Cloud uses the same public HTTP contract as the OSS server, with a /v1/ prefix and bearer auth. The same SDK call works on both; you only change baseUrl / apiKey. Start with OSS locally, then move to Cloud when you want the hosted API. See openserp.org/docs/oss-vs-cloud for the full comparison.

Search

const single = await client.search({
  engine: "bing",
  text: "golang",
  limit: 10,
  region: "US",
});

const mega = await client.megaSearch({
  text: "golang",
  engines: ["google", "bing", "yandex"],
  mode: "balanced",
  limit: 20,
});

const fast = await client.fastSearch({
  text: "golang",
  engines: ["google", "bing"],
});

const any = await client.anySearch({
  text: "golang",
  engines: ["google", "yandex"],
});

megaSearch aggregates multiple engines. mode is "balanced" (default, merged and deduplicated), "any" (first successful engine wins), or "fast" (uses the fastest healthy engine). fastSearch / anySearch are sugar for the matching mode.

To enrich top search results with cleaned page content, pass the extraction flags:

const grounded = await client.search({
  engine: "google",
  text: "openserp docs",
  extract: 3,
  extractMode: "auto",
  minRunes: 500,
});

console.log(grounded.results[0]?.extracted?.content);

Extract

const page = await client.extract({
  url: "https://openserp.org/docs",
  mode: "auto",
  clean: true,
});

console.log(page.markdown);

Use minRunes to set the auto-mode escalation floor, clean: false for whole-page readable extraction, and useLlmsTxt: true to prefer /llms-full.txt or /llms.txt for site-root URLs. Non-JSON formats are returned as strings:

const markdown = await client.extract({
  url: "https://openserp.org",
  format: "markdown",
});

Images

const images = await client.image({
  engine: "bing",
  text: "golang logo",
  limit: 20,
});

const megaImages = await client.megaImage({
  text: "golang logo",
  engines: ["bing", "google"],
});

Endpoint availability

OSS-only operational methods throw OssOnlyError when the client is configured for Cloud:

await client.parseGoogle({ html: "<html>...</html>" });
await client.stats();
await client.health();

Cloud-only account methods throw CloudOnlyError when the client is configured for OSS:

await client.me();
await client.pricing();
await client.enginesStatus();
await client.enginesCapabilities();

The backend is inferred from baseUrl and apiKey. Pass backend: "oss" or backend: "cloud" to the constructor to override.

Telemetry

client.lastResponse is updated after each HTTP response:

console.log(client.lastResponse?.credits); // Cloud - { used, remaining }
console.log(client.lastResponse?.engineUsed); // both - X-Engine-Used
console.log(client.lastResponse?.fallbackEngine); // OSS only
console.log(client.lastResponse?.cache); // OSS only

Some self-hosted operational headers are not part of the Cloud response contract, so expect those fields to be undefined against api.openserp.org. credits is Cloud-specific.

Error handling

import { CaptchaError, RateLimitError, SERPError } from "@openserp/sdk";

try {
  await client.search({ engine: "google", text: "openserp" });
} catch (err) {
  if (err instanceof RateLimitError) {
    // slow down or queue the request
  } else if (err instanceof CaptchaError) {
    // inspect the upstream search failure and retry later
  } else if (err instanceof SERPError) {
    console.error(err.status, err.code, err.reason, err.requestId);
  }
}

Retry hook

The SDK does not apply a retry policy. Provide a hook when you want one:

import { OpenSERP, SERPError } from "@openserp/sdk";

const RETRYABLE = new Set([408, 429, 500, 502, 503]);

const client = new OpenSERP({
  apiKey: process.env.OPENSERP_API_KEY,
  retry: async (err, attempt) => {
    if (attempt >= 2 || !(err instanceof SERPError) || !RETRYABLE.has(err.status)) {
      return false;
    }
    const wait = Math.min(2 ** attempt * 250, 8_000) + Math.random() * 250;
    await new Promise((r) => setTimeout(r, wait));
    return true;
  },
});

Use cases

• AI grounding / RAG - feed top-N search results into an LLM prompt (OpenAI, Anthropic, Ollama) for up-to-date answers.
• LLM tool use - expose client.search as a tool to your agent.
• SEO monitoring - daily rank tracking across multiple engines and regions, export to Sheets or Notion.
• Competitor analysis - weekly diff of top-10 results for a keyword set.
• Data pipelines - stream SERPs to ClickHouse, BigQuery, or a DataFrame for NLP on snippets.