Node.js - Geekflare

The official @geekflare/api-node SDK gives you full TypeScript support and handles auth, serialization, and response parsing out of the box. Raw fetch examples are included for dependency-free setups.

Prerequisites

Node.js 18+ (native fetch is stable from v18)
A Geekflare API key — get one free

Installation

pnpm
npm
yarn

bash pnpm add @geekflare/api-node

bash npm install @geekflare/api-node

bash yarn add @geekflare/api-node

Set your API key

Create a .env file at your project root:

.env

GEEKFLARE_API_KEY=your_api_key_here

Never commit your .env file. Add it to .gitignore.

Initialize the client

import { GeekflareClient } from "@geekflare/api-node";

const client = new GeekflareClient({
  apiKey: process.env.GEEKFLARE_API_KEY!,
});

Web Scraping

Scrape the full content of any URL. Returns HTML, Markdown, and more depending on the format you request.

SDK
fetch

import { GeekflareClient } from "@geekflare/api-node";

const client = new GeekflareClient({
  apiKey: process.env.GEEKFLARE_API_KEY!,
});

const result = await client.webScrape({
  url: "https://toscrape.com/",
  device: "desktop",
  renderJS: true,
  blockAds: true,
  format: "html,markdown",
});

console.log(result);

const response = await fetch("https://api.geekflare.com/webscraping", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "x-api-key": process.env.GEEKFLARE_API_KEY!,
  },
  body: JSON.stringify({
    url: "https://toscrape.com/",
    device: "desktop",
    renderJS: true,
    blockAds: true,
    format: "html,markdown",
  }),
});

const result = await response.json();
console.log(result);

Key parameters:

Parameter	Type	Description
`url`	`string`	Required. The URL to scrape
`device`	`"desktop" \| "mobile"`	Emulate device type
`renderJS`	`boolean`	Wait for JavaScript to execute
`blockAds`	`boolean`	Block ads before scraping
`format`	`string`	Comma-separated: `html`, `markdown`
`proxyCountry`	`string`	Route via country code, e.g. `"us"`
`stealth`	`boolean`	Enable stealth mode
`waitTime`	`number`	Extra wait time in seconds

Example response:

{
  "timestamp": 1779703261268,
  "apiStatus": "success",
  "apiCode": 200,
  "meta": {
    "url": "https://toscrape.com/",
    "device": "desktop",
    "format": ["html-llm"],
    "blockAds": true,
    "renderJS": true,
    "stealth": false,
    "test": { "id": "mxqx9v9y0742lap6altwdteqd28t23nq" }
  },
  "data": "https://example.com/9bulgk075ed9m3vhua5vcrp0.html"
}

The data field is a URL to the scraped output file. For full response details, see the Web Scraping endpoint reference.

Search

Run a web search and get ranked results with titles, URLs, and descriptions.

SDK
fetch

import { GeekflareClient } from "@geekflare/api-node";

const client = new GeekflareClient({
  apiKey: process.env.GEEKFLARE_API_KEY!,
});

const result = await client.search({
  query: "best static site generators",
  limit: 10,
  location: "us",
  source: "web",
  time: "m",     // past month
  format: "json",
});

console.log(result);

const response = await fetch("https://api.geekflare.com/search", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "x-api-key": process.env.GEEKFLARE_API_KEY!,
  },
  body: JSON.stringify({
    query: "best static site generators",
    limit: 10,
    location: "us",
    source: "web",
    time: "m",
    format: "json",
  }),
});

const result = await response.json();
console.log(result);

Key parameters:

Parameter	Type	Description
`query`	`string`	Required. The search query
`limit`	`number`	Number of results (default: `10`)
`location`	`string`	Country code for localized results, e.g. `"us"`
`source`	`string`	`"web"`, `"news"`, etc.
`time`	`string`	Recency filter: `"d"` (day), `"w"` (week), `"m"` (month)
`includeDomains`	`string[]`	Only return results from these domains
`excludeDomains`	`string[]`	Exclude results from these domains
`groundedAnswer`	`boolean`	Return an AI-grounded answer alongside results

Example response:

{
  "timestamp": 1779703261268,
  "apiStatus": "success",
  "apiCode": 200,
  "meta": {
    "query": "best static site generators",
    "count": 10,
    "source": "web",
    "location": "us",
    "time": "m",
    "test": { "id": "mxqx9v9y0742lap6altwdteqd28t23nq" }
  },
  "data": [
    {
      "title": "10 Best Static Site Generators in 2024",
      "url": "https://example.com/article",
      "snippet": "A comprehensive comparison of the top static site generators...",
      "date": "Dec 18, 2025",
      "position": 1,
      "content": "Full article cleaned for LLM consumption..."
    }
  ]
}

