> ## Documentation Index
> Fetch the complete documentation index at: https://docs.geekflare.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Web Search

> Search the web, news, or images and get structured results in JSON, Markdown, or HTML. Supports AI-grounded answers, content scraping, domain filtering, and time-based filtering.

The Search endpoint queries the web and returns ad-free results. It supports web, news, and image search with AI-grounded answers that synthesize results into a single cited response.

**Endpoint:** `POST https://api.geekflare.com/search`

<Info>
  Install the official SDK: `npm install @geekflare/api-node` or `pip install
      geekflare-api`
</Info>

***

## Basic Web Search

Search the web and get structured JSON results. Costs **2 credits**.

<CodeGroup>
  ```typescript Node.js SDK theme={null}
  import { GeekflareClient } from '@geekflare/api-node';

  const client = new GeekflareClient({ apiKey: 'YOUR_API_KEY' });
  const result = await client.search({ query: 'Nvidia stock performance' });
  console.log(result);

  ```

  ```python Python SDK theme={null}
  from geekflare_api.client import GeekflareClient
  from geekflare_api.models import SearchRequestDto

  with GeekflareClient(api_key='YOUR_API_KEY') as client:
      result = client.search(SearchRequestDto(query='best running shoes'))
      print(result)
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.geekflare.com/search \
    -H "x-api-key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"query": "best running shoes"}'
  ```
</CodeGroup>

<Accordion title="Response">
  ```json theme={null}
  {
    "timestamp": 1778737930991,
    "apiStatus": "success",
    "apiCode": 200,
    "meta": {
      "query": "best running shoes",
      "count": 10,
      "source": ["web"],
      "location": "us",
      "time": "any",
      "scrape": false,
      "scrapeLimit": 3,
      "test": { "id": "abc123" }
    },
    "data": [
      {
        "title": "Best Running Shoes of 2026 — Tested & Reviewed",
        "url": "https://example.com/best-running-shoes",
        "snippet": "We tested over 100 pairs to find the best running shoes for every type of runner...",
        "date": "Jan 15, 2025",
        "position": 1
      },
      {
        "title": "Top 10 Running Shoes for 2026",
        "url": "https://example2.com/running-shoes",
        "snippet": "From track to trail, here are the top running shoes this year...",
        "position": 2
      }
    ]
  }
  ```
</Accordion>

***

## News Search

Search recent news articles on any topic.

<CodeGroup>
  ```typescript Node.js SDK theme={null}
  const result = await client.search({
    query: 'AI news',
    source: 'news',
    limit: 5
  });
  ```

  ```python Python SDK theme={null}
  result = client.search(SearchRequestDto(query='AI news', source='news', limit=5))
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.geekflare.com/search \
    -H "x-api-key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"query": "AI news", "source": "news", "limit": 5}'
  ```
</CodeGroup>

<Accordion title="Response">
  ```json theme={null}
  {
    "timestamp": 1778737930991,
    "apiStatus": "success",
    "apiCode": 200,
    "meta": {
      "query": "AI news",
      "count": 5,
      "source": ["news"],
      "time": "any",
      "test": { "id": "abc123" }
    },
    "data": [
      {
        "title": "OpenAI releases new model with improved reasoning",
        "url": "https://techcrunch.com/2025/01/openai-new-model",
        "snippet": "OpenAI today announced a new model that significantly improves on reasoning tasks...",
        "date": "2 hours ago",
        "position": 1
      }
    ]
  }
  ```
</Accordion>

***

## Image Search

Search for images on any topic.

<CodeGroup>
  ```typescript Node.js SDK theme={null}
  const result = await client.search({
    query: 'golden gate bridge',
    source: 'images',
    limit: 5
  });
  ```

  ```python Python SDK theme={null}
  result = client.search(SearchRequestDto(query='golden gate bridge', source='images', limit=5))
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.geekflare.com/search \
    -H "x-api-key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"query": "golden gate bridge", "source": "images", "limit": 5}'
  ```
</CodeGroup>

<Accordion title="Response">
  ```json theme={null}
  {
    "timestamp": 1778737930991,
    "apiStatus": "success",
    "apiCode": 200,
    "meta": {
      "query": "golden gate bridge",
      "count": 5,
      "source": ["images"],
      "test": { "id": "abc123" }
    },
    "data": [
      {
        "title": "Golden Gate Bridge at Sunset",
        "imageUrl": "https://example.com/images/golden-gate.jpg",
        "sourceUrl": "https://example.com/golden-gate-bridge",
        "width": 1920,
        "height": 1080
      }
    ]
  }
  ```
