JavaScript SDK
v1.1.0
JavaScript/Node.js SDK
Official JavaScript SDK for SearchHive APIs. Zero runtime dependencies, native fetch, full TypeScript support. Requires Node.js 18+.
Zero Dependencies
searchhive-js has zero runtime dependencies and uses the native fetch API. It works in Node.js 18+, modern browsers, and edge runtimes like Vercel Edge Functions and Cloudflare Workers.Quick Start
1. Install
Installation
2. Initialize
Set up the client
JavaScript
import { SearchHive, SearchHiveError, RateLimitError, AuthenticationError } from 'searchhive-js';
const client = new SearchHive({
apiKey: 'sk_live_your_key_here',
// baseURL: 'https://www.searchhive.dev/api/v1', // default
});Core Methods
| Method | Description | Returns |
|---|---|---|
| swiftSearch(options) | Real-time web search with optional auto-scraping | SwiftSearchResponse |
| scrapeForge(options) | Extract content from a single webpage | ScrapeForgeResponse |
| deepDive(options) | Multi-page research with summarization | DeepDiveResponse |
| batchScrape(options) | Scrape multiple URLs in one request | ScrapeForgeResponse[] |
| health() | Check API health status | HealthResponse |
SwiftSearch
Real-time web search with optional auto-scraping of top results, contact extraction, and social profile lookup.
SwiftSearch Example
JavaScript
// Search with optional auto-scraping of top results
const result = await client.swiftSearch({
query: 'latest AI developments 2025',
max_results: 10,
auto_scrape_top: 3,
include_contacts: true,
include_social: true
});
console.log(`Found ${result.results_count} results, ${result.scraped_count} scraped`);
console.log(`Credits used: ${result.credits_used}, remaining: ${result.remaining_credits}`);
result.search_results.forEach((r) => {
console.log(`${r.position}. ${r.title}`);
console.log(` ${r.link}`);
console.log(` ${r.snippet}`);
});
// If auto_scrape_top was set, scraped content is included:
result.scraped_content.forEach((page) => {
console.log(`Scraped: ${page.url} — ${page.text.length} chars`);
});ScrapeForge
Extract structured content from any webpage — title, text, links, images, and metadata.
ScrapeForge Example
JavaScript
// Scrape a single page
const page = await client.scrapeForge({
url: 'https://example.com/article',
extract: ['title', 'text', 'links', 'images'],
wait_for: '.content',
timeout: 30,
use_browser: false
});
console.log('Title:', page.title);
console.log('Content length:', page.text.length);
console.log('Links found:', page.links.length);
console.log('Images found:', page.images.length);
console.log('Credits remaining:', page.remaining_credits);DeepDive
Multi-page research that searches, scrapes multiple sources, and returns a summary.
DeepDive Example
JavaScript
// Research a topic across multiple sources
const research = await client.deepDive({
query: 'sustainable energy solutions 2025',
max_pages: 10,
extract_content: true,
include_domains: ['nature.com', 'ieee.org'],
exclude_domains: ['spam-site.com']
});
console.log('Summary:', research.summary);
console.log('Pages scraped:', research.scraped_content.length);
console.log('Credits remaining:', research.remaining_credits);Batch Scrape
Scrape multiple URLs in a single request.
Batch Scrape Example
JavaScript
// Scrape multiple URLs at once
const results = await client.batchScrape({
urls: [
'https://example.com/page1',
'https://example.com/page2',
'https://example.com/page3'
],
extract: ['title', 'text'],
timeout: 30,
use_browser: false
});
results.forEach((page) => {
if (page.error) {
console.error(`Failed ${page.url}: ${page.error}`);
} else {
console.log(`OK: ${page.url} — ${page.title}`);
}
});Health Check
API Health Check
JavaScript
// Check API status
const health = await client.health();
console.log('API status:', health.status);Error Handling
The SDK exports three error classes for specific handling:
SearchHiveError— Base error for all API errors (includesstatusCode,message)RateLimitError— Thrown on rate limit (includesretryAfter)AuthenticationError— Invalid or missing API key
Error Handling Example
JavaScript
import { SearchHiveError, RateLimitError, AuthenticationError } from 'searchhive-js';
try {
const result = await client.swiftSearch({ query: 'test' });
} catch (error) {
if (error instanceof RateLimitError) {
console.error(`Rate limited. Retry after ${error.retryAfter}s`);
} else if (error instanceof AuthenticationError) {
console.error('Invalid API key');
} else if (error instanceof SearchHiveError) {
console.error(`API error (${error.statusCode}): ${error.message}`);
} else {
throw error;
}
}TypeScript
The SDK ships with full TypeScript type definitions. All method options and response shapes are fully typed — just install and import with full autocompletion.
Key Features
Zero Dependencies
No runtime dependencies. Uses native fetch for maximum compatibility and minimal bundle size.
Full TypeScript Support
Complete type definitions for all methods, options, and responses out of the box.
Node.js 18+
Built on native fetch. Works in Node.js 18+, modern browsers, and edge runtimes.
Clean Error Handling
Specific error classes for rate limits, auth failures, and general API errors.
Resources
External Resources