faceit 0.2.0

The Python wrapper for the FACEIT API

FACEIT Python API Library

The easiest and most type-safe way to interact with the FACEIT API.

Access FACEIT data — player stats, matches, and tournaments — directly from Python.

---

Features

• 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 timestamp pagination.
• Flexible data access — Choose between raw data and parsed models (e.g., .raw_players vs .players).
• Page collection utilities — Paginated responses in model mode are wrapped in an ItemPage collection with convenient methods, such as .map(), .filter(), .find(), and more.

Installation

Requires Python 3.8+

pip install faceit

For automatic environment variable loading (see API Key Handling):

pip install faceit[env]

Quickstart

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

[!IMPORTANT] Currently, only the Data Resource is available.
Access to this resource requires a valid API key, which you can obtain via the official FACEIT Developer Portal.

import faceit

# 1. Initialize the Data Resource.
# If `FACEIT_API_KEY` is set in your environment, no arguments are needed.
data = faceit.SyncDataResource()  # or faceit.SyncDataResource("YOUR_API_KEY")

# 2. Fetch player data by nickname.
nickname = input("Enter the player's nickname: ")
player = data.players.get(nickname)

# 3. Get all CS2 matches for the player.
# Returns an `ItemPage` — a type-safe collection with built-in utility methods.
matches = data.players.all_matches_stats(player.id, faceit.GameID.CS2)

print(f"Total CS2 matches for {player.nickname}: {len(matches)}")

# 4. Perform data analysis.
# Filter for matches with a positive K/D ratio (1 or higher).
positive_kd_matches = matches.filter(lambda m: m.kd_ratio >= 1)

total_count = len(matches)
positive_count = len(positive_kd_matches)

kd_rate = (positive_count / total_count * 100) if total_count > 0 else 0

print(f"Matches with K/D >= 1: {positive_count}")
print(f"{player.nickname}'s positive K/D rate: {kd_rate:.2f}%")

See additional usage examples in the examples/ directory.

API Key Handling

You can provide your API key directly in the constructor or let the library automatically load it from your environment.

• Automatic: Set the FACEIT_API_KEY environment variable. (Requires faceit[env] or manual python-decouple installation).
• Manual: Pass the key string directly: SyncDataResource("YOUR_API_KEY").
• Custom Variable: To use a different environment variable name, pass an instance of EnvKey: SyncDataResource(EnvKey("SECRET"))

Motivation

This project was born out of necessity while building a product that works closely with the FACEIT platform.
Existing solutions did not offer the level of type safety, convenience, or abstraction needed for strong, maintainable code.
The goal is to provide a solution approaching enterprise-level quality, while remaining accessible and useful for a wide range of users.

Project Status & Roadmap

[!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.
• In-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!

Planned Improvements

• Support for more endpoints and models
• Webhooks and chat API integration
• Full documentation and usage guides

---

This project is licensed under the Apache License 2.0. See the LICENSE file for details.