The official Node.js SDK for live SERP data — Google, Bing, Yahoo, and SEO intelligence — powered by SERPHouse.
Run Google, Bing, and Yahoo searches, resolve locations, and query Jobs, Local, Videos, and more — directly from your Node.js app or TypeScript project. Structured JSON in, production-ready results out.
- Why This SDK
- Quick Start
- What You Can Build
- SDK Overview
- Client Options
- Responses & Errors
- TypeScript
- Development
- Troubleshooting
- Contributing
- License
| 20 API methods | Google, Bing, and Yahoo SERP plus Google verticals and account utilities — all typed and ready to call |
| Zero boilerplate | Auth headers, JSON parsing, and error mapping are handled for you |
| Two call styles | Use namespaced methods (client.google.search) or flat aliases (client.google_search) — same underlying API |
| TypeScript-first | Exported types for every search engine, parameter set, and response shape |
| JSON or HTML | Request structured JSON by default, or pass responseType: 'html' when you need raw markup |
1. Get your API key from the SERPHouse Dashboard.
2. Install the package:
npm install @serphouse/serphouse-nodejs3. Create a client and run your first search:
import { SERPHouse } from '@serphouse/serphouse-nodejs';
const client = new SERPHouse('YOUR_API_KEY');
const { results } = await client.google.search({
q: 'Fresh Bagels',
domain: 'google.com',
lang: 'en',
device: 'desktop',
loc: 'New York,United States',
});CommonJS?
const { SERPHouse } = require('@serphouse/serphouse-nodejs');works the same way.
For SEO teams, agencies, and SaaS builders who need live search data inside their own applications — no scrapers, no proxy management, no captcha headaches.
| Use case | SDK call |
|---|---|
| Track rankings | client.google.search({ q: 'crm software', loc: 'United States', … }) |
| Beat competitors | client.google.search with page and date_range filters |
| Own local search | client.google.local({ q: 'emergency plumber', loc: 'Chicago,Illinois,United States', … }) |
| Discover keywords | client.google.autocomplete({ q: 'best saas for', … }) — 5 credits/request |
| Monitor on Bing | client.bing.search({ q: 'your brand', loc: 'United States', device: 'mobile', … }) |
| Multi-engine coverage | client.yahoo.news alongside client.google.news for the same query |
| Resolve locations | client.extra.location_search({ q: 'Austin', type: 'google' }) → use loc or loc_id in searches |
The SERPHouse client groups 20 methods across four namespaces. Google and Bing search endpoints require exactly one location field — loc (e.g. Austin,Texas,United States) or loc_id (from extra.location_search). Never send both or omit both. Yahoo SERP methods do not require location.
| Method | Description | Docs |
|---|---|---|
extra.account_info |
Account balance, plan, and credit usage | Account Info |
extra.domain_list |
Supported Google, Bing, and Yahoo domains | Domains List |
extra.language_list |
Language codes by engine (google | bing | yahoo) |
Languages List |
extra.location_search |
Resolve city/country names to loc_id |
Locations List |
| Method | Alias | Description | Docs |
|---|---|---|---|
google.search |
google_search |
Web search | Search API |
google.image |
google_image |
Image search | Image API |
google.news |
google_news |
News search | News API |
google.shopping |
google_shopping |
Shopping & products | Shopping API |
google.video |
google_video |
Video results | Videos API |
google.short_video |
google_short_video |
Shorts, TikTok, Reels | Short Videos API |
google.local |
google_local |
Local / Maps listings | Local API |
google.jobs |
google_jobs |
Job listings | Jobs API |
google.forums |
google_forums |
Forum & discussion results | Forums API |
google.autocomplete |
google_autocomplete |
Autocomplete suggestions | Autocomplete API |
| Method | Alias | Description | Docs |
|---|---|---|---|
bing.search |
bing_search |
Web search | Search API |
bing.image |
bing_image |
Image search | Image API |
bing.news |
bing_news |
News search | News API |
| Method | Alias | Description | Docs |
|---|---|---|---|
yahoo.search |
yahoo_search |
Web search | Search API |
yahoo.image |
yahoo_image |
Image search | Image API |
yahoo.news |
yahoo_news |
News search | News API |
Endpoint-level parameter details live in the
doc/folder and on docs.serphouse.com.
Pass a second argument to the constructor to customize behavior:
| Option | Default | Description |
|---|---|---|
baseUrl |
https://api.serphouse.com |
API base URL |
timeout |
60000 |
Request timeout in milliseconds |
Authentication is key-only — pass your API key as the first constructor argument. The SDK sends it as a Bearer token on every request.
| Success shape | { status: 'success', msg: string, results: T } — every method returns a Promise resolving to this |
| HTML responses | Pass { responseType: 'html' } as the second argument on any POST method |
| Errors | Failed requests throw SERPHouseError with statusCode, apiMessage, and apiError fields |
| Validation | API validation errors arrive as structured field messages inside apiError |
Types ship with the package — no @types install needed.
| Export | Purpose |
|---|---|
SERPHouse |
Main client class |
SERPHouseError |
Typed error for failed API calls |
GoogleSearchParams |
Parameters for all Google endpoints |
BingSearchParams |
Parameters for Bing endpoints |
YahooSearchParams / YahooImageParams |
Parameters for Yahoo endpoints |
ApiSuccessResponse |
Success response wrapper |
RequestOptions |
Per-request options (responseType) |
git clone https://github.com/SERPHouse/serphouse-nodejs.git
cd serphouse-nodejs
npm install| Command | Description |
|---|---|
npm run build |
Compile TypeScript to lib/ |
npm run dev |
Watch mode — recompile on change |
npm test |
Run Jest tests (requires API_KEY in .env) |
npm run lint |
ESLint on src/ |
Copy .env.example to .env and add your API key before running integration tests.
| Issue | Fix |
|---|---|
API key is required |
Pass a non-empty string to new SERPHouse('…') |
| Invalid key | Verify your key in the SERPHouse dashboard |
| Credit exhausted | Check balance with client.extra.account_info() |
| Location error | For Google and Bing, include loc or loc_id (not both); use extra.location_search to resolve IDs |
| Request timed out | Increase timeout in client options or check network connectivity |
| Type errors | Import parameter types from @serphouse/serphouse-nodejs — see TypeScript |
Contributions are welcome. Please keep changes focused and match existing code style.
git checkout -b feature/your-feature
npm install
npm run build
npm test
git commit -m "Add your feature"
git push origin feature/your-featureThen open a Pull Request. Update this README if you change setup, configuration, or public API surface.
MIT License — Copyright SERPHouse.