ffdata-client 1.0.0

Professional Python SDK for FFData API

FFData Python SDK

---

Python SDK for accessing Free Fire player data and Craftland information via the professional FFData API.

---

Installation

pip install ffdata-client

---

Quick Start

from ffclient import FFClient

# Initialize client (Default points to https://ffdata-api.onrender.com)
client = FFClient(api_key="your_api_key")

# Fetch player data with specific detail level
# Supported detail_levels: "basic", "detailed", "full"
player = client.get_player(uid=1738283841, detail_level="detailed")

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

# Fetch clan info (Guild)
clan = client.get_clan(clan_id=3022208474, detail_level="basic")

print(player["data"]["nickname"])
print(author["data"])
print(clan["data"]["clan_name"])

# Check cached credit balance
print(f"Remaining balance: {client.credits_left}")

---

Detailed Usage

Player API

Retrieve real-time player statistics and regional data.

player = client.get_player(
    uid=2726416993,
    detail_level="detailed" # options: "basic", "detailed", "full"
)

# Access primary data
print(player["data"])

# Access metadata (Time, Request ID, Version, Credits Left)
print(player["meta"]["time_ms"])
print(player["meta"]["request_id"])
print(player["meta"]["credits_left"])

Workshop (Craftland)

Retrieve creator statistics and map information.

author = client.get_workshop_author(uid=2726416993, detail_level="basic")
print(author["data"]["likes"])

Clan Info (Guild)

Retrieve clan standings, rosters, and levels.

clan = client.get_clan(clan_id=3022208474, detail_level="detailed")
print(clan["data"]["clan_name"])

---

Configuration

Custom configuration for private endpoints or specialized debugging.

client = FFClient(
    api_key="your_api_key",
    base_url="https://ffdata-api.onrender.com",  # optional override
    debug="basic",  # options: "off", "basic", "verbose"
    timeout=15,
    max_retries=3
)

---

Response Format

The SDK returns a unified response structure for all endpoints:

{
  "data": { 
    "uid": 2726416993,
    "nickname": "...",
    ...
  },
  "meta": {
    "time_ms": 120,      // Latency in milliseconds
    "request_id": "...", // Global tracing ID
    "fallback": false,   // True if served from circuit-breaker cache
    "version": "1.0.0",  // SDK Version
    "credits_left": 490, // Account credits left
    "credits_used": 5    // Request cost
  }
}

---

Error Handling

The SDK maps HTTP errors to descriptive Python exceptions.

from ffclient import AuthError, RateLimitError, InsufficientCreditsError

try:
    client.get_player(uid=2726416993)

except AuthError:
    print("Invalid API key or session expired")

except RateLimitError as e:
    print(f"Rate limited. Retry after {e.retry_after}s")

except InsufficientCreditsError:
    print("Your account balance is 0. Please top up.")

except Exception as e:
    print(f"An unexpected error occurred: {e}")

---

Features

• Resilience: Built-in adaptive circuit breakers and jiterred retries.
• Unified Schema: Consistent data + meta structure across all calls.
• Metadata Insight: High-resolution latency tracking (time_ms) and request_id for debugging.
• Performance: Persistent connection pooling and memory-safe LRU caching.
• Detail Levels: Granular control over response payload size.

---

License

MIT