Serphouse Nodejs

@serphouse/serphouse-nodejs SDK Skill

This skill equips the agent to use the official SERPHouse Node.js SDK (@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

npm install @serphouse/serphouse-nodejs

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

Quick Start

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:

const { SERPHouse } = require('@serphouse/serphouse-nodejs');

Client Options

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

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

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>:

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:

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:

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.

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

// 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

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

Multi-Engine Comparison

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

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

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 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
• Source: SERPHouse/agent-skills
• License: MIT

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