Python SDK Reference

The official Python SDK (ffdata-client) is a fully-typed, production-ready client library designed to simplify integrations with FFDATA API routes. It encapsulates low-level protocol exchanges, authorization header generation, connection pooling, and circuit breaking capabilities.

Installation

Install the package via pip from public repositories:

pip install ffdata-clientTerminal

Client Initialization

Initialize the FFClient instance by feeding your secret API credential.

python
from ffclient import FFClient

# Initialize client using your secret API key
# By default, client connects to production gateway at https://ffdata-api.onrender.com
client = FFClient(
    api_key="your_api_key",
    timeout=10,        # request timeout in seconds (default is 10)
    max_retries=3      # automatic retries on gateway failures (default is 3)
)
)

Querying Player Statistics

Call `get_player` to fetch player data. Specify region and detail filters directly:

python
# Fetch player details
player_data = client.get_player(
    uid=1738283841,
    region="ind",             # optional region code, defaults to "ind"
    detail_level="detailed"   # basic, detailed, or full
)

print(player_data["data"]["nickname"])
print(player_data["data"]["level"])])

Querying Clan/Guild Data

Fetch detailed guild hierarchies and rosters using `get_clan`:

python
# Fetch clan details (Guild info)
clan_data = client.get_clan(
    clan_id=3022208474,
    region="ind",
    detail_level="basic"
)

print(clan_data["data"]["clan_name"])
print(clan_data["data"]["member_num"])])

Querying Craftland Authors

Retrieve author profile stats and publishing map listings using `get_workshop_author`:

python
# Fetch Craftland workshop author details
author_data = client.get_workshop_author(
    uid=1738283841,
    detail_level="full"
)

print(author_data["data"]["nickname"])
for map_info in author_data["data"]["publish_maps"]:
    print(f"Map: {map_info['map_name']} - Plays: {map_info['plays']}"))

Exception Handling

The SDK maps status codes to structured exceptions to allow clean client-side exception routing:

python
from ffclient import FFClient
from ffclient.exceptions import (
    AuthError,
    InsufficientCreditsError,
    RateLimitError,
    CircuitBreakerError
)

client = FFClient(api_key="your_api_key")

try:
    player = client.get_player(uid=1738283841)
except AuthError:
    print("Invalid API credentials. Review authorization tokens.")
except InsufficientCreditsError:
    print("Your account balance has run out. Refill credits to resume.")
except RateLimitError as e:
    print(f"Rate limited. Retry allowed after {e.retry_after} seconds.")
except CircuitBreakerError:
    print("Local client circuit breaker opened due to high downstream failure rates."))
FFData LogoFFData API