# SerpAPI

Structured engine-specific SERP data; normalized search begins with Google organic results.

Canonical: https://searchsdk.dev/docs/providers/serpapi
Markdown: https://searchsdk.dev/docs/providers/serpapi.md

<a id="overview"></a>

## Normalized search

> **TypeScript reference**
> The API names, code and policy behavior in this article describe the TypeScript SDK. See [your language guide](https://searchsdk.dev/docs/sdks) for its supported surface and limits.

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.

**serpapi-search.ts · server**

```typescript
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.

<a id="native-client"></a>

## Provider-native client

**serpapi-native.ts · server**

```typescript
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.

<a id="operations"></a>

## 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.

| Method | HTTP / relative path | Response / retry eligibility |
| --- | --- | --- |
| `search` | `GET /search.json` | json · no automatic retry |
| `searchHtml` | `GET /search.html` | text · no automatic retry |
| `searchMarkdown` | `GET /search.md` | text · no automatic retry |
| `searchPixelPositions` | `GET /search.json_with_pixel_position` | json · no automatic retry |
| `getSearch` | `GET /searches/{search_id}.json` | json · eligible |
| `getSearchHtml` | `GET /searches/{search_id}.html` | text · eligible |
| `getSearchPixelPositions` | `GET /searches/{search_id}.json_with_pixel_position` | json · no automatic retry |
| `locations` | `GET /locations.json` | json · eligible |
| `account` | `GET /account.json` | json · eligible |
| `uploadImage` | `POST /image` | json · no automatic retry |

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.

<a id="lifecycle"></a>

## 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.

<a id="sources"></a>

## Official sources

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

- [Google Search API reference](https://serpapi.com/search-api)

- [Native request and response reference](https://searchsdk.dev/docs/api/native-transport)
- [All providers](https://searchsdk.dev/docs/providers)