GameQuery Docs
Guides

Python Integration

A practical Python requests client for live fetch workflows.

View as Markdown

Minimal client

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

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.

On this page