Registry / communication / hyundai-kia-connect-api

hyundai-kia-connect-api

JSON →
library4.16.0pypypi✓ verified 84d ago

The `hyundai-kia-connect-api` library provides a Python interface to interact with Hyundai and Kia Connect (Bluelink/Uvo) services. It allows users to fetch vehicle status, send remote commands, and manage their connected car. The library is actively maintained with frequent releases (several times a month) to adapt to upstream API changes and add new features.

pip install hyundai-kia-connect-api
INSTALL
IMPORT
SIG · HYUNDAI-KIA-CONNEC
H
hyundai-kia-connect-api
communicationpythonv4.16.0
Install
3.1s avg
Import
760ms
Disk
32MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v4.16.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.103.910 runs
installs and imports cleanly · install 0.0s · import 0.797s · 34.8MB
glibc
py 3.103.910 runs
installs and imports cleanly · install 3.1s · import 0.723s · 36MB
32MB installed
● package 32MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

VehicleManager
from hyundai_kia_connect_api import VehicleManager
Regions
from hyundai_kia_connect_api import Regions
Bluelink
from hyundai_kia_connect_api import Bluelink
from hyundai_kia_connect_api import BluelinkAPI
Class name is `Bluelink` (an alias for VehicleManager), not `BluelinkAPI`.
KiaConnect
from hyundai_kia_connect_api import KiaConnect
from hyundai_kia_connect_api import KiaConnectAPI
Class name is `KiaConnect` (an alias for VehicleManager), not `KiaConnectAPI`.

Initializes the `VehicleManager` with user credentials and region, then authenticates and fetches a list of vehicles and their latest status. Ensure environment variables `HMC_USERNAME`, `HMC_PASSWORD`, `HMC_PIN`, and `HMC_REGION` are set or replace placeholders directly in the script.

import os from hyundai_kia_connect_api import VehicleManager, Regions USERNAME = os.environ.get('HMC_USERNAME', 'your_username') PASSWORD = os.environ.get('HMC_PASSWORD', 'your_password') # Your 4-digit PIN, mandatory for some commands. Replace '1234' with your actual PIN. PIN = os.environ.get('HMC_PIN', '1234') # e.g., USA, EU, CA, AU, KR, IN. Replace 'USA' with your region. REGION_CODE = os.environ.get('HMC_REGION', 'USA') if USERNAME == 'your_username' or PASSWORD == 'your_password' or PIN == '1234': print("Please set HMC_USERNAME, HMC_PASSWORD, HMC_PIN, and HMC_REGION environment variables or update script placeholders.") else: try: region = getattr(Regions, REGION_CODE.upper()) manager = VehicleManager( username=USERNAME, password=PASSWORD, region=region, pin=PIN ) print(f"Attempting to login for region: {REGION_CODE}") manager.check_and_update_token() print("Login successful. Fetching vehicles...") vehicles = manager.get_vehicles() if vehicles: print(f"Found {len(vehicles)} vehicle(s):") for vehicle_id, vehicle in vehicles.items(): print(f" Vehicle ID: {vehicle_id}, Name: {vehicle.name}") status = vehicle.get_latest_status() if status: print(f" Engine: {status.engineOn}, Doors: {status.doorOpen}, Lock: {status.doorLock}") else: print(" Could not retrieve vehicle status (vehicle might be offline).") else: print("No vehicles found.") except Exception as e: print(f"An error occurred: {e}") print("Please ensure your username, password, PIN, and region are correct and your vehicle is connected.")
Debug
Known issues
breakingThe upstream Hyundai/Kia Connect APIs frequently change, often requiring immediate library updates. Minor version bumps (e.g., 4.x to 4.y) can introduce breaking changes if upstream APIs are modified significantly.
fix
Keep the library updated to the latest version (`pip install --upgrade hyundai-kia-connect-api`) and review release notes for significant changes.
affects: All versions, especially older ones, due to external API volatility.
gotchaAuthentication tokens expire, and the library handles refresh automatically. However, frequent requests can trigger rate limiting or temporary bans from the upstream API.
fix
Implement exponential backoff or sensible delays between requests. Avoid polling too frequently. The `check_and_update_token()` method should be called regularly but not excessively.
affects: All versions.
gotchaA 4-digit PIN is mandatory for sending most remote commands (e.g., start/stop engine, lock/unlock doors). If not provided during `VehicleManager` initialization, commands will fail.
fix
Always pass the `pin` argument when initializing `VehicleManager` if you intend to send commands, even if just fetching data, as the login flow might require it.
affects: All versions.
gotchaRegional differences in the upstream APIs are significant. Using the wrong `Regions` enum value (e.g., `Regions.USA` for an EU account) will lead to authentication failures.
fix
Double-check the correct region for your account. The `Regions` enum provides options like `USA`, `EU`, `CA`, `AU`, `KR`, `IN`.
affects: All versions.
Errors
Common errors & fixes
Error: Invalid credentials for region: <REGION_CODE>
Incorrect username, password, or PIN provided for the specified region, or the region itself is wrong for your account. Check for typos or if the region code matches your vehicle's market.
fix
Verify your Hyundai/Kia Connect app login details and ensure the `Regions` enum (e.g., `Regions.USA`) matches your account's geographical location.
KeyError: 'Vehicle not found'
The vehicle ID or VIN used to access a specific vehicle via `vehicles[vehicle_id]` does not exist in the list returned by `get_vehicles()` after a successful login.
fix
Iterate through `manager.get_vehicles()` to get available vehicle IDs and ensure you are using one of them. The vehicle might also be offline or not fully provisioned.
AttributeError: 'NoneType' object has no attribute 'engineOn'
The `get_latest_status()` method might return `None` if the vehicle data could not be fetched (e.g., vehicle is offline, communication error, or API rate limit).
fix
Always check if the result of `get_latest_status()` (or other data-fetching methods) is not `None` before attempting to access its attributes. If `None`, consider retrying or checking vehicle connectivity.
requests.exceptions.ConnectionError: HTTPSConnectionPool(...) Max retries exceeded with url: ...
Network connectivity issues, upstream API server downtime, or aggressive rate limiting by the Hyundai/Kia servers causing temporary blocks to your IP.
fix
Check your internet connection. Wait a few minutes and retry, potentially with a backoff strategy. Reduce the frequency of API calls if you are making many requests to avoid hitting rate limits.
Upgrade
Version history
4.16.0latest on PyPI · released Jun 15, 2026
Audit
Dependencies
requestsrequiredCore HTTP client for API interactions.
beautifulsoup4requiredRequired for parsing HTML responses during authentication.
lxmlrequiredFast parser backend for `beautifulsoup4`.
aiohttpoptionalRequired for asynchronous API interactions via `KiaConnectAsync`.
asyncio_throttleoptionalUsed with `aiohttp` for rate limiting in async operations.
Agent activity
22 hits · last 30 days
node
16
OpenAI (training)
1
Resources
hyundai-kia-connect-api — pip install hyundai-kia-connect-api · libregistry