> ## 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.

# Python

> Use Geekflare in any Python project with the official SDK or the requests library.

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](https://dash.geekflare.com)

## Installation

> [tab] pip
>
> ```bash theme={null}
> pip install geekflare-api
> ```

> [tab] uv
>
> ```bash theme={null}
> uv add geekflare-api
> ```

> [tab] pip + requests (no SDK)
>
> ```bash theme={null}
> pip install requests python-dotenv
> ```

## Set your API key

Create a `.env` file:

```bash .env theme={null}
GEEKFLARE_API_KEY=your_api_key_here
```

Load it in your script:

```python theme={null}
from dotenv import load_dotenv
import os

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

> [!WARNING]
>
> Never hardcode your API key. Add `.env` to `.gitignore`.

## Initialize the client

```python theme={null}
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:

```python theme={null}
with GeekflareClient(api_key=os.environ["GEEKFLARE_API_KEY"]) as client:
    # make calls here
    pass
```

***

## Web Scraping

> [tab] SDK
>
> ```python theme={null}
> 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="markdown",
>             device="desktop",
>         )
>     )
>     print(result)
> ```

> [tab] requests
>
> ```python theme={null}
> 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": "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:**

```json theme={null}
{
  "timestamp": 1779703261268,
  "apiStatus": "success",
  "apiCode": 200,
  "meta": {
    "url": "https://toscrape.com/",
    "device": "desktop",
    "format": ["markdown"],
    "blockAds": true,
    "renderJS": true,
    "test": { "id": "mxqx9v9y0742lap6altwdteqd28t23nq" }
  },
  "data": "# To Scrape\n\nA sandbox for practicing web scraping..."
}
```

The `data` field is a URL to the scraped output file. See the [Web Scraping endpoint reference](https://docs.geekflare.com/api/endpoint/webscraping.md).

***

## Search

> [tab] SDK
>
> ```python theme={null}
> 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)
> ```

> [tab] requests
>
> ```python theme={null}
> 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

> [tab] SDK
>
> ```python theme={null}
> 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)
> ```

> [tab] requests
>
> ```python theme={null}
> 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

> [tab] SDK
>
> ```python theme={null}
> 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}")
> ```

> [tab] requests
>
> ```python theme={null}
> 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 |

> [!TIP]
>
> See [Rate Limit Exceeded](https://docs.geekflare.com/rate-limit-exceeded.md) and [Credit
> Exhausted](https://docs.geekflare.com/credit-exhausted.md) for strategies to handle these gracefully.

***

## Next steps

* [Django quickstart](https://docs.geekflare.com/quickstart/django.md) — Views, services, and `python-decouple`
* [API Reference](https://docs.geekflare.com/endpoint/reference.md) — Full endpoint documentation
* [SDK on PyPI](https://pypi.org/project/geekflare-api/)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.