# Serphouse Nodejs

> Teach AI agents to use @serphouse/serphouse-nodejs SDK for typed SERP data access

- **Type:** Skill
- **Install:** `agentstack add skill-serphouse-agent-skills-nodejs`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [SERPHouse](https://agentstack.voostack.com/s/serphouse)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [SERPHouse](https://github.com/SERPHouse)
- **Source:** https://github.com/SERPHouse/agent-skills/tree/master/skills/nodejs

## Install

```sh
agentstack add skill-serphouse-agent-skills-nodejs
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# @serphouse/serphouse-nodejs SDK Skill

This skill equips the agent to use the official [SERPHouse Node.js SDK](https://github.com/SERPHouse/serphouse-nodejs) (`@serphouse/serphouse-nodejs`) for live SERP data — Google, Bing, Yahoo search results plus Jobs, Local, Videos, Shopping, Autocomplete, and more.

## When to Use

Trigger when the user's project uses (or should use) `@serphouse/serphouse-nodejs` and needs help with:

| Category | Example prompts |
|---|---|
| **Setup** | "Install serphouse-nodejs and set up the client" |
| **Google SERP** | "Search Google for 'best CRM' from the US on desktop" |
| **Bing/Yahoo SERP** | "Run a Bing news search for 'AI startups'" |
| **Google Verticals** | "Find software engineer jobs on Google Jobs in SF" or "Get autocomplete suggestions for 'best saas'" |
| **Location** | "Find the loc_id for Austin, Texas" |
| **Account** | "Check my SERPHouse credit balance" |
| **Error handling** | "Catch and log SERPHouse API errors" |
| **TypeScript** | "Import the correct types for a Google search" |
| **HTML responses** | "Get raw HTML instead of JSON" |

Do **not** trigger for general web scraping or non-SERPHouse APIs.

## Installation

```bash
npm install @serphouse/serphouse-nodejs
```

Requires Node.js 18+ (uses `fetch` natively). No runtime dependencies.

## Quick Start

```typescript
import { SERPHouse } from '@serphouse/serphouse-nodejs';

const client = new SERPHouse('YOUR_API_KEY');

// Namespaced style
const { results } = await client.google.search({
  q: 'Fresh Bagels',
  domain: 'google.com',
  lang: 'en',
  device: 'desktop',
  loc: 'New York,United States',
});

// Flat alias style (same result)
const { results } = await client.google_search({
  q: 'Fresh Bagels',
  domain: 'google.com',
  lang: 'en',
  device: 'desktop',
  loc: 'New York,United States',
});
```

CommonJS is also supported:
```javascript
const { SERPHouse } = require('@serphouse/serphouse-nodejs');
```

## Client Options

```typescript
const client = new SERPHouse('API_KEY', {
  baseUrl: 'https://api.serphouse.com', // default
  timeout: 60000, // default, ms
});
```

## Complete API Reference (20 methods)

### Extra / Utility

| Method | Description |
|---|---|
| `client.extra.account_info()` or `client.account_info()` | Account balance, plan, credits |
| `client.extra.domain_list()` or `client.domain_list()` | Supported domains per engine |
| `client.extra.language_list(type)` or `client.language_list(type)` | Language codes for `google`, `bing`, or `yahoo` |
| `client.extra.location_search({ q, type })` or `client.location_search()` | Resolve city/country to `loc_id` |

### Google (10 methods)

| Method | Alias | Endpoint |
|---|---|---|
| `client.google.search(params)` | `client.google_search` | Web search |
| `client.google.image(params)` | `client.google_image` | Image search |
| `client.google.news(params)` | `client.google_news` | News search |
| `client.google.shopping(params)` | `client.google_shopping` | Shopping |
| `client.google.video(params)` | `client.google_video` | Videos |
| `client.google.short_video(params)` | `client.google_short_video` | Shorts/TikTok/Reels |
| `client.google.local(params)` | `client.google_local` | Local/Maps |
| `client.google.jobs(params)` | `client.google_jobs` | Job listings |
| `client.google.forums(params)` | `client.google_forums` | Forum discussions |
| `client.google.autocomplete(params)` | `client.google_autocomplete` | Autocomplete (5 credits) |

### Bing (3 methods)

| Method | Alias | Endpoint |
|---|---|---|
| `client.bing.search(params)` | `client.bing_search` | Web search |
| `client.bing.image(params)` | `client.bing_image` | Image search |
| `client.bing.news(params)` | `client.bing_news` | News search |

### Yahoo (3 methods)

| Method | Alias | Endpoint |
|---|---|---|
| `client.yahoo.search(params)` | `client.yahoo_search` | Web search |
| `client.yahoo.image(params)` | `client.yahoo_image` | Image search |
| `client.yahoo.news(params)` | `client.yahoo_news` | News search |

## Parameter Rules

### GoogleSearchParams / BingSearchParams

```typescript
interface GoogleSearchParams {
  q: string;            // required
  domain: string;       // required (e.g. 'google.com', 'google.co.uk')
  lang: string;         // required (e.g. 'en', 'fr')
  device: Device;       // required ('desktop' | 'mobile')
  loc?: string;         // location string (e.g. 'Austin,Texas,United States')
  loc_id?: number;      // location ID (from location_search) — mutually exclusive with loc
  page?: number;        // page number (default 1)
  date_range?: DateRange; // 'h' | 'd' | 'w' | 'm' | 'y' | 'YYYY-MM-DD,YYYY-MM-DD'
  no_trace?: NoTrace;   // boolean | 0 | 1 | '0' | '1' | 'true' | 'false'
}
```

**Critical:** Google and Bing methods require exactly **one** of `loc` or `loc_id`. Never send both or omit both.

### YahooSearchParams

```typescript
interface YahooSearchParams {
  q: string;       // required
  domain: string;  // required (e.g. 'yahoo.com')
  lang: string;    // required
  device: Device;  // required ('desktop' | 'mobile')
  page?: number;
  no_trace?: NoTrace;
}
```

Yahoo SERP methods do **not** require location.

## Response Shape

Every method returns `Promise>`:

```typescript
interface ApiSuccessResponse {
  status: 'success';
  msg: string;
  results: T;  // the SERP data — shape varies by endpoint
}
```

The `results` field contains the actual search results. The shape differs per endpoint/engine — refer to the SERPHouse API docs for each endpoint's response structure.

## HTML Responses

Pass `{ responseType: 'html' }` as the second argument to any POST method to get raw HTML instead of JSON:

```typescript
const { results } = await client.google.search(
  { q: 'test', domain: 'google.com', lang: 'en', device: 'desktop', loc: 'US' },
  { responseType: 'html' },
);
```

## Error Handling

Failed requests throw `SERPHouseError`:

```typescript
import { SERPHouse, SERPHouseError } from '@serphouse/serphouse-nodejs';

try {
  const { results } = await client.google.search(params);
} catch (error) {
  if (error instanceof SERPHouseError) {
    console.error(error.statusCode);   // HTTP status (e.g. 400, 401, 429)
    console.error(error.apiMessage);   // API error message
    console.error(error.apiError);     // Structured field errors or raw string
  }
}
```

Common errors:
- `API key is required` — empty key passed to constructor
- `401` — invalid API key
- `429` — rate limit exceeded (60 req/min on most plans)
- `400` with location errors — missing or conflicting `loc`/`loc_id`

## TypeScript Types

All types ship with the package — no `@types/` install needed.

```typescript
import {
  SERPHouse,
  SERPHouseError,
  GoogleSearchParams,
  BingSearchParams,
  YahooSearchParams,
  YahooImageParams,
  LocationSearchParams,
  ApiSuccessResponse,
  ApiErrorResponse,
  ClientOptions,
  RequestOptions,
  Device,
  DateRange,
  LanguageType,
  LocationType,
  NoTrace,
  ResponseType,
} from '@serphouse/serphouse-nodejs';
```

## Complete Usage Examples

### Location Resolution → Search

```typescript
// Step 1: Find location ID
const { results: locations } = await client.extra.location_search({
  q: 'Austin',
  type: 'google',
});
const locId = locations[0]?.loc_id; // use in subsequent calls

// Step 2: Search with loc_id
const { results } = await client.google.search({
  q: 'coffee shops',
  domain: 'google.com',
  lang: 'en',
  device: 'desktop',
  loc_id: locId,
});
```

### Check Account Before Searching

```typescript
const { results: account } = await client.account_info();
console.log(`Credits remaining: ${account.credits}`);
```

### Multi-Engine Comparison

```typescript
const [googleResults, bingResults, yahooResults] = await Promise.all([
  client.google.search({ q: 'AI tools', domain: 'google.com', lang: 'en', device: 'desktop', loc: 'US' }),
  client.bing.search({ q: 'AI tools', lang: 'en', device: 'desktop', loc: 'US' }),
  client.yahoo.search({ q: 'AI tools', domain: 'yahoo.com', lang: 'en', device: 'desktop' }),
]);
```

### Google Jobs with Date Filter

```typescript
const { results } = await client.google.jobs({
  q: 'software engineer',
  domain: 'google.com',
  lang: 'en',
  device: 'desktop',
  loc: 'San Francisco,California,United States',
  date_range: 'w', // past week
});
```

### Pagination

```typescript
const page1 = await client.google.search({ q: 'node.js', domain: 'google.com', lang: 'en', device: 'desktop', loc: 'US', page: 1 });
const page2 = await client.google.search({ q: 'node.js', domain: 'google.com', lang: 'en', device: 'desktop', loc: 'US', page: 2 });
```

## Credit Costs

- Most searches: **1 credit per page**
- Google Autocomplete: **5 credits**
- Google Advanced (not in SDK — use REST directly): **10 credits/page**

## Important Notes

- The SDK has **no runtime dependencies** — it uses Node.js 18+ native `fetch`.
- All POST endpoints accept `responseType: 'html'` for raw markup.
- `page` parameter is 1-indexed (page 1 = first page of results).
- The `doc/` folder in the repo and [docs.serphouse.com](https://docs.serphouse.com) have endpoint-specific parameter details.

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [SERPHouse](https://github.com/SERPHouse)
- **Source:** [SERPHouse/agent-skills](https://github.com/SERPHouse/agent-skills)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-serphouse-agent-skills-nodejs
- Seller: https://agentstack.voostack.com/s/serphouse
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.