freefire-api 1.0.0
Powerful Python wrapper for FreeFire API
License: MIT
Requires Python: >=3.7
Keywords: freefire, api, gaming, player-stats, game-api

# 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

```bash
pip install freefire-api
```

Or install from source:

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

## Quick Start

### Basic Usage

```python
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:

```bash
# 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:

```bash
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

```python
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

```python
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

```python
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

```python
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

```bash
# 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

```bash
# 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

```bash
# 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](LICENSE) file for details.

## Support

- 📧 Email: rosdiyttaa@gmail.com
- 🐛 Issues: [GitHub Issues](https://github.com/seseegy/freefire-api-python/issues)
- 📖 Documentation: [GitHub Wiki](https://github.com/seseegy/freefire-api-python/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**