Search Guide

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. Set serp: true to get the full Google search results page instead, with optional city-level targeting. Endpoint: POST https://api.geekflare.com/search

Install the official SDK: npm install @geekflare/api-node or pip install geekflare-api

Basic Web Search

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

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);

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)

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"}'

Response

{
  "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
    }
  ]
}

News Search

Search recent news articles on any topic.

const result = await client.search({
  query: 'AI news',
  source: 'news',
  limit: 5
});

result = client.search(SearchRequestDto(query='AI news', source='news', limit=5))

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}'

Response

{
  "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
    }
  ]
}

Image Search

Search for images on any topic.

const result = await client.search({
  query: 'golden gate bridge',
  source: 'images',
  limit: 5
});

result = client.search(SearchRequestDto(query='golden gate bridge', source='images', limit=5))

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}'

Response

{
  "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
    }
  ]
}

Grounded Answer

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

const result = await client.search({
  query: 'what is the Model Context Protocol',
  groundedAnswer: true
});

result = client.search(SearchRequestDto(
    query='what is the Model Context Protocol',
    grounded_answer=True
))

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}'

Response

{
  "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 }
    ]
  }
}

Search with Content Scraping

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

const result = await client.search({
  query: 'NestJS authentication guide',
  scrape: true,
  scrapeLimit: 3
});

result = client.search(SearchRequestDto(
    query='NestJS authentication guide',
    scrape=True,
    scrape_limit=3
))

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}'

Response

{
  "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..."
    }
  ]
}

Markdown Output

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

const result = await client.search({
  query: 'TypeScript tips 2025',
  format: 'markdown'
});

result = client.search(SearchRequestDto(query='TypeScript tips 2025', format='markdown'))

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"}'

Response

{
  "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..."
}

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.

const result = await client.search({
  query: 'AI news',
  source: 'news',
  time: 'd'
});

result = client.search(SearchRequestDto(query='AI news', source='news', time='d'))

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"}'

Domain Filtering

Include or exclude specific domains from results.

const result = await client.search({
  query: 'React hooks tutorial',
  includeDomains: ['reddit.com', 'stackoverflow.com'],
  excludeDomains: ['pinterest.com']
});

result = client.search(SearchRequestDto(
    query='React hooks tutorial',
    include_domains=['reddit.com', 'stackoverflow.com'],
    exclude_domains=['pinterest.com']
))

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"]
  }'

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

const result = await client.search({
  query: 'binary search tree implementation',
  category: 'code'
});

result = client.search(SearchRequestDto(
    query='binary search tree implementation',
    category='code'
))

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"}'

Device

Set device to mobile to get results as they appear on a mobile device. Defaults to desktop. Works in standard search and in SERP mode.

const result = await client.search({
  query: 'best running shoes',
  device: 'mobile'
});

result = client.search(SearchRequestDto(query='best running shoes', device='mobile'))

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", "device": "mobile"}'

SERP Results

Set serp: true to get the full Google search results page for a query including organic results, AI Overviews, related searches, People Also Ask, navigation tabs, and pagination. Returns everything on the first page of results.

const result = await client.search({
  query: 'ats for agencies',
  serp: true
});

result = client.search(SearchRequestDto(query='ats for agencies', serp=True))

curl -X POST https://api.geekflare.com/search \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "ats for agencies", "serp": true}'

Response

