Free Fire Account Information Python Library By HL GAMING OFFICIAL - Documentation



Overview

The hl-gaming-official-ff-data Python library offers a simple, high-level interface to retrieve a Free Fire player’s complete account information from HL Gaming Official’s “AllData” REST API. By calling a single method, developers can fetch detailed JSON data—such as account level, rank, inventory, guild membership, pet information, and more—without manually constructing HTTP requests or parsing complex responses. This library encapsulates parameter validation, network requests, and branded error handling. It returns standard Python dictionaries that exactly mirror the JSON structure returned by the server, enabling seamless integration into analytics dashboards, custom web apps, or community tools.

Key Benefits:

  • Single Method Fetch: Retrieve the entire account payload with get_player_data.
  • Automatic Error Handling: On any HTTP 4xx/5xx response, the library returns the exact JSON error body when available or a clear branded message when no JSON is present.
  • Endpoint Privacy: The underlying API endpoint remains hidden; developers receive branded guidance rather than raw URLs or internal server details.
  • Python-Native Output: All responses are delivered as dict types, ready to consume without further conversion.

This library is proprietary to HL Gaming Official (hlgamingofficial.com). All rights are exclusively reserved by HL Gaming Official. Redistribution, modification, or reuse of this code in any form is strictly forbidden unless you have obtained explicit written permission from HL Gaming Official’s legal department. Unauthorized use will be considered a serious violation of intellectual property rights.

Misuse or unauthorized distribution of this code is strictly prohibited. If you knowingly distribute or publicly post this library without HL Gaming Official’s consent, you will face immediate termination of all API access privileges and potential legal action. Any developer or organization found in breach of these terms will be held fully accountable for damages.

License Terms: This library may only be used in strict accordance with the official license agreement located at: https://hlgamingofficial.com/p/license.html. By using this library, you agree to abide by all conditions outlined in that document, including but not limited to permitted use cases, duration, and any stated limitations or requirements.

Redistribution or commercial resale of this library without HL Gaming Official’s prior written permission is strictly forbidden. If you intend to integrate this library into a commercial product or distribute it publicly, you must obtain an appropriate license from HL Gaming Official’s licensing team. Failure to do so will result in immediate suspension of services and possible legal proceedings.

Any reverse engineering, decompilation, or unauthorized copying of this code is a direct violation of these terms. Under no circumstances should you attempt to deconstruct the inner workings of the HLFFClient or extract proprietary algorithms contained within this library. Such actions will be met with immediate legal repercussions as set forth in the license agreement.

For full license details and permissible use cases, please visit the License Page at: https://hlgamingofficial.com/p/license.html. This document contains the complete terms, including any regional restrictions, data usage policies, and obligations for attribution. You are responsible for reviewing the latest version of the license before integrating this library into your project.

If you have any questions, need clarification on permitted use, or require a commercial license, please contact us at: developers@hlgamingofficial.com. Our licensing team will respond promptly with guidance on obtaining the appropriate permissions and any associated fees.

WARNING: Using this library beyond the granted permissions will result in immediate suspension of your API access and may lead to legal consequences, including but not limited to claims for damages, injunctive relief, and termination of developer accounts.

Installation

Install the latest stable release from PyPI: 

pip install hl-gaming-official-ff-data

This installs hl-gaming-official-ff-data and its runtime dependency requests. The package release for this documentation is 2.3.8.

To upgrade an existing installation: 

pip install --upgrade hl-gaming-official-ff-data

For production, pin the version in requirements.txt: 

hl-gaming-official-ff-data==2.3.8

Optional extras (recommended for better resiliency & caching): 

# HTTP retries (urllib3 included with requests)
# Optional cache support:
pip install cachetools

Authentication

Every request to the HL Gaming Official Free Fire API requires two credentials: API Key (field name api) and User UID (field name useruid). These are used to authenticate requests and track usage / quotas.

To obtain these credentials:

  1. Open the HL Gaming Official Developer Portal.
  2. Sign in with your developer account.
  3. Go to the API Credentials (or Developer Dashboard) section and copy the useruid and api values.
Security Note: Do not embed API keys or developer UIDs in client-side code or public repositories. Use environment variables or a secrets store (Vercel Environment Variables, AWS Secrets Manager, etc.) for production.

Primary Library Methods

client.get_all_data(player_uid: str, user_uid: str, region: Optional[str] = None) → dict

The primary convenience method to fetch the full account payload is get_all_data. It returns the same JSON structure the HL Gaming server provides for the AllData section. 

# Basic usage example
from hl_gaming_official_ff_data import HLFFClient

client = HLFFClient(api_key="YOUR_API_KEY", region="pk")
result = client.get_all_data(player_uid="9351564274", user_uid="YOUR_USER_UID", region="pk")

