This library makes it easy to access and use data from the FACEIT gaming platform – such as player stats, matches, and tournaments – directly from your Python programs, without needing to understand the technical details of the FACEIT API. Automate and integrate FACEIT data into your projects, whether building apps, analyzing stats, or creating tools for esports and gaming.
See the official FACEIT API documentation for details about the available data and endpoints.
- Python 3.8 or higher
- High-level, idiomatic API – Interact with FACEIT as if it were a native Python service.
- Full type safety – Compatible with mypy and other type checkers.
- Sync & async support – Powered by httpx.
- Pydantic models – All data models inherit from
pydantic.BaseModel. - Advanced pagination – Supports both cursor-based and unix-time-based iterators.
- Flexible data access – Choose between raw data and parsed models (e.g.,
.raw_players/.players). - Page collection utilities – Paginated responses in model mode are wrapped in an
ItemPagecollection with convenient methods, such as.map(),.filter(),.find(), and more.
pip install faceit
You can also install with the env extra to enable loading the API key from environment files (details below):
pip install faceit[env]
You can get started in just a few lines of code.
Below is a minimal example demonstrating how to retrieve the complete CS2 match history for a player using the synchronous API.
Important
Currently, only the Faceit Data resource is available, and access requires a valid API key.
You can obtain your API key by following the instructions in the official FACEIT documentation.
You can specify your API key directly in the constructor, or let the library automatically load it from your environment (e.g., .env, settings.ini).
By default, the key is read from the FACEIT_API_KEY variable.
To use a different variable, pass an instance of EnvKey to the constructor:
from faceit import Faceit, EnvKey
data = Faceit.data(EnvKey("API_KEY_FIELD"))Note
Loading the API key from environment files requires either installing the [env] extra or installing python-decouple yourself.
from faceit import Faceit, GameID
# Initialize the API client.
# If FACEIT_API_KEY is set in your environment, you can omit the argument.
data = Faceit.data() # or Faceit.data("YOUR_API_KEY")
# Fetch player information by nickname.
player = data.players.get("s1mple")
# Retrieve all CS2 match history for the player.
# Returns an ItemPage collection (fully-featured iterable).
matches = data.players.all_history(player.id, GameID.CS2)
print(f"Total CS2 matches for {player.nickname}: {len(matches)}")
# Example: Find a match by its ID.
match_id = "1-441ff69f-09e3-4c58-b5c4-a0a7424fe8e0"
some_match = matches.find("id", match_id)
if some_match:
print(f"Found match with ID {match_id}: {some_match}")
else:
print(f"No match found with ID {match_id}")See additional usage examples in the examples/ directory.
This project was created out of necessity during the development of a product requiring deep integration with the FACEIT platform. Existing solutions did not offer the level of type safety, convenience, or abstraction needed for robust, maintainable code. The goal is to provide a solution approaching enterprise-level quality, while remaining accessible and useful for a wide range of users.
Warning
This library is currently in early development.
Many endpoints, models, and features are not yet implemented.
Webhooks, chat API, and some advanced features are not available yet.
Inline code documentation is minimal, and the Sphinx-based documentation site is not yet ready.
Expect breaking changes and incomplete coverage.
Contributions and feedback are highly welcome!
- Support for more endpoints and models
- Webhooks and chat API integration
- Complete documentation and usage guides
Contributions, bug reports, and feature requests are welcome!
Please see CONTRIBUTING.md for detailed guidelines before opening an issue or pull request.
This project is licensed under the Apache License 2.0. See the LICENSE file for details.