{
  "timestamp": 1790698941310,
  "apiStatus": "success",
  "apiCode": 200,
  "meta": {
    "query": "ats for agencies",
    "limit": 10,
    "count": 10,
    "source": ["web"],
    "format": "json",
    "location": "us",
    "time": "any",
    "category": "general",
    "scrape": false,
    "scrapeLimit": 3,
    "test": {
      "id": "9f455f1a-5df8-4658-97fd-1a286789dc67"
    }
  },
  "data": {
    "general": {
      "search_engine": "google",
      "query": "ats for agencies",
      "detected_query": "ats for agencies",
      "results_cnt": 128,
      "search_time": 0.24,
      "language": "en",
      "country_code": "US",
      "location": "United States",
      "gl": "US",
      "mobile": false,
      "basic_view": false,
      "search_type": "text",
      "page_title": "ats for agencies - Google Search",
      "timestamp": "2026-09-29T16:22:20.881Z"
    },
    "input": {
      "original_url": "https://www.google.com/search?q=ats%20for%20agencies&gl=us",
      "request_id": "hl_309dd1bd_fawunsu8b5k"
    },
    "navigation": [
      {
        "title": "Images",
        "href": "https://www.google.com/search?q=ats+for+agencies&udm=2"
      },
      {
        "title": "News",
        "href": "https://www.google.com/search?q=ats+for+agencies&tbm=nws"
      },
      {
        "title": "Videos",
        "href": "https://www.google.com/search?q=ats+for+agencies&udm=vids"
      }
    ],
    "organic": [
      {
        "link": "https://recruiterflow.com/",
        "source": "Recruiterflow",
        "display_link": "https://recruiterflow.com",
        "title": "Recruiterflow - Best AI-Native ATS & CRM for Executive ...",
        "description": "Recruiterflow is the best AI-Native ATS & CRM software for executive search firms, recruiting agencies and staffing agencies. It comes equipped with ATS, ...",
        "snippet_highlighted_words": [
          "Recruiterflow is the best AI-Native ATS & CRM software"
        ],
        "icon": "data:image/webp;base64,...",
        "rank": 1,
        "global_rank": 1
      },
      {
        "link": "https://recruiteze.com/ats-for-staffing-agencies/",
        "source": "Recruiteze",
        "display_link": "https://recruiteze.com › ats-for-staffing-agencies",
        "title": "9 Best ATS For Staffing Agencies [New Picks]",
        "description": "Hiring through ATS or recruiting software helps staffing agencies provide the best-fit, talented and qualified candidates to the client company.",
        "snippet_highlighted_words": [
          "Hiring through ATS or recruiting software"
        ],
        "icon": "data:image/webp;base64,...",
        "rank": 3,
        "global_rank": 7
      },
      {
        "link": "https://smartsearchinc.com/ats-for-your-recruiting-agency-essential-guide/",
        "source": "SmartSearch Inc.",
        "display_link": "https://smartsearchinc.com › ats-for-your-recruiting-age...",
        "title": "Choosing the Right ATS for Your Recruiting Agency",
        "description": "Discover how to choose an innovative ATS for your recruiting agency's success. Learn key features, benefits, and tips to boost your staffing ...",
        "snippet_highlighted_words": [
          "ATS"
        ],
        "extensions": [
          {
            "inline": true,
            "type": "text",
            "text": "Jul 15, 2025",
            "rank": 1
          }
        ],
        "icon": "data:image/webp;base64,...",
        "rank": 5,
        "global_rank": 9
      }
    ],
    "pagination": {
      "pages": [
        {
          "page": 2,
          "start": 10,
          "link": "https://www.google.com/search?q=ats+for+agencies&start=10"
        },
        {
          "page": 3,
          "start": 20,
          "link": "https://www.google.com/search?q=ats+for+agencies&start=20"
        }
      ],
      "current_page": 1,
      "next_page": 2,
      "next_page_start": 10,
      "next_page_link": "https://www.google.com/search?q=ats+for+agencies&start=10"
    },
    "related": [
      {
        "text": "Ats for agencies reddit",
        "link": "https://www.google.com/search?q=Ats+for+agencies+reddit",
        "rank": 1,
        "global_rank": 14
      },
      {
        "text": "Recruiterflow",
        "link": "https://www.google.com/search?q=Recruiterflow",
        "rank": 2,
        "global_rank": 15
      }
    ],
    "people_also_ask": [
      {
        "question": "What is the best ATS for recruiting agencies?",
        "question_type": "ai_overview",
        "rank": 1,
        "global_rank": 3
      },
      {
        "question": "What is an ATS vs CRM?",
        "question_link": "https://www.google.com/search?q=What+is+an+ATS+vs+CRM%3F",
        "question_type": "ai_overview",
        "rank": 3,
        "global_rank": 5
      }
    ]
  }
}