Behavior: on success the method returns a Python dict matching the API JSON. On failure it raises a branded exception (see Exceptions below). The client also supports optional per-request caching, retries, and backoff configured at client construction.

client.get_section(section_name: str, player_uid: str, user_uid: str, region: Optional[str] = None) → dict

Use get_section to fetch a specific section (for example "AccountInfo", "Guild Info", "Pet Info", "Ban Check", or "AllData"). 

# Fetch a specific section
data = client.get_section("AccountInfo", player_uid="9351564274", user_uid="YOUR_USER_UID")

Notes on queued / rate-limited responses

The API may return a queued or PENDING response for per-UID rate-limits. Example returned payload: 

{
  "endpoint": "AllData",
  "result": {
    "message": "Queued due to per-UID rate limit",
    "queuedUntil": "2025-08-14T04:39:39.904Z",
    "status": "PENDING"
  }
}

If you receive a PENDING response, respect queuedUntil and retry at or after that timestamp, or implement an asynchronous worker / cache to poll later — avoid busy-loop retries.

Exceptions

The client raises branded exceptions derived from HLFFClientError: AuthError, RateLimitError, APIError, NetworkError, InvalidResponseError. Callers should catch HLFFClientError for structured error handling and may inspect e.to_dict() for details.

View on PyPI

The package is published on PyPI: 

https://pypi.org/project/hl-gaming-official-ff-data

On the PyPI page you can find release history, installation instructions, metadata and links to the source repository and issue tracker. Use pip index versions hl-gaming-official-ff-data to list available versions programmatically.

Parameters & Validation

ParameterRequiredTypeDescription
player_uid Yes string The Free Fire Player UID to query. Example: "9351564274". Missing or empty → ValueError.
user_uid Yes string Your Developer UID (useruid) from HL Gaming Official. Missing or empty → ValueError.
region No string Two-letter region code (e.g. "pk", "in", "sg"). If provided, overrides the client's default region.
Parameter Errors: 
ValueError("🚫 Player UID is required. Example: '9351564274'")
ValueError("🚫 User UID is required. This helps track your API usage.")
Supported Regions
Below are the regions supported by the HL Gaming API. Please select the appropriate region when making API requests. This will ensure you are interacting with the correct server for your region:
Region Code
India ind
Brazil br
Singapore sg
Russia ru
Indonesia id
Taiwan tw
United States us
Vietnam vn
Thailand th
Middle East me
Pakistan pk
cis cis
Bangladesh bd
To obtain your User id and API Key, please visit the API Key Page for more details. Make sure to secure your credentials to avoid unauthorized usage.

Success Response Schema

When get_all_data receives HTTP 200, it returns the full JSON payload as a Python dict. Nested fields are accessible directly. **Queued / PENDING responses are now first-class and do not raise exceptions**.

