Node.js

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

pnpm add @geekflare/api-node

npm install @geekflare/api-node

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

Getting started

Quickstarts

Guides

MCP Server

Capabilities

Best Practices

Troubleshooting

Changelog

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

Prerequisites

Installation

Set your API key

Initialize the client

Web Scraping

Search

Screenshot

Error handling

Common error codes

Next steps