Screenshot

Capture a screenshot of any URL. Returns a hosted image URL.

SDK
fetch

import { GeekflareClient } from "@geekflare/api-node";

const client = new GeekflareClient({
  apiKey: process.env.GEEKFLARE_API_KEY!,
});

const result = await client.screenshot({
  url: "https://example.com",
  type: "png",
  fullPage: true,
  device: "desktop",
  viewportWidth: 1280,
  viewportHeight: 800,
  blockAds: true,
  hideCookie: true,
  quality: 90,
});

console.log(result);

const response = await fetch("https://api.geekflare.com/screenshot", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "x-api-key": process.env.GEEKFLARE_API_KEY!,
  },
  body: JSON.stringify({
    url: "https://example.com",
    type: "png",
    fullPage: true,
    device: "desktop",
    viewportWidth: 1280,
    viewportHeight: 800,
    blockAds: true,
    hideCookie: true,
    quality: 90,
  }),
});

const result = await response.json();
console.log(result);

Key parameters:

Parameter	Type	Description
`url`	`string`	Required. The URL to capture
`type`	`"png" \| "jpg" \| "webp"`	Output image format
`fullPage`	`boolean`	Capture beyond the visible viewport
`device`	`"desktop" \| "mobile"`	Device emulation
`viewportWidth`	`number`	Viewport width in pixels
`viewportHeight`	`number`	Viewport height in pixels
`blockAds`	`boolean`	Remove ads before capture
`hideCookie`	`boolean`	Hide cookie consent banners
`skipCaptcha`	`boolean`	Attempt to bypass CAPTCHA overlays
`delay`	`number`	Wait (seconds) before capture
`quality`	`number`	Image quality `1–100` (JPEG/WebP)
`removeBackground`	`boolean`	Remove background (PNG only)

Example response:

{
  "timestamp": 1779703261268,
  "apiStatus": "success",
  "apiCode": 200,
  "meta": {
    "url": "https://example.com",
    "type": "png",
    "device": "desktop",
    "fullPage": true,
    "blockAds": true,
    "hideCookie": true,
    "viewportWidth": 1280,
    "viewportHeight": 800,
    "quality": 90,
    "test": { "id": "mxqx9v9y0742lap6altwdteqd28t23nq" }
  },
  "data": "https://geekflare.com/tests/screenshot/kbi6d206g87ituahb7icwtpr.png"
}

The data field is a direct URL to the screenshot image. See the Screenshot endpoint reference.

Error handling

The SDK throws on API errors. Wrap calls in try/catch and inspect the error for actionable codes.

import { GeekflareClient } from "@geekflare/api-node";

const client = new GeekflareClient({
  apiKey: process.env.GEEKFLARE_API_KEY!,
});

try {
  const result = await client.webScrape({ url: "https://toscrape.com/" });
  console.log(result);
} catch (error: any) {
  console.error("API error:", error);

  const code = error?.apiCode ?? error?.status;

  switch (code) {
    case 401:
      console.error("Invalid or missing API key.");
      break;
    case 402:
      console.error("API credits exhausted. Top up at dash.geekflare.com.");
      break;
    case 403:
      console.error("This endpoint is not available on your current plan.");
      break;
    case 429:
      console.error("Rate limit exceeded. Back off and retry.");
      break;
    default:
      console.error(`Unexpected error [${code}]:`, error.message);
  }
}

Common error codes

Code	Meaning
`401`	Missing or invalid `x-api-key` header
`402`	API credits exhausted
`403`	Endpoint requires a higher plan
`404`	Wrong endpoint URL or HTTP method
`429`	Rate limit exceeded

See Rate Limit Exceeded and Credit Exhausted for strategies to handle these gracefully.

Next steps

Next.js quickstart — Server Actions and Route Handlers
NestJS quickstart — Injectable services and modules
API Reference — Full endpoint documentation
SDK on npm

Documentation Index

​Prerequisites

​Installation

​Set your API key

​Initialize the client

​Web Scraping

​Search

​Screenshot

​Error handling

​Common error codes

​Next steps

Prerequisites

Installation

Set your API key

Initialize the client

Web Scraping

Search

Screenshot

Error handling

Common error codes

Next steps