Python - Geekflare

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)

bash pip install geekflare-api

bash uv add geekflare-api

bash 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

Next steps

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

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