Official TypeScript client for Search1API. It supports Node.js 18+ and runtimes
with a standards-compatible fetch implementation.
API documentation: search1api.com/docs
npm install @search1api/clientimport { Search1API } from '@search1api/client';
const client = new Search1API({
apiKey: process.env.SEARCH1API_API_KEY,
});
const response = await client.search('latest AI agent frameworks', {
maxResults: 10,
crawlResults: 3,
});
for (const result of response.results) {
console.log(result.title, result.link);
}The constructor reads SEARCH1API_API_KEY when apiKey is omitted.
searchService selects one engine (google by default), for example bing,
bingcn, yandex, reddit, github, arxiv, wikipedia, or grokipedia.
page requests a later results page on engines with native pagination
(bing, bingcn, baidu, grokipedia). Results carry published_date when the source
exposes one. Engine-specific fields are in each result's optional metadata:
GitHub uses metadata.kind, metadata.stars, metadata.language, and
metadata.num_comments; Hacker News news results use metadata.story_url,
metadata.points, and metadata.num_comments. The former top-level paths
are removed in 0.4.0; published_date stays at the top level.
CommonJS projects can load the same client with require:
const { Search1API } = require('@search1api/client');ask sends a natural-language request and lets Search1API choose the engines
and time window. It returns at most 10 results ranked by relevance, and
intent reports what was searched:
const answer = await client.ask(
'What are developers saying about Bun 1.3 this month?'
);
console.log(answer.intent.sources, answer.intent.time_range);
for (const result of answer.results) {
console.log(result.relevance, result.source, result.title, result.link);
}A completed request costs 5 credits. Ask is not available with pay-per-request
payments, and its default timeout is 45 seconds. Use search when you already
know which engine and keywords you want.
maps searches Google Maps and returns one page of up to 20 places. Each place
has a name, place ID and Maps link, plus address, phone, website, rating,
review count, coordinates and opening hours when available:
const places = await client.maps('coffee shops', {
location: { latitude: 40.7455, longitude: -74.0083, zoom: 15 },
maxResults: 10,
});
for (const place of places.results) {
console.log(place.name, place.rating, place.address);
}A completed page costs 3 credits, including a confirmed empty page.
maxResults only trims the page and does not lower the price. Request page
2-6 with the same query and location for more places; each page is billed
separately. Maps is not available with pay-per-request payments.
deepcrawl starts a task and waits for it to finish:
const result = await client.deepcrawl('https://example.com', { type: 'all' });
console.log(result.zipUrl);maxPages (1-1000, default 1000) caps the crawl after the path rules.
includePaths and excludePaths take up to 20 rules each, matched against
the URL path: a rule without * is a path prefix (/docs matches /docs/api
but not /docsearch), a rule with * must match the whole path, and exclusion
wins. format: 'json' returns the pages in the completed status response
instead of a ZIP:
const result = await client.deepcrawl('https://hono.dev/docs/', {
maxPages: 20,
includePaths: ['/docs/'],
excludePaths: ['/docs/changelog'],
format: 'json',
});
for (const page of result.pages ?? []) {
console.log(page.url, page.title, page.content.length);
}
console.log(result.stats, result.failed);pages is omitted when the result is larger than 5 MB; download resultUrl
instead. A task costs 20 credits regardless of the page count.
Use startDeepcrawl, getDeepcrawlStatus, and waitForDeepcrawl when the
application needs to control task persistence or polling itself.
Screenshot responses are binary image bytes rather than JSON:
import { writeFile } from 'node:fs/promises';
const screenshot = await client.screenshot('https://example.com', {
format: 'png',
fullPage: true,
});
await writeFile('screenshot.png', screenshot.data);
console.log(screenshot.contentType, screenshot.requestId);extract pulls structured fields out of one page. Both prompt and
responseFormat are required; wrap your JSON Schema as
{ type: 'json_schema', json_schema: <schema> }:
const response = await client.extract<{ title: string; price: number }>(
'https://example.com/product',
{
prompt: 'Extract the product name and price.',
responseFormat: {
type: 'json_schema',
json_schema: {
type: 'object',
properties: {
title: { type: 'string' },
price: { type: 'number' },
},
},
},
}
);
console.log(response.results.title, response.results.price);A request without either field fails with UnprocessableEntityError (422).
The client also provides news, crawl, sitemap, trending,
usage, and their batch variants where the HTTP API supports them.
feedback reports a Search1API problem, missing capability, or confusing
documentation. It is free and is never retried automatically, because a retry
could file a duplicate report. Do not include credentials or personal data:
await client.feedback('Results for this query have no publication dates', {
category: 'feature_request',
requestId: 'the x-search1api-request-id of the original request',
});Requests time out after 30 seconds and retry 429 and transient 5xx
responses twice by default. Authentication, payment, and validation errors are
never retried. Deepcrawl task creation and feedback are not retried
automatically because they are not idempotent. Configure this with timeoutMs
and maxRetries.
npm install
npm run generate
npm run typecheck
npm test
npm run buildThe generated wire-level types come from the checked-in public OpenAPI snapshot. Update the snapshot before regenerating types when the API contract changes.
MIT