cs2-api 1.0.0

CS2 API client for Rust: Counter-Strike 2 live scores, match results, player stats, teams, rankings (world + VRS), events and skin prices
Documentation
# CS2 API for Rust

[![crates.io](https://img.shields.io/crates/v/cs2-api)](https://crates.io/crates/cs2-api) [![docs.rs](https://img.shields.io/docsrs/cs2-api)](https://docs.rs/cs2-api) [![license](https://img.shields.io/badge/license-MIT-blue)](LICENSE)

`cs2-api` is the official Rust client for the **CS2 API** at [cs2-api.org](https://cs2-api.org). One blocking client, two small dependencies (`ureq` with rustls, `serde_json`), and every Counter-Strike 2 endpoint you need:

- live CS2 match scores and round-level scoreboards
- match results, schedules and streams
- player stats (rating, ADR, KAST, K/D) and leaderboards
- teams, rosters and head-to-head records
- the world ranking and Valve Regional Standings (VRS)
- events, standings and brackets
- roster transfers
- **CS2 skin prices across 25+ marketplaces**, with price history and trending movers

> **You need a free API key** (500 requests/month, no card): **[Get a free API key]https://citoapi.com/signup?game=cs2&utm_source=crates&utm_medium=referral&utm_campaign=cs2-api-package**

## Install

```bash
cargo add cs2-api
```

Or in `Cargo.toml`:

```toml
[dependencies]
cs2-api = "1"
```

## Quickstart

```rust,no_run
use cs2_api::Client;

fn main() -> Result<(), cs2_api::Error> {
    let cs2 = Client::from_env()?; // reads CITO_API_KEY

    // Every CS2 match being played right now
    for m in cs2.live()?.as_array().into_iter().flatten() {
        println!(
            "{} {}-{} {} on {}",
            m["team1Name"], m["team1Score"], m["team2Score"], m["team2Name"], m["currentMap"]
        );
    }

    let ranking = cs2.world_ranking(10)?;
    let vitality = cs2.team("vitality")?; // roster + recent results
    let donk = cs2.player("donk")?;
    let prices = cs2.skin_prices("ak-47-redline-field-tested-1ab1a2dc")?;
    println!("{ranking}\n{vitality}\n{donk}\n{prices}");
    Ok(())
}
```

Pass the key directly with `Client::new("your-key")?`, or set a base URL and timeout:

```rust,no_run
use std::time::Duration;

let cs2 = cs2_api::Client::builder()
    .api_key("your-key")
    .timeout(Duration::from_secs(10))
    .build()?;
# Ok::<(), cs2_api::Error>(())
```

Every method returns the `data` field of the response as a `serde_json::Value`. `get_raw(path, query)` returns the whole envelope (`success`, `data`, `meta`) for pagination.

## Endpoints

Teams, players and events accept an id or a slug (`vitality`, `donk`). Path segments are percent-encoded for you.

| Area | Methods |
|---|---|
| Live | `live()`, `live_scoreboard(match_id)`: sides, round, player K/D/ADR, money |
| Matches | `upcoming(limit)`, `results(limit)`, `today()`, `match_by_id(id)`, `match_maps(id)`, `match_player_stats(id)`, `match_streams(id)` |
| Teams | `team(slug)`, `team_matches(slug, limit)`, `team_stats(slug)`, `team_map_stats(slug)`, `head_to_head(a, b)` |
| Players | `player(slug)`, `search_players(q, limit)`, `player_stats(slug)`, `player_matches(slug, limit)` |
| Events | `events(status, limit)` (`"upcoming"`, `"live"`, `"recent"`), `event(slug)`, `event_matches(slug)`, `event_standings(slug)`, `event_bracket(slug)` |
| Rankings & stats | `world_ranking(limit)`, `vrs_ranking(limit)`, `leaderboard(metric, limit)`, `transfers(limit)`, `search(q)` |
| Skins | `search_skins(q, filters)`, `skin(slug)`, `skin_prices(slug)`, `skin_history(slug, range)`, `trending_skins(timeframe, limit, min_price)` |
| Anything else | `get(path, query)` / `get_raw(path, query)`: any of the 140+ endpoints |

## Errors

Every call returns `Result<Value, cs2_api::Error>`:

- `Error::Http { status, code, message }`: the API answered with an error (bad key, not found, rate limit)
- `Error::Transport(_)`: no response (DNS, connection, TLS, timeout)
- `Error::Decode(_)`: the body was not JSON
- `Error::MissingKey`: no key passed and `CITO_API_KEY` not set

`Error` implements `std::error::Error`, so `?` works with `anyhow`, `Box<dyn Error>` and friends.

## Use cases

- **Discord bots**: [cs2-discord-bot]https://github.com/achillesscriptsvip/cs2-discord-bot
- **Stream overlays**: [cs2-obs-overlay]https://github.com/achillesscriptsvip/cs2-obs-overlay
- **Skin trading tools**: [cs2-skin-price-api]https://github.com/achillesscriptsvip/cs2-skin-price-api
- Fantasy, analytics dashboards, prediction models and AI agents

## Keep your key safe

Keep it in an environment variable or a git-ignored `.env`. If a key leaks, revoke it in your dashboard and create a new one.

## Links

- CS2 API docs and endpoints: https://cs2-api.org
- API reference for this crate: https://docs.rs/cs2-api
- Pricing: https://citoapi.com/pricing
- Issues: https://github.com/achillesscriptsvip/cs2-api/issues

Also available for [JavaScript (npm)](https://www.npmjs.com/package/cs2-api) and [Python (PyPI)](https://pypi.org/project/cs2-api/).

Not affiliated with Valve, HLTV, ESL, BLAST or PGL. MIT licensed.