SerpAPI

Normalized search#

Normalized search uses synchronous Google search and maps organic results only. It checks provider error/status information even after an HTTP success. Native engine selection preserves engine-specific fields.

import { createSearch } from '@belweave/search-sdk';
import { serpapi } from '@belweave/search-sdk/serpapi';

const apiKey = process.env.SERPAPI_API_KEY;
if (!apiKey) throw new Error('SERPAPI_API_KEY is required');

const client = createSearch({ provider: serpapi({ apiKey }) });
const response = await client.web.search({
  query: 'SQLite write concurrency',
  limit: 5,
});
console.log(response.results, response.attempts);

Selecting an engine on the native client is not a claim that every engine has an independently tested normalized adapter. Async search, archives, pagination, and rich result categories require their own handling. Provider URLs may contain account-sensitive query parameters; avoid logging them.

Domain filters unavailable on the normalized adapter.

Provider-native client#

import { createSerpApiClient } from '@belweave/search-sdk/native-serpapi';

const apiKey = process.env.SERPAPI_API_KEY;
if (!apiKey) throw new Error('SERPAPI_API_KEY is required');

const client = createSerpApiClient({ apiKey, timeoutMs: 10_000 });
const response = await client.search({ query: { engine: 'google', q: 'SQLite write concurrency' } });
console.log(response.data, response.metadata);

Read provider data from response.data and sanitized transport details from response.metadata. Native TypeScript response types are not runtime schema validation. Preserve the operation's native response and source identities.

Native operation inventory#

Methods available on this native client. Paths are relative to each operation's fixed base; a provider may use more than one origin. Eligible operations retry only when you opt into a client retry policy.

Additional client helpers: google, extract, extractMarkdown. These reuse catalog operations or expose a native output variant. Their input and response types remain in the provider subpath.

Limits and operation lifecycle#

• Pass signal and per-call timeoutMs on native request input when needed.
• Persist a returned job identifier before explicitly reading or polling the same job. Native clients do not automatically poll.
• SSE data is incremental provider event text. Parse and validate terminal or error events according to the provider contract; there is no reconnect or replay.
• Native operations may create, delete, ingest, or incur charges. A successful HTTP response is not proof that a remote job completed.

Official sources#

Use the official reference for current schemas, account access, and operation-specific requirements.

• Google Search API reference↗

• Native request and response reference↗
• All providers↗