</Accordion>

***

## Grounded Answer

Get an AI-synthesized answer with inline citations from search results. Ideal for RAG pipelines and AI agents. Costs **5 credits**.

<CodeGroup>
  ```typescript Node.js SDK theme={null}
  const result = await client.search({
    query: 'what is the Model Context Protocol',
    groundedAnswer: true
  });
  ```

  ```python Python SDK theme={null}
  result = client.search(SearchRequestDto(
      query='what is the Model Context Protocol',
      grounded_answer=True
  ))
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.geekflare.com/search \
    -H "x-api-key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"query": "what is the Model Context Protocol", "groundedAnswer": true}'
  ```
</CodeGroup>

<Accordion title="Response">
  ```json theme={null}
  {
    "timestamp": 1778737930991,
    "apiStatus": "success",
    "apiCode": 200,
    "meta": {
      "query": "what is the Model Context Protocol",
      "count": 10,
      "source": ["web"],
      "test": { "id": "abc123" }
    },
    "data": {
      "answer": "The Model Context Protocol (MCP) is an open standard developed by Anthropic that allows AI assistants to connect with external data sources and tools [1]. It provides a universal interface for LLMs to interact with APIs, databases, and local services [2].",
      "sources": [
        { "title": "MCP Documentation", "url": "https://modelcontextprotocol.io", "position": 1 },
        { "title": "Anthropic Blog", "url": "https://www.anthropic.com/news/model-context-protocol", "position": 2 }
      ]
    }
  }
  ```
</Accordion>

***

## Search with Content Scraping

Scrape the top result pages and return their full content alongside search results. Costs **4 credits**.

<CodeGroup>
  ```typescript Node.js SDK theme={null}
  const result = await client.search({
    query: 'NestJS authentication guide',
    scrape: true,
    scrapeLimit: 3
  });
  ```

  ```python Python SDK theme={null}
  result = client.search(SearchRequestDto(
      query='NestJS authentication guide',
      scrape=True,
      scrape_limit=3
  ))
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.geekflare.com/search \
    -H "x-api-key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"query": "NestJS authentication guide", "scrape": true, "scrapeLimit": 3}'
  ```
</CodeGroup>

<Accordion title="Response">
  ```json theme={null}
  {
    "timestamp": 1778737930991,
    "apiStatus": "success",
    "apiCode": 200,
    "meta": {
      "query": "NestJS authentication guide",
      "count": 10,
      "scrape": true,
      "scrapeLimit": 3,
      "test": { "id": "abc123" }
    },
    "data": [
      {
        "title": "NestJS Authentication with JWT",
        "url": "https://docs.nestjs.com/security/authentication",
        "snippet": "Authentication is an essential part of most applications...",
        "position": 1,
        "content": "# Authentication\n\nAuthentication is an essential part of most applications..."
      }
    ]
  }
  ```
</Accordion>

***

## Markdown Output

Return results as clean Markdown instead of JSON. Ideal for feeding directly into LLMs.

<CodeGroup>
  ```typescript Node.js SDK theme={null}
  const result = await client.search({
    query: 'TypeScript tips 2025',
    format: 'markdown'
  });
  ```

  ```python Python SDK theme={null}
  result = client.search(SearchRequestDto(query='TypeScript tips 2025', format='markdown'))
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.geekflare.com/search \
    -H "x-api-key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"query": "TypeScript tips 2025", "format": "markdown"}'
  ```
</CodeGroup>

<Accordion title="Response">
  ```json theme={null}
  {
    "timestamp": 1778737930991,
    "apiStatus": "success",
    "apiCode": 200,
    "meta": {
      "query": "TypeScript tips 2025",
      "count": 10,
      "test": { "id": "abc123" }
    },
    "data": "1. [TypeScript 5.4 New Features](https://example.com)\n   - Use `satisfies` for safer type assertions...\n\n2. [TypeScript Tips for Large Codebases](https://example2.com)\n   - Prefer interface over type for objects..."
  }
  ```
</Accordion>

***

## Time Filtering

Limit results to a specific time range.

