Metadata-Version: 2.4
Name: unofficial-polestar-api
Version: 0.1.0
Summary: Unofficial async Python client for Polestar vehicle APIs
Project-URL: Homepage, https://github.com/kildahldev/unofficial-polestar-api
Project-URL: Issues, https://github.com/kildahldev/unofficial-polestar-api/issues
License-Expression: MIT
License-File: LICENSE
Keywords: api,car,ev,grpc,home-assistant,polestar
Classifier: Development Status :: 3 - Alpha
Classifier: Framework :: AsyncIO
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Home Automation
Requires-Python: >=3.12
Requires-Dist: grpclib>=0.4.7
Requires-Dist: httpx>=0.27
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Provides-Extra: docs
Requires-Dist: mkdocs-material>=9.6; extra == 'docs'
Requires-Dist: mkdocs>=1.6; extra == 'docs'
Requires-Dist: mkdocstrings[python]>=0.30; extra == 'docs'
Description-Content-Type: text/markdown


# unofficial-polestar-api

Unofficial async Python client for Polestar vehicle gRPC APIs.

This project aims to bring you as much control as possible over your car. It uses the same APIs as the official mobile app and exposes most functionality (Atleast for the PS4 for now)


## Supported Cars

This library for now just implements the **C3** (Volvo Cars Cloud Connectivity) backend. The Polestar app actually supports four backends — C3, PCCS, Vocmo, and HuanFu — and the server assigns one per vehicle via a `remoteControlType` field.

The server assigns a backend per vehicle — which cars use which backend is currently unclear, but the Polestar 4 (Which i developed against) - responds to commands through the C3 Backend. 

If you use this library (or the HA integration) please report back what works and what doesn't, for your model.

Contributions and testing from owners of other models are welcome and encouraged

| Model | Backend | Verified         |
|---|---|------------------|
| Polestar 4 | C3 | ✅ Mostly working |

| Backend | Status |
|---|---|
| C3 | ✅ Implemented |
| PCCS | ❌ Not implemented |
| Vocmo | ❌ Not implemented |
| HuanFu | ❌ Not implemented |

Not all features are available on all models.


## Usage

### Home Assistant
For integrating with Home Assistant, use this integration (which uses this API)

### As a library

```python
from polestar_api import PolestarApi

async with PolestarApi(email="you@example.com", password="...") as api:
    vehicles = await api.get_vehicles()
    car = vehicles[0]

    battery = await car.get_battery()
    print(f"{battery.charge_level}% — {battery.range_km} km")

    location = await car.get_location()
    print(f"Lat {location.coordinate.latitude}, Lon {location.coordinate.longitude}")
```

## Features

- **Battery** — charge level, range, charging status, power (with real-time streaming)
- **Location** — last known and last parked position (with real-time streaming)
- **Climate** — start/stop climatization with target temperature, seat and steering wheel heating
- **Climate timers** — view and manage scheduled parking climate timers
- **Locks** — lock, unlock, trunk unlock
- **Honk & flash** — flash lights or honk+flash
- **Windows** — open/close all windows
- **Exterior** — door, window, sunroof, hood, tailgate, and alarm status
- **Charging** — target SOC, amp limit, charge timers, start/stop immediate charging
- **Charge locations** — full CRUD for saved locations with per-location amp limits, min SOC, timers, departure times, and smart charging
- **Health** — service warnings, fluid levels, tyre pressures (kPa), all exterior light warnings, 12V battery
- **Availability** — vehicle online status with unavailable reason
- **Weather** — temperature at car location
- **OTA** — software update info, scheduling, install now, cancel
- **Pre-cleaning** — air quality status (PM2.5, AQI) and start/stop cabin pre-cleaning

For the full API reference with all methods, models, and enums, see the [docs](docs/).

## Disclaimer

This project is not affiliated with, endorsed by, or in any way officially connected to Polestar, Volvo Cars, or any of their subsidiaries.

This library does not contain any proprietary code, or copyrighted material from Polestar or Volvo. All code is written from scratch by observing the behaviour of the official app.

All API interactions are based on reverse-engineered, undocumented interfaces. These may change or break without notice. Use at your own risk. The authors are not responsible for any consequences of using this software, including but not limited to vehicle malfunctions, warranty implications, or account restrictions.
