Python

The official geekflare-api SDK provides a Pythonic interface that handles auth and serialization. Raw requests examples are included for those who prefer no extra dependencies.

Prerequisites

Python 3.8+
pip or uv
A Geekflare API key — get one free

Installation

pip
uv
pip + requests (no SDK)

pip install geekflare-api

uv add geekflare-api

pip install requests python-dotenv

Set your API key

Create a .env file:

.env

GEEKFLARE_API_KEY=your_api_key_here

Load it in your script:

from dotenv import load_dotenv
import os

load_dotenv()
API_KEY = os.environ["GEEKFLARE_API_KEY"]

Never hardcode your API key. Add .env to .gitignore.

Initialize the client

from geekflare_api.client import GeekflareClient

client = GeekflareClient(api_key=os.environ["GEEKFLARE_API_KEY"])

The client is a context manager — use with to ensure the underlying HTTP session is closed:

with GeekflareClient(api_key=os.environ["GEEKFLARE_API_KEY"]) as client:
    # make calls here
    pass

Web Scraping

SDK
requests

import os
from dotenv import load_dotenv
from geekflare_api.client import GeekflareClient
from geekflare_api.models import WebScrapeDto

load_dotenv()

with GeekflareClient(api_key=os.environ["GEEKFLARE_API_KEY"]) as client:
    result = client.web_scrape(
        WebScrapeDto(
            url="https://toscrape.com/",
            renderJS=True,
            blockAds=True,
            format="html,markdown",
            device="desktop",
        )
    )
    print(result)

import os
import requests
from dotenv import load_dotenv

load_dotenv()

response = requests.post(
    "https://api.geekflare.com/webscraping",
    headers={
        "Content-Type": "application/json",
        "x-api-key": os.environ["GEEKFLARE_API_KEY"],
    },
    json={
        "url": "https://toscrape.com/",
        "renderJS": True,
        "blockAds": True,
        "format": "html,markdown",
        "device": "desktop",
    },
)

response.raise_for_status()
print(response.json())

Key parameters:

Parameter	Type	Description
`url`	`str`	Required. The URL to scrape
`renderJS`	`bool`	Wait for JavaScript to execute
`blockAds`	`bool`	Block ads before scraping
`format`	`str`	Comma-separated: `html`, `markdown`
`device`	`str`	`"desktop"` or `"mobile"`
`proxyCountry`	`str`	Route via country code, e.g. `"us"`
`stealth`	`bool`	Enable stealth mode
`waitTime`	`float`	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,
    "test": { "id": "mxqx9v9y0742lap6altwdteqd28t23nq" }
  },
  "data": "https://example.com/9bulgk075ed9m3vhua5vcrp0.html"
}

The data field is a URL to the scraped output file. See the Web Scraping endpoint reference.

Search

SDK
requests

import os
from dotenv import load_dotenv
from geekflare_api.client import GeekflareClient
from geekflare_api.models import SearchDto

load_dotenv()

with GeekflareClient(api_key=os.environ["GEEKFLARE_API_KEY"]) as client:
    result = client.search(
        SearchDto(
            query="best Python web frameworks",
            limit=10,
            location="us",
            source="web",
            time="m",
            format="json",
        )
    )
    print(result)

import os
import requests
from dotenv import load_dotenv

load_dotenv()

response = requests.post(
    "https://api.geekflare.com/search",
    headers={
        "Content-Type": "application/json",
        "x-api-key": os.environ["GEEKFLARE_API_KEY"],
    },
    json={
        "query": "best Python web frameworks",
        "limit": 10,
        "location": "us",
        "source": "web",
        "time": "m",
        "format": "json",
    },
)

response.raise_for_status()
data = response.json()

for item in data.get("data", []):
    print(f"{item['title']} — {item['url']}")
    print(item['snippet'])

Key parameters:

Parameter	Type	Description
`query`	`str`	Required. The search query
`limit`	`int`	Number of results (default: `10`)
`location`	`str`	Country code for localized results, e.g. `"us"`
`source`	`str`	`"web"`, `"news"`, etc.
`time`	`str`	Recency filter: `"d"` (day), `"w"` (week), `"m"` (month)
`includeDomains`	`list[str]`	Only return results from these domains
`excludeDomains`	`list[str]`	Exclude results from these domains

Screenshot

SDK
requests

import os
from dotenv import load_dotenv
from geekflare_api.client import GeekflareClient
from geekflare_api.models import ScreenshotDto

load_dotenv()

with GeekflareClient(api_key=os.environ["GEEKFLARE_API_KEY"]) as client:
    result = client.screenshot(
        ScreenshotDto(
            url="https://example.com",
            type="png",
            fullPage=True,
            device="desktop",
            viewportWidth=1280,
            viewportHeight=800,
            blockAds=True,
            hideCookie=True,
            quality=90,
        )
    )
    print(result)

import os
import requests
from dotenv import load_dotenv

load_dotenv()

response = requests.post(
    "https://api.geekflare.com/screenshot",
    headers={
        "Content-Type": "application/json",
        "x-api-key": os.environ["GEEKFLARE_API_KEY"],
    },
    json={
        "url": "https://example.com",
        "type": "png",
        "fullPage": True,
        "device": "desktop",
        "viewportWidth": 1280,
        "viewportHeight": 800,
        "blockAds": True,
        "hideCookie": True,
        "quality": 90,
    },
)

response.raise_for_status()
data = response.json()
# data['data'] is the screenshot URL directly
print("Screenshot URL:", data["data"])

Error handling

SDK
requests

import os
from dotenv import load_dotenv
from geekflare_api.client import GeekflareClient
from geekflare_api.models import WebScrapeDto
from geekflare_api.exceptions import ApiException

load_dotenv()

try:
    with GeekflareClient(api_key=os.environ["GEEKFLARE_API_KEY"]) as client:
        result = client.web_scrape(WebScrapeDto(url="https://toscrape.com/"))
        print(result)

except ApiException as e:
    print(f"API error {e.status}: {e.reason}")

    if e.status == 401:
        print("Invalid or missing API key.")
    elif e.status == 402:
        print("API credits exhausted. Top up at dash.geekflare.com.")
    elif e.status == 403:
        print("This endpoint is not available on your current plan.")
    elif e.status == 429:
        print("Rate limit exceeded. Back off and retry.")

except Exception as e:
    print(f"Unexpected error: {e}")

import os
import requests
from dotenv import load_dotenv

load_dotenv()

try:
    response = requests.post(
        "https://api.geekflare.com/webscraping",
        headers={
            "Content-Type": "application/json",
            "x-api-key": os.environ["GEEKFLARE_API_KEY"],
        },
        json={"url": "https://toscrape.com/"},
    )
    response.raise_for_status()
    print(response.json())

except requests.HTTPError as e:
    code = e.response.status_code
    body = e.response.json()

    if code == 401:
        print("Invalid or missing API key.")
    elif code == 402:
        print("API credits exhausted.")
    elif code == 403:
        print("Endpoint not available on your plan.")
    elif code == 429:
        print("Rate limit exceeded. Back off and retry.")
    else:
        print(f"HTTP {code}: {body.get('message', 'Unknown error')}")

except requests.ConnectionError:
    print("Network error. Check your internet connection.")

Common error codes

Code	Meaning
`401`	Missing or invalid `x-api-key`
`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

Django quickstart — Views, services, and python-decouple
API Reference — Full endpoint documentation
SDK on PyPI

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