| Value      | Description                     |
| ---------- | ------------------------------- |
| `any`      | No time filter (default)        |
| `h`        | Past hour                       |
| `d`        | Past day                        |
| `w`        | Past week                       |
| `m`        | Past month                      |
| `y`        | Past year                       |
| `h2`, `d7` | Past 2 hours, past 7 days, etc. |

<CodeGroup>
  ```typescript Node.js SDK theme={null}
  const result = await client.search({
    query: 'AI news',
    source: 'news',
    time: 'd'
  });
  ```

  ```python Python SDK theme={null}
  result = client.search(SearchRequestDto(query='AI news', source='news', time='d'))
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.geekflare.com/search \
    -H "x-api-key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"query": "AI news", "source": "news", "time": "d"}'
  ```
</CodeGroup>

***

## Domain Filtering

Include or exclude specific domains from results.

<CodeGroup>
  ```typescript Node.js SDK theme={null}
  const result = await client.search({
    query: 'React hooks tutorial',
    includeDomains: ['reddit.com', 'stackoverflow.com'],
    excludeDomains: ['pinterest.com']
  });
  ```

  ```python Python SDK theme={null}
  result = client.search(SearchRequestDto(
      query='React hooks tutorial',
      include_domains=['reddit.com', 'stackoverflow.com'],
      exclude_domains=['pinterest.com']
  ))
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.geekflare.com/search \
    -H "x-api-key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "query": "React hooks tutorial",
      "includeDomains": ["reddit.com", "stackoverflow.com"],
      "excludeDomains": ["pinterest.com"]
    }'
  ```
</CodeGroup>

***

## Category Search

Search within a specific category for more relevant results.

| Category   | Description                         |
| ---------- | ----------------------------------- |
| `general`  | General web search (default)        |
| `code`     | Code snippets and technical content |
| `pdf`      | PDF documents                       |
| `research` | Academic and research papers        |
| `linkedin` | LinkedIn profiles and posts         |
| `wiki`     | Wikipedia content                   |

<CodeGroup>
  ```typescript Node.js SDK theme={null}
  const result = await client.search({
    query: 'binary search tree implementation',
    category: 'code'
  });
  ```

  ```python Python SDK theme={null}
  result = client.search(SearchRequestDto(
      query='binary search tree implementation',
      category='code'
  ))
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.geekflare.com/search \
    -H "x-api-key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"query": "binary search tree implementation", "category": "code"}'
  ```
</CodeGroup>

***

## All Parameters

| Parameter        | Type                           | Default   | Description                                                         |
| ---------------- | ------------------------------ | --------- | ------------------------------------------------------------------- |
| `query`          | string                         | required  | Search query (max 2048 chars)                                       |
| `limit`          | number                         | `10`      | Number of results (1–100)                                           |
| `source`         | `web` \| `news` \| `images`    | `web`     | Search source                                                       |
| `format`         | `json` \| `markdown` \| `html` | `json`    | Output format                                                       |
| `time`           | string                         | `any`     | Time filter (`h`, `d`, `w`, `m`, `y`, `h2`, `d7`, etc.)             |
| `location`       | string                         | `us`      | Country code (ISO alpha-2)                                          |
| `category`       | string                         | `general` | Category (`general`, `code`, `pdf`, `research`, `linkedin`, `wiki`) |
| `includeDomains` | array                          | —         | Only return results from these domains                              |
| `excludeDomains` | array                          | —         | Exclude results from these domains                                  |
| `groundedAnswer` | boolean                        | `false`   | Return AI-synthesized answer with citations                         |
| `scrape`         | boolean                        | `false`   | Scrape content from top result URLs                                 |
| `scrapeLimit`    | number                         | `3`       | Number of URLs to scrape (1–10, requires `scrape: true`)            |

## Credits

| Mode                                     | Credits |
| ---------------------------------------- | ------- |
| Standard search                          | 2       |
| Search with scraping (`scrape: true`)    | 4       |
| Grounded answer (`groundedAnswer: true`) | 5       |

<CardGroup cols={2}>
  <Card title="Node.js SDK" icon="npm" href="https://www.npmjs.com/package/@geekflare/api-node">
    `npm install @geekflare/api-node`
  </Card>

  <Card title="Python SDK" icon="python" href="https://pypi.org/project/geekflare-api/">
    `pip install geekflare-api`
  </Card>
</CardGroup>