FreeFire API Python

🚀 Powerful Python wrapper for FreeFire API - Get player statistics, profile data, and search accounts with ease!

Features

• 🔥 Simple & Intuitive - Easy-to-use Python interface
• 📊 Complete Data - Player stats, profiles, and search functionality
• 🌍 Multi-Region Support - 12 server regions supported
• 🛡️ Error Handling - Comprehensive exception handling
• 🎯 Type Hints - Full type annotation support
• 🖥️ CLI Tool - Command-line interface included
• 🧪 Well Tested - Unit tests with high coverage

Installation

pip install freefire-api

Or install from source:

git clone https://github.com/seseegy/freefire-api-python
cd freefire-api-python
pip install -e .

Quick Start

Basic Usage

from freefire_api import FreeFireClient

# Initialize client
client = FreeFireClient(server="ID")

# Search for accounts
search_result = client.search_account("rasyah")
print(search_result)

# Get player profile
profile = client.get_player_profile("2947169998")
print(profile)

# Get player stats
stats = client.get_player_stats("2947169998", gamemode="br", matchmode="CAREER")
print(stats)

# Get complete player data (profile + all stats)
complete_data = client.get_complete_player_data("2947169998")
print(complete_data)

Command Line Interface

The package includes a CLI tool for quick access:

# Search for accounts
freefire search "rasyah" --server ID

# Get player profile
freefire profile 2947169998 --pretty

# Get player stats
freefire stats 2947169998 --gamemode br --matchmode RANKED

# Get complete player data
freefire complete 2947169998 --server ID

# Interactive mode
freefire interactive

Interactive Mode

Start the interactive CLI for a user-friendly experience:

freefire interactive

🔥 FreeFire API Interactive CLI
Type 'help' for commands or 'exit' to quit

freefire> search rasyah
freefire> profile 2947169998
freefire> stats 2947169998
freefire> complete 2947169998
freefire> help
freefire> exit

API Reference

FreeFireClient

The main client class for interacting with the FreeFire API.

Constructor

FreeFireClient(default_server: str = "IND")

• default_server: Default server region (IND, SG, RU, ID, TW, US, VN, TH, ME, PK, CIS, BR)

Methods

search_account(keyword: str, server: Optional[str] = None) -> Dict[str, Any]

Search for FreeFire accounts by keyword.

Parameters:

• keyword: Search keyword (minimum 3 characters)
• server: Server region (uses default if not specified)

Returns: Search results dictionary

Raises: InvalidParameterError if keyword is too short

get_player_profile(uid: str, server: Optional[str] = None, need_gallery_info: bool = False, call_sign_src: int = 7) -> Dict[str, Any]

Get player profile data.

Parameters:

• uid: Player UID
• server: Server region (uses default if not specified)
• need_gallery_info: Include gallery information
• call_sign_src: Call sign source type

Returns: Player profile data dictionary

get_player_stats(uid: str, server: Optional[str] = None, gamemode: str = "br", matchmode: str = "CAREER") -> Dict[str, Any]

Get player statistics.

Parameters:

• uid: Player UID
• server: Server region (uses default if not specified)
• gamemode: Game mode ("br" for Battle Royale, "cs" for Clash Squad)
• matchmode: Match mode ("CAREER", "NORMAL", "RANKED")

Returns: Player statistics dictionary

Raises: InvalidParameterError for invalid game mode or match mode

get_complete_player_data(uid: str, server: Optional[str] = None) -> Dict[str, Any]

Get complete player data (profile + stats for both modes).

Parameters:

• uid: Player UID
• server: Server region (uses default if not specified)

Returns: Complete player data dictionary including profile and all stats

Exceptions

The package provides custom exceptions:

• FreeFireAPIError: Base exception for all API errors
• InvalidParameterError: Raised when invalid parameters are provided
• APIResponseError: Raised when API returns an error response
• NetworkError: Raised when network-related errors occur

Server Regions

The API supports 12 server regions:

Code	Region
IND	India
SG	Singapore
RU	Russia
ID	Indonesia
TW	Taiwan
US	United States
VN	Vietnam
TH	Thailand
ME	Middle East
PK	Pakistan
CIS	CIS
BR	Brazil

Examples

Example 1: Basic Player Lookup

from freefire_api import FreeFireClient

client = FreeFireClient()

# Search for player
search_results = client.search_account("rasyah")
player_uid = search_results[0]['accountid']

# Get profile
profile = client.get_player_profile(player_uid)
print(f"Player: {profile['basicinfo']['nickname']}")
print(f"Level: {profile['basicinfo']['level']}")
print(f"Rank: {profile['basicinfo']['rank']}")

Example 2: Complete Player Analysis

from freefire_api import FreeFireClient

client = FreeFireClient(server="ID")

# Get complete player data
data = client.get_complete_player_data("2947169998")

# Profile info
profile = data['profile']
basic_info = profile['basicinfo']
print(f"👤 {basic_info['nickname']} (Level {basic_info['level']})")

# BR Stats
br_stats = data['stats_br']['data']['solostats']
print(f"🎯 BR Stats: {br_stats['wins']} wins, {br_stats['kills']} kills")

# CS Stats
cs_stats = data['stats_cs']['data']['solostats']
if cs_stats.get('gamesplayed'):
    print(f"⚔️ CS Stats: {cs_stats['wins']} wins, {cs_stats['kills']} kills")

Example 3: Error Handling

from freefire_api import FreeFireClient, FreeFireAPIError

client = FreeFireClient()

try:
    # This will raise InvalidParameterError
    result = client.search_account("ab")  # Too short
except FreeFireAPIError as e:
    print(f"API Error: {e}")

try:
    # This will handle network errors gracefully
    result = client.get_player_profile("invalid_uid")
except FreeFireAPIError as e:
    print(f"Failed to get player data: {e}")

Development

Setting up Development Environment

# Clone the repository
git clone https://github.com/seseegy/freefire-api-python
cd freefire-api-python

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install development dependencies
pip install -e ".[dev]"

Running Tests

# Run all tests
pytest

# Run tests with coverage
pytest --cov=freefire_api --cov-report=html

# Run specific test file
pytest tests/test_client.py

Code Formatting

# Format code with black
black freefire_api/ tests/

# Check formatting
black --check freefire_api/ tests/

# Lint code
flake8 freefire_api/ tests/

# Type checking
mypy freefire_api/

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

• 📧 Email: rosdiyttaa@gmail.com
• 🐛 Issues: GitHub Issues
• 📖 Documentation: GitHub Wiki

Changelog

v1.0.0 (2024-01-01)

• ✨ Initial release
• 🔥 Complete API wrapper with all endpoints
• 🖥️ Command-line interface
• 🧪 Comprehensive test suite
• 📚 Full documentation
• 🛡️ Error handling and type hints

---

Made with ❤️ by Rosdie