polestar_api

A lightweight, type-safe Rust wrapper for the Polestar vehicle GraphQL API.

Disclaimer: This library is not affiliated with nor supported by Polestar.

Features

• Type-safe: Leverages Rust's type system for compile-time guarantees
• Async-first: Built on async/await with Tokio runtime
• Comprehensive: Supports all major Polestar API endpoints
• Well-tested: Extensive unit, mock, and integration tests
• Documented: Full API documentation and examples

Supported Endpoints

• [WIP] Vehicle Telemetry - Battery status, charging info, odometer
• ✅ Consumer Vehicle Data - Vehicle specifications, features, images
• [WIP] Specifications - Detailed vehicle specification metadata

Quick Start

Installation

Add this to your Cargo.toml:

[dependencies]
polestar_api = "0.1"
tokio = { version = "1", features = ["full"] }

Usage

use polestar_api_rs::PolestarClient;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Create a client with your Polestar account credentials
    let client = PolestarClient::new("your_email@example.com", "your_password")?;

    // Fetch vehicle telemetry
    let telemetry = client.get_telemetry("YOUR_VIN").await?;

    println!("Battery: {:.1}%",
        telemetry.battery.charge_level_percentage.unwrap_or(0.0));

    Ok(())
}

Authentication

The client authenticates using your Polestar account credentials (username and password). The library handles the web-based login flow to obtain access tokens from the Polestar authentication service.

Note: Authentication implementation is currently in progress. The client accepts username and password credentials which will be used to authenticate with the Polestar API. See the pypolestar reference implementation for examples of the authentication flow.

Security: Never commit credentials to version control. Use environment variables:

export POLESTAR_USERNAME="your_email@example.com"
export POLESTAR_PASSWORD="your_password"
export POLESTAR_VIN="your_vin"

Examples

Get Battery Status

let client = PolestarClient::new("user@example.com", "password")?;
let telemetry = client.get_telemetry("VIN").await?;

if let Some(charge) = telemetry.battery.charge_level_percentage {
    println!("Battery: {:.1}%", charge);
}

if let Some(status) = telemetry.battery.charge_status {
    println!("Status: {}", status);
}

Get Vehicle Information

let client = PolestarClient::new("user@example.com", "password")?;
let vehicle = client.get_vehicle("VIN").await?;

println!("Model: {}", vehicle.content.model.name.unwrap_or_default());
println!("Market: {}", vehicle.market.unwrap_or_default());

See the examples/ directory for more complete examples.

Documentation

• Implementation Plan - Development roadmap
• Architecture - Technical design and decisions
• Test Harness - Testing strategy and tools
• API Reference - Polestar API documentation

Testing

Run all tests:

cargo test

Run integration tests (requires credentials):

export POLESTAR_USERNAME="your_email@example.com"
export POLESTAR_PASSWORD="your_password"
export POLESTAR_VIN="your_vin"
cargo test --test integration_tests

Use the test harness CLI:

cargo run --example test_harness --features cli -- \
  --username "$POLESTAR_USERNAME" \
  --password "$POLESTAR_PASSWORD" \
  --vin "$POLESTAR_VIN" \
  --endpoint all

Development Status

Current Version: 0.1.0 (Planning Phase)

This project is in active development. The current release includes:

• ✅ Comprehensive planning documentation
• ✅ Architecture design
• ✅ Test harness specification
• 🚧 Implementation in progress

See PLAN.md for the complete roadmap.

Contributing

Contributions are welcome! Please open an issue or pull request on GitHub. Contribution guidelines will be added in a future release.

License

Dual-licensed under either of:

• Apache License, Version 2.0 (apache.org/licenses/LICENSE-2.0)
• MIT license (opensource.org/licenses/MIT)

at your option.

Disclaimer

This is an unofficial, community-maintained wrapper for the Polestar API. It is not affiliated with, endorsed by, or supported by Polestar or Volvo Car Corporation.

Acknowledgments

• pypolestar - Python reference implementation
• The Rust community for excellent async tooling

References

• Polestar Official Site
• GraphQL Specification