{"id":50398442,"url":"https://github.com/zombyacoff/faceit-python","last_synced_at":"2026-05-30T22:01:22.400Z","repository":{"id":288624386,"uuid":"956427496","full_name":"zombyacoff/faceit-python","owner":"zombyacoff","description":"The Python wrapper for the FACEIT API","archived":false,"fork":false,"pushed_at":"2026-05-24T12:25:23.000Z","size":621,"stargazers_count":21,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-05-24T14:21:27.281Z","etag":null,"topics":["api-wrapper","cs2","csgo","faceit","faceit-api","httpx","pydantic","python"],"latest_commit_sha":null,"homepage":"https://docs.faceit.com/docs/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/zombyacoff.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-03-28T08:36:53.000Z","updated_at":"2026-05-24T12:25:27.000Z","dependencies_parsed_at":"2025-07-26T00:16:06.419Z","dependency_job_id":"4f5696c2-cd60-4083-bcc4-4583fd5ef6a9","html_url":"https://github.com/zombyacoff/faceit-python","commit_stats":null,"previous_names":["zombyacoff/faceit-python"],"tags_count":11,"template":false,"template_full_name":null,"purl":"pkg:github/zombyacoff/faceit-python","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zombyacoff%2Ffaceit-python","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zombyacoff%2Ffaceit-python/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zombyacoff%2Ffaceit-python/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zombyacoff%2Ffaceit-python/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/zombyacoff","download_url":"https://codeload.github.com/zombyacoff/faceit-python/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zombyacoff%2Ffaceit-python/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33711018,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-30T02:00:06.278Z","response_time":92,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api-wrapper","cs2","csgo","faceit","faceit-api","httpx","pydantic","python"],"created_at":"2026-05-30T22:01:21.689Z","updated_at":"2026-05-30T22:01:22.393Z","avatar_url":"https://github.com/zombyacoff.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n# FACEIT Python API Library\n\n[![Python](https://img.shields.io/badge/Python-3.10%2B-FAD6C5?style=flat-square)](https://www.python.org/)\n[![PyPI](https://img.shields.io/pypi/v/faceit?label=PyPI\u0026style=flat-square\u0026color=FAD6C5)](https://pypi.org/project/faceit/)\n[![License](https://img.shields.io/badge/License-Apache_2.0-FAD6C5?style=flat-square)](https://opensource.org/licenses/Apache-2.0)\n[![Downloads](https://img.shields.io/pypi/dm/faceit?label=Downloads\u0026style=flat-square\u0026color=FAD6C5)](https://pypi.org/project/faceit/)\n\n[![FACEIT API](https://img.shields.io/badge/FACEIT_API-Reference-FF5500?style=flat-square\u0026logo=faceit)](https://docs.faceit.com/docs)\n\n**The easiest and most type-safe way to interact with the FACEIT API.**\n\n\u003c!-- Access FACEIT data — player stats, matches, and tournaments — directly from Python. --\u003e\n\n\u003c/div\u003e\n\n---\n\n## Features\n\n- **High-level, idiomatic API** — Interact with FACEIT as if it were a native Python service.\n- **Full type safety** — Compatible with [mypy](https://mypy-lang.org/) and other type checkers.\n- **Sync \u0026 async support** — Powered by [httpx](https://www.python-httpx.org/).\n- **Pydantic models** — All data models inherit from [`pydantic.BaseModel`](https://docs.pydantic.dev/latest/concepts/models/).\n- **Advanced pagination** — Supports both cursor-based and Unix timestamp pagination.\n- **Flexible data access** — Choose between raw data and parsed models (e.g., `.raw_players` vs `.players`).\n- **Page collection utilities** — Paginated responses in model mode are wrapped in an `ItemPage` collection with convenient methods, such as `.map()`, `.filter()`, `.find()`, and more.\n\n## Installation\n\n\u003e Requires **Python 3.10+**.\n\n```bash\npip install faceit\n```\n\nFor automatic environment variable loading (see [API Key Handling](#api-key-handling)):\n\n```bash\npip install faceit[env]\n```\n\n## Quickstart\n\nGet started in seconds. The following example demonstrates how to fetch a player's CS2 matches and perform a basic performance analysis using the synchronous API.\n\n\u003e [!IMPORTANT]\n\u003e Currently, only the Data Resource is available.  \n\u003e Access to this resource requires a valid API key, which you can obtain via the official [FACEIT Developer Portal](https://docs.faceit.com/getting-started/authentication/api-keys/).\n\n```py\nimport faceit\n\n# 1. Initialize the Data Resource.\n# If `FACEIT_API_KEY` is set in your environment, no arguments are needed.\ndata = faceit.SyncDataResource()  # or faceit.SyncDataResource(\"YOUR_API_KEY\")\n\n# 2. Fetch player data by nickname.\nnickname = input(\"Enter the player's nickname: \")\nplayer = data.players.get(nickname)\n\n# 3. Get all CS2 matches for the player.\n# Returns an `ItemPage` — a type-safe collection with built-in utility methods.\nmatches = data.players.all_matches_stats(player.id, faceit.GameID.CS2)\n\nprint(f\"Total CS2 matches for {player.nickname}: {len(matches)}\")\n\n# 4. Perform data analysis.\n# Filter for matches with a positive K/D ratio (1 or higher).\npositive_kd_matches = matches.filter(lambda m: m.kd_ratio \u003e= 1)\n\ntotal_count = len(matches)\npositive_count = len(positive_kd_matches)\n\nkd_rate = (positive_count / total_count * 100) if total_count \u003e 0 else 0\n\nprint(f\"Matches with positive K/D: {positive_count}\")\nprint(f\"{player.nickname}'s positive K/D rate: {kd_rate:.2f}%\")\n```\n\nSee additional usage examples in the [examples/](examples/) directory.\n\n### API Key Handling\n\nYou can provide your API key directly in the constructor or let the library automatically load it from your environment.\n\n- **Automatic:** Set the `FACEIT_API_KEY` environment variable.  \n    Requires `faceit[env]` extra dependency or manual [python-decouple](https://github.com/HBNetwork/python-decouple) installation.\n- **Manual:** Pass the key string directly: `SyncDataResource(\"YOUR_API_KEY\")`.\n- **Custom Variable:** To use a different environment variable name, pass an instance of `FromEnv`: `SyncDataResource(FromEnv(\"SECRET\"))`\n\n## Motivation\n\nThis project was born out of necessity while building a product that works closely with the FACEIT platform.  \nExisting solutions did not offer the level of type safety, convenience, or abstraction needed for strong, maintainable code.  \nThe goal is to provide a solution approaching enterprise-level quality, while remaining accessible and useful for a wide range of users.\n\n## Project Status \u0026 Roadmap\n\n\u003e [!WARNING]\n\u003e This library is currently in **early development**.\n\u003e\n\u003e - Many endpoints, models, and features are not yet implemented.\n\u003e - Webhooks, chat API, and some advanced features are not available yet.\n\u003e - In-code documentation is minimal, and the Sphinx-based documentation site is not yet ready.\n\u003e - Expect breaking changes and incomplete coverage.\n\u003e\n\u003e **Contributions and feedback are highly welcome!**\n\n### Planned Improvements\n\n- Support for more endpoints and models.\n- Webhooks and chat API integration.\n- Full documentation and usage guides.\n\n---\n\nThis project is licensed under the Apache License 2.0. See the [LICENSE](LICENSE) file for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzombyacoff%2Ffaceit-python","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzombyacoff%2Ffaceit-python","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzombyacoff%2Ffaceit-python/lists"}