Package

polestar_api

Unofficial async Python client for Polestar vehicle APIs.

BackendProfile dataclass

BackendProfile(battery_svc: str = '/services.vehiclestates.battery.BatteryService', availability_svc: str = '/services.vehiclestates.availability.AvailabilityService', climate_svc: str = '/services.vehiclestates.parkingclimatization.ParkingClimatizationService', dashboard_svc: str = '/services.vehiclestates.dashboard.DashboardService', exterior_svc: str = '/services.vehiclestates.exterior.ExteriorService', health_svc: str = '/services.vehiclestates.health.HealthService', odometer_svc: str = '/services.vehiclestates.odometer.OdometerService', precleaning_svc: str = '/services.vehiclestates.precleaning.PreCleaningService', charge_location_svc: str = '/chronos.services.v1.ChargeLocationService', charge_now_svc: str = '/chronos.services.v1.ChargeNowService', parking_climate_timer_svc: str = '/chronos.services.v1.ParkingClimateTimerService', target_soc_svc: str = '/chronos.services.v1.TargetSocService', amp_limit_svc: str = '/chronos.services.v1.AmpLimitService', charge_timer_svc: str = '/chronos.services.v2.GlobalChargeTimerService', invocation_svc: str = '/invocation.InvocationService', location_svc: str = '/dtlinternet.DtlInternetService', weather_svc: str = '/weather.WeatherService', ota_discovery_svc: str = '/ota_mobcache.OtaDiscoveryService', ota_scheduler_svc: str = '/ota_mobcache.SchedulerService')

gRPC service paths for a specific backend.

Each backend (C3, PCCS, etc.) exposes the same logical services under different gRPC package paths. A BackendProfile maps every service to its concrete path so service clients stay backend-agnostic.

PolestarApi

PolestarApi(email: str, password: str, *, token_store: TokenStore | None = None)

Async client for the Polestar vehicle API.

Usage::

async with PolestarApi(email="...", password="...") as api:
    vehicles = await api.get_vehicles()
    battery = await vehicles[0].get_battery()
    if battery is not None:
        print(battery.charge_level)

async_init async

async_init() -> None

Authenticate and discover endpoints. Must be called before use.

get_vehicles async

get_vehicles() -> list[Vehicle]

Fetch the user's vehicles.

get_vehicle async

get_vehicle(vin: str) -> Vehicle

Get a specific vehicle by VIN.

close async

close() -> None

Close all connections.

Vehicle

Vehicle(vin: str, connection: GrpcConnection, *, internal_id: str | None = None, registration_no: str | None = None, model_year: int | None = None, model_name: str | None = None)

Represents a single Polestar vehicle.

get_battery async

get_battery() -> Battery | None

Charge level, range, charging status, power, voltage, and temperatures, or None if unavailable.

stream_battery async

stream_battery() -> AsyncIterator[Battery]

Real-time battery status updates.

get_exterior async

get_exterior() -> ExteriorStatus | None

Door, window, sunroof, hood, tailgate, and alarm status, or None if unavailable.

stream_exterior async

stream_exterior() -> AsyncIterator[ExteriorStatus]

Real-time exterior status updates (doors, locks, windows).

get_location async

get_location() -> Location

Last known vehicle position.

get_parked_location async

get_parked_location() -> Location

Last parked vehicle position.

stream_location async

stream_location() -> AsyncIterator[Location]

Live position updates.

stream_parked_location async

stream_parked_location() -> AsyncIterator[Location]

Live parked position updates.

get_climate async

get_climate() -> ClimatizationInfo | None

Climatization running status, request type, and heat/cool action, or None if unavailable.

stream_climate async

stream_climate() -> AsyncIterator[ClimatizationInfo]

Live climatization status updates.

start_climate async

start_climate(temperature: float = 0.0, front_left_seat: HeatingIntensity = HeatingIntensity.UNSPECIFIED, front_right_seat: HeatingIntensity = HeatingIntensity.UNSPECIFIED, rear_left_seat: HeatingIntensity = HeatingIntensity.UNSPECIFIED, rear_right_seat: HeatingIntensity = HeatingIntensity.UNSPECIFIED, steering_wheel: HeatingIntensity = HeatingIntensity.UNSPECIFIED) -> ClimatizationResponse

Start climatization with target temperature and optional seat/steering wheel heating.

stop_climate async

stop_climate() -> ClimatizationResponse

Stop climatization.

lock async

lock(feedback: LockFeedback = LockFeedback.NORMAL, alarm_level: LockAlarmLevel = LockAlarmLevel.NORMAL) -> CarLockResponse

Lock the car.

unlock async

unlock(feedback: UnlockFeedback = UnlockFeedback.NORMAL) -> CarUnlockResponse

Unlock the car.

unlock_trunk async

unlock_trunk() -> TrunkUnlockResponse

Unlock the trunk.

honk_flash async

honk_flash(action: HonkFlashAction = HonkFlashAction.FLASH) -> HonkAndFlashResponse

Flash lights or honk and flash.

get_dashboard async

get_dashboard() -> DashboardStatus | None

Trip meters, odometer, and tyre pressure warnings, or None if unavailable.

Note: This is a legacy PCCS endpoint (DashboardService). It is UNIMPLEMENTED on Digital Twin vehicles (Polestar 4+). Use :meth:get_odometer and :meth:get_health instead.

