Free Fire Account Information Python Library By HL GAMING OFFICIAL

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 release directly from the Python Package Index (PyPI) using pip:

pip install hl-gaming-official-ff-data

This command installs version 2.3.7 (or later), along with its required dependency, requests. To update an existing installation to the newest version, run:

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

For production deployments, explicitly pin the version in your requirements.txt file:

hl-gaming-official-ff-data==2.3.7

Authentication

Each API request must include two required credentials: API Key (your confidential developer key) and User UID (your HL Gaming Official developer UID). These credentials authenticate you, enable usage tracking, and enforce daily request quotas.

To obtain your api key and useruid:

Visit the HL Gaming Official Developer Portal.
Log in with your developer account.
Navigate to the “API Credentials” section. Copy your useruid (Developer UID) and api (API Key).

        Security Note: Never embed your API Key in client-side code. Store it in environment variables or a secure secret store on your server.
      

Library Method: `get_player_data`

The primary function of this library is:

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

get_player_data requires the following arguments:

player_uid (string, required): The Free Fire Player UID you wish to fetch, for example "9351564274". If this argument is missing or an empty string, the method raises a ValueError.
user_uid (string, required): Your HL Gaming Official Developer UID. If omitted or an empty string, a ValueError is raised.
region (string, optional): A two-letter region code (e.g., "pk", "sg", "in"). If provided, this overrides the default region set in the constructor; otherwise the client’s default region is used.

The method returns a Python dict containing the exact JSON structure from the server on success. On failure, the method raises a branded Exception with either the JSON error body (if available) or a clear fallback message.

View on PyPI

The hl-gaming-official-ff-data library is published on the Python Package Index (PyPI). You can visit the official PyPI page below to see the latest release, documentation, and metadata:

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

On the PyPI project page, you’ll find:

Release History: A chronological list of all published versions (e.g., 2.3.7, 2.3.8, etc.), including release dates and changelogs.
Installation Command: The exact pip install command to install or upgrade the package (e.g., pip install hl-gaming-official-ff-data).
Package Metadata: Project description, author/maintainer information, license, and links to the source repository.
Download Statistics: Weekly and monthly download counts, giving insight into community adoption.
Related Links: Quick access to the homepage, source code on GitHub, issue tracker, and documentation.

Recommended Actions:

# 1. Install or upgrade directly from PyPI:
pip install --upgrade hl-gaming-official-ff-data

# 2. To check available versions programmatically (e.g., in CI/CD):
pip index versions hl-gaming-official-ff-data

By periodically visiting the PyPI page or using pip index versions, you ensure that your application is always up to date with the latest bug fixes, performance improvements, and feature enhancements. If you encounter any issues or have questions, the project’s PyPI page also links to the issue tracker and source repository for reporting bugs or requesting new features.

Parameters & Validation

Parameter	Required	Type	Description
`player_uid`	Yes	string	The Free Fire Player UID to query. Example: `"9351564274"`. If missing or empty, a `ValueError` is raised.
`user_uid`	Yes	string	Your Developer UID from HL Gaming Official. If missing, a `ValueError` is raised.
`region`	No	string	Two-letter region code (e.g., `"pk"`, `"sg"`). Case-sensitive. Overrides the constructor’s default region when provided.

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_player_data obtains a successful HTTP 200 response, it returns the entire JSON payload as a Python dict. Below is an illustrative example of the full structure:

View Full JSON Schema (expand to see 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:\u3164@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\u1d1c\u1d0d\u1d0d\u028fE\u1d20\u1d00T\u1d07\u1d00\u1d0d",
      "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:\u3164@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
  }
}

In your Python code, access nested fields directly. For example:

Example: Access Nested Fields

# Accessing fields in the returned dict
player_info  = player_data["result"]["AccountInfo"]
player_name  = player_info["AccountName"]
player_level = player_info["AccountLevel"]
guild_name   = player_data["result"]["GuildInfo"]["GuildName"]
pet_name     = player_data["result"]["petInfo"]["name"]
daily_left   = player_data["usage"]["remainingToday"]

Error Response

Whenever the underlying API returns an HTTP status code 4xx or 5xx, get_player_data raises a single Exception with a standardized, branded message. If the server returned a JSON-formatted error body, that JSON appears verbatim immediately after “❗ Error details from API:”, enabling you to see exactly what the service returned.

View Standardized Error Message (with JSON details if provided)

API error: 📡 HL Gaming API returned an error (4xx/5xx).
❗ Error details from API:
{ ...exact JSON returned by HL Gaming Official... }
🔁 Please check your API key, Player UID, and Region.
📚 Docs: https://www.hlgamingofficial.com/p/api.html
🆘 Need help? Contact support: https://www.hlgamingofficial.com/p/contact-us.html

If the response body is not valid JSON or is empty, you will see:

View Fallback Message for Non-JSON Error

API error: ❗ HL API returned an error, and no JSON body was found.
🔁 Please check your API key, Player UID, and Region.
📚 Docs: https://www.hlgamingofficial.com/p/api.html
🆘 Need help? Contact support: https://www.hlgamingofficial.com/p/contact-us.html

For network failures (timeouts, DNS issues, etc.), the library raises:

View Network Failure Message

API error: ⚠️ Could not connect to HL API. Check your internet or endpoint.

For any other unexpected exception inside the client code:

View Unexpected Exception Message

API error: ❗ An unexpected error: <original exception message>

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.7 — 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.