Full JSON Schema (all fields) 
{
  "endpoint": "AllData",
  "result": {
    "AccountInfo": {
      "AccountAvatarId": 902000154,
      "AccountBPBadges": 1,
      "AccountBPID": 1001000085,
      "AccountBannerId": 901049014,
      "AccountCreateTime": "1512595169",
      "AccountEXP": 2088986,
      "AccountLastLogin": "1748797387",
      "AccountLevel": 67,
      "AccountLikes": 3417960,
      "AccountName": "FB:GMRemyX",
      "AccountRegion": "SG",
      "AccountSeasonId": 45,
      "AccountType": 1,
      "BrMaxRank": 321,
      "BrRankPoint": 3646,
      "CsMaxRank": 317,
      "CsRankPoint": 68,
      "ReleaseVersion": "OB49",
      "ShowBrRank": true,
      "ShowCsRank": true,
      "Title": 904090023
    },
    "AccountProfileInfo": {
      "EquippedOutfit": [203000543, 204000103, 211037076, 211000028, 214039011, 205000455],
      "EquippedSkills": [16, 706, 8, 1, 16, 3806, 8, 2, 16, 2506, 8, 3, 16, 1706]
    },
    "GuildInfo": {
      "GuildCapacity": 55,
      "GuildID": "60893361",
      "GuildLevel": 7,
      "GuildMember": 46,
      "GuildName": "MᴍᴏᴅᴏEᴛAᴏᴅ",
      "GuildOwner": "12345678"
    },
    "captainBasicInfo": {
      "EquippedWeapon": [907104822, 912048002, 914048001],
      "accountId": "12345678",
      "accountType": 1,
      "badgeCnt": 1,
      "badgeId": 1001000085,
      "bannerId": 901049014,
      "createAt": "1512595169",
      "csMaxRank": 317,
      "csRank": 317,
      "csRankingPoints": 68,
      "exp": 2088986,
      "headPic": 902000154,
      "lastLoginAt": "1748797387",
      "level": 67,
      "liked": 3417960,
      "maxRank": 321,
      "nickname": "FB:GMRemyX",
      "rank": 321,
      "rankingPoints": 3646,
      "region": "SG",
      "releaseVersion": "OB49",
      "seasonId": 45,
      "showBrRank": true,
      "showCsRank": true,
      "title": 904090023
    },
    "creditScoreInfo": {
      "creditScore": 100,
      "periodicSummaryEndTime": "1748657008",
      "rewardState": "REWARD_STATE_UNCLAIMED"
    },
    "newUpdate": {
      "diamondCostRes": {
        "diamondCost": 390
      }
    },
    "petInfo": {
      "exp": 6000,
      "id": 1300000071,
      "isSelected": true,
      "level": 7,
      "name": "SiNo",
      "selectedSkillId": 1315000009,
      "skinId": 1310000071
    },
    "socialinfo": {
      "AccountID": "12345678",
      "AccountLanguage": "Language_EN",
      "AccountSignature": "FB & YT GM Remy | TikTok :gmremyx | IG GM Remy",
      "ModePreference": "ModePrefer_BR",
      "RankDisplay": "RankShow_CS"
    },
  },
  "source": "HL Gaming Official",
  "usage": {
    "dailyLimit": 999,
    "remainingToday": 986,
    "usedToday": 13
  }
}
Example: Access nested fields 
player_info  = player_data["result"]["AccountInfo"]
player_name  = player_info["AccountName"]
player_level = player_info["AccountLevel"]
guild_name   = player_data["result"].get("GuildInfo", {}).get("GuildName")
pet_name     = player_data["result"].get("petInfo", {}).get("name")
daily_left   = player_data["usage"]["remainingToday"]
Example: Handle queued / PENDING response 
res = player_data.get("result", {})
if res.get("status") == "PENDING":
    print("Data queued until:", res.get("queuedUntil"))
else:
    print("Player Level:", res["AccountInfo"]["AccountLevel"])

Error Handling

All exceptions derive from HLFFClientError. Common subclasses:

  • AuthError — 401/403
  • RateLimitError — 429
  • APIError — other 4xx/5xx
  • NetworkError — connection failures, timeouts
  • InvalidResponseError — server returned unparsable/non-JSON content
Exception structure example 
{
  "message": "Authentication failure",
  "code": "AUTH_ERROR",
  "details": {
    "local": {
      "summary": "Invalid API key or insufficient permissions",
      "probable_causes": ["API key missing", "User UID mismatch"],
      "suggestions": ["Verify API key", "Check user UID and region"],
      "debug": {"status_code": 401, "body": "{...}"}
    },
    "ai": { "suggestions": ["Contact support if issue persists"] }
  }
}
Python: catch & inspect errors 
try:
    data = client.get_all_data(player_uid="9351564274", user_uid="YOUR_USER_UID")
    if data.get("result", {}).get("status") == "PENDING":
        print("Queued until:", data["result"]["queuedUntil"])
    else:
        print("Player Name:", data["result"]["AccountInfo"]["AccountName"])
except RateLimitError as e:
    print("Rate limited:", e.to_dict())
except AuthError as e:
    print("Auth failed:", e.to_dict())
except HLFFClientError as e:
    print("Client error:", e.to_dict())
except Exception as e:
    print("Unexpected error:", str(e))

Best practices:

  • Respect queuedUntil timestamps instead of busy-looping.
  • Use cache_ttl to avoid repeated per-UID calls.
  • Handle RateLimitError with exponential backoff + jitter.
  • Log e.to_dict() for easier HL Gaming support troubleshooting.
  • Always check status in result to distinguish SUCCESS vs PENDING.

Imports & Supported Classes

The HLFF Python client provides a structured set of imports to interact with the HL Gaming Official API. All imports are fully typed and include comprehensive error handling, convenience methods, and data modeling. You can import the client core, error classes, and utility methods as follows:

Full Import List 
from hlff_client import (
    HLFFClient,         # Core client class for querying player data and API endpoints
    HLFFClientError,    # Base exception for all client-side errors
    AuthError,          # Raised when authentication fails (invalid API key / 401 / 403)
    RateLimitError,     # Raised when API rate limit is exceeded (429)
    APIError,           # Raised for general 4xx or 5xx HTTP responses
    NetworkError,       # Raised for connection failures, DNS issues, or timeouts
    InvalidResponseError # Raised when server response is invalid or non-JSON
)

HLFFClient: This is the main class to instantiate for making API calls. Example usage: 