get_connectivity async

get_connectivity() -> ConnectivityInfo | None

Network status, type, and signal strength, or None if unavailable.

Note: Served by the legacy DashboardService. UNIMPLEMENTED on Digital Twin vehicles (Polestar 4+).

get_odometer async

get_odometer() -> OdometerStatus | None

Odometer (meters, converted to km via property), trip meters, and timestamp, or None if unavailable.

get_target_soc async

get_target_soc() -> TargetSocResponse

Get the charge target level.

set_target_soc async

set_target_soc(level: int, setting_type: ChargeTargetLevelSettingType = ChargeTargetLevelSettingType.DAILY) -> TargetSocResponse

Set the charge target level (0-100%).

get_amp_limit async

get_amp_limit() -> AmpLimitResponse

Get the charging amperage limit.

set_amp_limit async

set_amp_limit(amperage: int) -> AmpLimitResponse

Set the charging amperage limit.

get_charge_timer async

get_charge_timer() -> ChargeTimerResponse

Get the scheduled charge timer.

set_charge_timer async

set_charge_timer(timer: BatteryChargeTimer) -> ChargeTimerResponse

Set a scheduled charge timer.

wakeup async

wakeup(reason: WakeUpReason = WakeUpReason.UNDEFINED) -> WakeUpResponse

Wake the car from sleep.

get_health async

get_health() -> Health | None

Service warnings, brake fluid, tyre pressures (kPa), and tyre pressure warnings, or None if unavailable.

Note: On EVs (Polestar 4), engine coolant, oil level, washer fluid, low-voltage battery, and all exterior light warning fields are not reported by the backend and will be their default (UNSPECIFIED/0).

get_availability async

get_availability() -> Availability | None

Vehicle online status and unavailable reason (power saving, OTA, in use, etc.), or None if unavailable.

open_windows async

open_windows() -> ClimatizationResponse

Open all windows.

close_windows async

close_windows() -> ClimatizationResponse

Close all windows.

start_charging async

start_charging() -> int

Start charging immediately.

stop_charging async

stop_charging() -> int

Stop charging.

get_charge_locations async

get_charge_locations() -> list[ChargeLocation]

Saved charge locations with per-location settings (amp limit, min SOC, timers, departure times).

is_at_charge_location async

is_at_charge_location() -> dict

Check if parked at a saved charge location.

create_charge_location async

create_charge_location(alias: str, amp_limit: int = 0, minimum_soc: int = 0, optimised_charging: bool = False) -> ChargeLocation | None

Save the current position as a charge location.

update_charge_location_alias async

update_charge_location_alias(location_id: str, alias: str) -> int

Rename a saved charge location.

update_charge_location_amp_limit async

update_charge_location_amp_limit(location_id: str, amp_limit: int) -> int

Set the amp limit for a saved charge location.

update_charge_location_min_soc async

update_charge_location_min_soc(location_id: str, minimum_soc: int) -> int

Set the minimum SOC for a saved charge location.

update_charge_location_optimised async

update_charge_location_optimised(location_id: str, enabled: bool) -> int

Enable or disable smart charging at a saved location.

delete_charge_location async

delete_charge_location(location_id: str) -> int

Delete a saved charge location.

get_weather async

get_weather() -> WeatherReport | None

Temperature at the car's current location, or None if unavailable.

get_software_info async

get_software_info() -> CarSoftwareInfo | None

Current software version and update state.

Returns None when no software info is available from the backend (observed on Polestar 4 when no OTA update is pending).

get_ota_schedule async

get_ota_schedule() -> Scheduler | None

Scheduled OTA update info.

schedule_ota async

schedule_ota(software_id: str, relative_time: int = 0) -> Scheduler | None

Schedule an OTA update. relative_time is seconds from now.

install_ota_now async

install_ota_now(software_id: str) -> Scheduler | None

Install an OTA update immediately.

cancel_ota async

cancel_ota(software_id: str) -> Scheduler | None

Cancel a scheduled OTA update.

get_climate_timers async

get_climate_timers() -> list[ParkingClimateTimer]

Get all scheduled parking climate timers.

set_climate_timer async

set_climate_timer(timer: ParkingClimateTimer) -> int

Create or update a scheduled parking climate timer.

delete_climate_timer async

delete_climate_timer(timer_id: str) -> int

Delete a scheduled parking climate timer.

get_climate_timer_settings async

get_climate_timer_settings() -> ParkingClimateTimerSettings

Get the default climate settings applied when a parking climate timer fires.

set_climate_timer_settings async

set_climate_timer_settings(settings: ParkingClimateTimerSettings) -> int

Set the default climate settings for parking climate timers.

get_precleaning async

get_precleaning() -> PreCleaningInfo | None

Air quality status, PM2.5 levels, running state, and runtime remaining.

Returns None when the backend sends an empty pre-cleaning payload.

stream_precleaning async

stream_precleaning() -> AsyncIterator[PreCleaningInfo]

Real-time pre-cleaning status updates.

start_precleaning async

start_precleaning() -> None

Start cabin air quality pre-cleaning.

stop_precleaning async

stop_precleaning() -> None

Stop cabin air quality pre-cleaning.