AI Overviews

When Google shows an AI Overview for the query, it’s returned in data.ai_overview alongside the other SERP sections, with the overview as plain text (text), as the HTML Google rendered (html), and the sources it cites (references).

Response — ai_overview field

{
  "ai_overview": {
    "text": "The best laptops under $1,000 include the Apple MacBook Neo for everyday macOS use and the HP OmniBook 5 for top-tier Windows performance. Top Recommendations $799.00 Apple& more Offers an all-aluminum build, an A18 Pro chip, and long battery life. It serves as an ideal budget choice for students and general tasks. $862.49 HP& more Noted as one of the best overall Windows AI laptops. It features exceptional battery endurance and a dedicated neural processing unit (NPU). Where to Shop You can purchase or configure Apple models directly at the Apple Store. You can browse a wide inventory of Windows and gaming machines through Best Buy Laptops.",
    "html": "<div data-subtree=\"aimc\" ...>...</div>",
    "references": [
      {
        "title": "The Best Laptops Under $1,000 We've Tested for 2026 | PCMag",
        "url": "https://www.pcmag.com/picks/best-laptops-under-1000",
        "source": "PCMag",
        "snippet": "Tested Laptops Under $1,000: HP OmniBook 5 14 (best overall Windows, 34-hour battery); Apple MacBook Neo (best budget Mac, aluminum build); MSI Katana 15 HX (RTX 5..."
      },
      {
        "title": "laptops under $1000 - Best Buy",
        "url": "https://www.bestbuy.com/site/searchpage.jsp?id=pcat17071&st=laptops%20under%20%241000",
        "source": "Best Buy",
        "snippet": "Laptops under $1000: Dell 15.6\" 2K (i5, 8GB, 512GB, $649.99), HP Victus 15.6\" Gaming (Ryzen 7, 16GB, RTX 4050, $949.99), HP OmniBo..."
      },
      {
        "title": "What is the best laptop under $ 1000 US? - Reddit",
        "url": null,
        "source": "[www.reddit.com](https://www.reddit.com)",
        "snippet": "Specific Laptop Recommendations: Recommended laptops for graphically intensive medical imaging and 3D rendering under $1000 includ..."
      }
    ]
  }
}

ai_overview is only present when Google returns one for the query. A reference’s url can be null when Google doesn’t expose one. The html value is shortened here.

Which sections appear (People Also Ask, related searches, and so on) depends on what Google returns for the query. The example above is shortened.

In SERP mode these parameters apply: query, location, city, device, limit, source (one value only), time, includeDomains, and excludeDomains. format, category, scrape, scrapeLimit, and groundedAnswer are ignored. The meta object still echoes them back.

SERP filters

Narrow a SERP request with source, time, includeDomains, excludeDomains, and limit.

const result = await client.search({
  query: 'best running shoes',
  serp: true,
  source: 'news',
  time: 'w',
  excludeDomains: ['pinterest.com'],
  limit: 5
});

result = client.search(SearchRequestDto(
    query='best running shoes',
    serp=True,
    source='news',
    time='w',
    exclude_domains=['pinterest.com'],
    limit=5
))

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",
    "serp": true,
    "source": "news",
    "time": "w",
    "excludeDomains": ["pinterest.com"],
    "limit": 5
  }'

