leapmotor-api 0.1.0

Unofficial Python client for the Leapmotor vehicle cloud API

leapmotor-api

Unofficial Python client for the Leapmotor vehicle cloud API.

Extracted from the leapmotor-ha Home Assistant integration to provide a reusable, framework-agnostic library.

Acknowledgments

Special thanks to Jakob Kern for the impressive reverse engineering work on the Leapmotor application and for generously sharing his work.

Installation

pip install leapmotor-api

Quick Start

from leapmotor_api import LeapmotorApiClient

client = LeapmotorApiClient(
    username="[e-mail]",
    password="password",
    app_cert_path="/path/to/app_cert.pem",
    app_key_path="/path/to/app_key.pem",
    language="it-IT",  # default: en-GB
)

client.login()
vehicles = client.get_vehicle_list()

for vehicle in vehicles:
    print(f"{vehicle.vin} ({vehicle.car_type}) — {vehicle.nickname}")
    status = client.get_vehicle_status(vehicle)
    print(f"  Battery: {status.battery.soc}%")
    print(f"  Range: {status.battery.expected_mileage} km")
    print(f"  Odometer: {status.driving.total_mileage} km")

client.close()

Typed Models vs Raw Data

The library exposes two ways to access vehicle data:

Typed models (recommended)

get_vehicle_status() returns a VehicleStatus dataclass with typed sub-objects:

status = client.get_vehicle_status(vehicle)

# Battery & charging
status.battery.soc                  # int | None — state of charge %
status.battery.expected_mileage     # int | None — remaining range km
status.battery.is_charging          # bool | None
status.battery.charging_power_kw    # float | None
status.battery.dump_energy_kwh      # float | None — available energy in kWh

# Driving
status.driving.total_mileage        # int | None — odometer km
status.driving.speed                # int | None
status.driving.is_parked            # bool | None

# Location
status.location.latitude            # float | None
status.location.longitude           # float | None

# Climate
status.climate.ac_switch            # bool | None
status.climate.outdoor_temp         # int | None

# Doors & locks
status.doors.is_locked              # bool | None

# Windows
status.windows.left_front_window_percent   # int | None

# Tire pressure
status.tires.front_left_bar         # float | None — pressure in bar
status.tires.all_ok                 # bool | None — all pressures normal

# Connectivity
status.connectivity.bluetooth_state # bool | None

# Timestamps
status.collect_time                 # datetime | None

Raw API data

For forward-compatibility or debugging, use get_vehicle_raw_status():

raw = client.get_vehicle_raw_status(vehicle)
# Returns the full API JSON dict with signal codes, config, etc.
# raw["data"]["signal"]["1204"]  → battery SOC
# raw["data"]["config"]["3"]     → charging plan

The VehicleStatus object also retains the raw dict in status.raw for convenience.

Async Usage

from leapmotor_api import LeapmotorApiClient
from leapmotor_api.async_client import AsyncLeapmotorApiClient

sync_client = LeapmotorApiClient(
    username="[e-mail]",
    password="password",
    app_cert_path="/path/to/app_cert.pem",
    app_key_path="/path/to/app_key.pem",
    language="it-IT",
)
client = AsyncLeapmotorApiClient(sync_client)

await client.login()
vehicles = await client.get_vehicle_list()
status = await client.get_vehicle_status(vehicles[0])
await client.close()

Remote Control

Remote actions require the vehicle PIN:

client = LeapmotorApiClient(
    username="[e-mail]",
    password="password",
    app_cert_path="/path/to/app_cert.pem",
    app_key_path="/path/to/app_key.pem",
    operation_password="1234",
    language="de-DE",
)

client.login()
client.lock_vehicle("WLM...")
client.unlock_vehicle("WLM...")
client.open_trunk("WLM...")
client.close_trunk("WLM...")
client.find_vehicle("WLM...")
client.open_windows("WLM...")
client.close_windows("WLM...")
client.ac_switch("WLM...")
client.quick_cool("WLM...")
client.quick_heat("WLM...")
client.windshield_defrost("WLM...")
client.open_sunshade("WLM...")
client.close_sunshade("WLM...")
client.battery_preheat("WLM...")
client.set_charge_limit("WLM...", charge_limit_percent=80)
client.close()

License

MIT

Configuration

Parameter	Type	Default	Description
username	str	—	Leapmotor account email
password	str	—	Leapmotor account password
app_cert_path	str	—	Path to app certificate PEM
app_key_path	str	—	Path to app private key PEM
operation_password	str | None	None	Vehicle PIN (required for remote control)
language	str	"en-GB"	API language (en-GB, it-IT, de-DE, fr-FR, …)
verify_ssl	bool	False	Verify server TLS certificate
base_url	str	DEFAULT_BASE_URL	API base URL
timeout	int	30	HTTP timeout in seconds
device_id	str | None	None	Custom device ID (auto-generated if omitted)