client = HLFFClient(api_key="YOUR_API_KEY")
player_data = client.get_all_data(player_uid="12345678")

HLFFClientError: Base exception that all other exceptions inherit from. Useful for catching generic client errors while still being able to distinguish detailed subtypes.

AuthError: Raised when authentication fails, such as incorrect API keys, mismatched player UID, or insufficient permissions. Always catch this separately to prompt the user to verify credentials.

RateLimitError: Raised when API rate limits are exceeded. Implement exponential backoff or queueing strategies when this occurs. The exception contains metadata about current limits and retry suggestions.

APIError: Covers all 4xx and 5xx HTTP errors returned by the HL Gaming Official API. The exception exposes the exact JSON returned by the API, allowing detailed debugging and error logging.

NetworkError: Raised for connectivity issues such as DNS failures, timeouts, or unreachable endpoints. Suggested handling includes retrying requests with backoff and checking internet connectivity.

InvalidResponseError: Raised when the server response is not JSON or cannot be parsed. Ensure the API is up-to-date and the request matches the current endpoint schema.

In combination, these imports provide a **robust, production-ready client** for HL Gaming Official. Handling each exception class separately allows precise recovery strategies while maintaining full visibility into all API responses.

Best Practices

  • Client-Side Caching: Cache valid player data for 5–10 minutes to reduce redundant API calls and improve performance under load.
  • Pre-Validation Checks: Always verify that player_uid is numeric (or matches expected format) and region is one of the known codes before making a request.
  • Graceful Quota Handling: Inspect usage.remainingToday in successful responses. Warn end users when they are close to their daily limit.
  • Retry Logic: On transient 5xx or 502 errors, implement exponential back-off and retry a few times before failing permanently.

Security Recommendations

  • Always use HTTPS: Ensure that communication with HL Gaming Official’s API is encrypted end-to-end.
  • Protect Credentials: Do not hardcode api_key or user_uid in client-side code. Store them in environment variables or a secure vault on your server.
  • Rotate API Keys: Change your API Key every 90 days and immediately revoke it if you suspect it is compromised.
  • Network Restriction: Restrict outbound traffic from your servers to only HL Gaming Official’s API domain, preventing unauthorized use.

Logging & Analytics

For auditing and monitoring, log each request’s parameters (excluding api_key), timestamp, and HTTP status code. Capture the usage section from successful responses to track daily usage trends. Forward these logs to an APM or analytics service (e.g., Datadog, New Relic) to measure latency, error rates, and application behavior over time.

FAQ

Q: What if I supply the wrong region value?
A: The API will return a 4xx error JSON, typically indicating “Player not found.” You will see that JSON under “Error details from API.” Ensure you use the correct region code where the player’s account is registered.

Q: How can I tell if I have exhausted my daily quota?
A: Every successful response includes a usage object containing remainingToday. When it reaches zero, subsequent calls will trigger a JSON error with a code indicating “quota exceeded.” Implement client-side warnings based on remainingToday values.

Q: Why does the library not expose the actual API URL?
A: To protect backend stability and prevent unauthorized scraping, the library intentionally hides internal endpoint details. You receive branded guidance rather than direct URLs, ensuring that your code always uses the official, supported interface.

Changelog

  • v2.3.8 — Enhanced error handling to return exact JSON on HTTP errors; suppressed License-File metadata in packaging; improved documentation with deeper usage examples.
  • v2.3.5 — Added license_files=[] to setup.py to fix PyPI metadata; updated README with visual badges and extended usage instructions.
  • v2.3.4 — Renamed package to hl-gaming-official-ff-data; introduced branded error messages and improved parameter validation to avoid exposing internal details.
  • v2.3.3 — Initial support for returning raw JSON on HTTP errors; embedded HL Gaming Official support URLs in error messages.

Support & Contact

For interactive guides, live testing, or developer assistance, visit the official support portal: HL Gaming Official Support. To report bugs, request features, or ask questions, email developers@hlgamingofficial.com or submit a request through the support site.

🚫 API Usage Limit: Free plans are limited to 25 API requests per day. This includes all operations such as checking ban status, rank verification, and other related endpoints. To increase your request limit and unlock additional features such as advanced rank metadata, detailed ban history, and real-time moderation integration, please consider upgrading your plan.
HL Gaming Official Free Fire Account Information Python Library API Documentation © 2025
Contact: Developers | Support

#buttons=(Accept !) #days=(20)

HL GAMING Uses cookies to enhance your experience. Check Now
Accept !

HL GAMING OFFICIAL FAST VIEW

Site Guider Chat
SmartView

SmartView

Notifications

Bookmarks

Recent

Most Visited

Live Chat NEW

Edit Bookmark

This is an Advertisement
5
This is an Advertisement
5