source: web (default), news, or images. SERP mode accepts one source per request. With news or images, results appear under the news or images key of data instead of organic.
time: same values as Time Filtering.
includeDomains / excludeDomains: applied as part of the search itself, so a filtered page still fills up with matching results. Pass bare domains such as reddit.com. Entries that are not valid domains are ignored.
limit: trims the results list to the first N entries. A SERP request returns a single Google page of about 10 results, so values above 10 return no additional results.
meta.count: the number of results in the returned list, after limit is applied.

City Targeting

Pass city to get results localized to a specific city, for example to check how a query ranks in London versus Manchester. It works in SERP mode and in standard search. Use city on its own or together with location (country code). When city is set, it takes priority over location for where the search appears to originate.

const result = await client.search({
  query: 'best running shoes',
  serp: true,
  city: 'London,England,United Kingdom'
});

result = client.search(SearchRequestDto(
    query='best running shoes',
    serp=True,
    city='London,England,United Kingdom'
))

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", "serp": true, "city": "London,England,United Kingdom"}'

For localized structured results, leave out serp:

const result = await client.search({
  query: 'best running shoes',
  city: 'London,England,United Kingdom'
});

result = client.search(SearchRequestDto(
    query='best running shoes',
    city='London,England,United Kingdom'
))

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", "city": "London,England,United Kingdom"}'

Use the city name exactly as it appears in the list of supported cities (JSON), for example London,England,United Kingdom.

All Parameters

Parameter	Type	Default	Description
`query`	string	required	Search query (max 2048 chars)
`limit`	number	`10`	Number of results (1–100). In SERP mode it trims the first page, which holds about 10 results
`source`	`web` \| `news` \| `images`	`web`	Search source. SERP mode accepts one source per request
`format`	`json` \| `markdown` \| `html`	`json`	Output format. Ignored in SERP mode
`time`	string	`any`	Time filter (`h`, `d`, `w`, `m`, `y`, `h2`, `d7`, etc.)
`location`	string	`us`	Country code (ISO alpha-2)
`device`	`desktop` \| `mobile`	`desktop`	Device to emulate. Works in standard and SERP modes
`category`	string	`general`	Category (`general`, `code`, `pdf`, `research`, `linkedin`, `wiki`). Ignored in SERP mode
`includeDomains`	array	—	Only return results from these domains
`excludeDomains`	array	—	Exclude results from these domains
`groundedAnswer`	boolean	`false`	Return AI-synthesized answer with citations. Ignored in SERP mode
`scrape`	boolean	`false`	Scrape content from top result URLs. Ignored in SERP mode
`scrapeLimit`	number	`3`	Number of URLs to scrape (1–10, requires `scrape: true`). Ignored in SERP mode
`serp`	boolean	`false`	Return the full Google SERP. Applies `query`, `location`, `city`, `device`, `limit`, `source`, `time`, `includeDomains`, and `excludeDomains`
`city`	string	—	City to target, e.g. `London,England,United Kingdom`. Works in SERP mode and standard search

Credits

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

Node.js SDK

npm install @geekflare/api-node

Python SDK

pip install geekflare-api

Getting started

Quickstarts

Guides

MCP Server

Capabilities

Best Practices

Troubleshooting

Changelog

About

Basic Web Search

News Search

Image Search

Grounded Answer

Search with Content Scraping

Markdown Output

Time Filtering

Domain Filtering

Category Search

Device

SERP Results

AI Overviews

SERP filters

City Targeting

All Parameters

Credits

Node.js SDK

Python SDK

​Basic Web Search

​News Search

​Image Search

​Grounded Answer

​Search with Content Scraping

​Markdown Output

​Time Filtering

​Domain Filtering

​Category Search

​Device

​SERP Results

​AI Overviews

​SERP filters

​City Targeting

​All Parameters

​Credits

Node.js SDK

Python SDK

Basic Web Search

News Search

Image Search

Grounded Answer

Search with Content Scraping

Markdown Output

Time Filtering

Domain Filtering

Category Search

Device

SERP Results

AI Overviews

SERP filters

City Targeting

All Parameters

Credits