Python Integration

Raw markdown source view for LLM workflows.

---
title: Python Integration
description: A practical Python requests client for live fetch workflows.
---

## Minimal client

```python
import os
import requests

BASE_URL = os.environ.get("GQ_API_BASE_URL", "https://api.gamequery.dev")
API_VERSION = os.environ.get("GQ_API_VERSION", "v1")

def headers():
    return {
        "Content-Type": "application/json",
        "X-API-Token": os.environ["GQ_API_TOKEN"],
        "X-API-Token-Type": os.environ.get("GQ_API_TOKEN_TYPE", "FREE"),
        "X-API-Token-Email": os.environ["GQ_API_TOKEN_EMAIL"],
    }

def get_games_catalog():
    response = requests.get(
        f"{BASE_URL}/{API_VERSION}/get/games",
        timeout=20,
    )
    response.raise_for_status()
    return response.json()

def fetch_servers(grouped_servers):
    response = requests.post(
        f"{BASE_URL}/{API_VERSION}/post/fetch",
        json={"servers": grouped_servers},
        headers=headers(),
        timeout=20,
    )
    response.raise_for_status()
    return response.json()
```

## Basic usage

```python
payload = [
    {
        "game_id": "minecraft",
        "servers": ["203.0.113.10:25565"],
    }
]

print(get_games_catalog())
print(fetch_servers(payload))
```

## Suggested production hardening

- Use a `requests.Session` for connection reuse.
- Track `429` responses and back off automatically.
- Persist `_meta.invalid_servers` for data quality reports.
- Keep `API_VERSION` configurable so migration to `v2` is an environment update.