{"id":9823,"library":"hyundai-kia-connect-api","title":"Hyundai/Kia Connect API","description":"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.","status":"active","version":"4.9.0","language":"en","source_language":"en","source_url":"https://github.com/Hyundai-Kia-Connect/hyundai_kia_connect_api","tags":["automotive","api","hyundai","kia","smart-car","connect","vehicle-data"],"install":[{"cmd":"pip install hyundai-kia-connect-api","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Core HTTP client for API interactions.","package":"requests","optional":false},{"reason":"Required for parsing HTML responses during authentication.","package":"beautifulsoup4","optional":false},{"reason":"Fast parser backend for `beautifulsoup4`.","package":"lxml","optional":false},{"reason":"Required for asynchronous API interactions via `KiaConnectAsync`.","package":"aiohttp","optional":true},{"reason":"Used with `aiohttp` for rate limiting in async operations.","package":"asyncio_throttle","optional":true}],"imports":[{"symbol":"VehicleManager","correct":"from hyundai_kia_connect_api import VehicleManager"},{"symbol":"Regions","correct":"from hyundai_kia_connect_api import Regions"},{"note":"Class name is `Bluelink` (an alias for VehicleManager), not `BluelinkAPI`.","wrong":"from hyundai_kia_connect_api import BluelinkAPI","symbol":"Bluelink","correct":"from hyundai_kia_connect_api import Bluelink"},{"note":"Class name is `KiaConnect` (an alias for VehicleManager), not `KiaConnectAPI`.","wrong":"from hyundai_kia_connect_api import KiaConnectAPI","symbol":"KiaConnect","correct":"from hyundai_kia_connect_api import KiaConnect"}],"quickstart":{"code":"import os\nfrom hyundai_kia_connect_api import VehicleManager, Regions\n\nUSERNAME = os.environ.get('HMC_USERNAME', 'your_username')\nPASSWORD = os.environ.get('HMC_PASSWORD', 'your_password')\n# Your 4-digit PIN, mandatory for some commands. Replace '1234' with your actual PIN.\nPIN = os.environ.get('HMC_PIN', '1234')\n# e.g., USA, EU, CA, AU, KR, IN. Replace 'USA' with your region.\nREGION_CODE = os.environ.get('HMC_REGION', 'USA')\n\nif USERNAME == 'your_username' or PASSWORD == 'your_password' or PIN == '1234':\n    print(\"Please set HMC_USERNAME, HMC_PASSWORD, HMC_PIN, and HMC_REGION environment variables or update script placeholders.\")\nelse:\n    try:\n        region = getattr(Regions, REGION_CODE.upper())\n        manager = VehicleManager(\n            username=USERNAME,\n            password=PASSWORD,\n            region=region,\n            pin=PIN\n        )\n        \n        print(f\"Attempting to login for region: {REGION_CODE}\")\n        manager.check_and_update_token()\n        print(\"Login successful. Fetching vehicles...\")\n        \n        vehicles = manager.get_vehicles()\n        if vehicles:\n            print(f\"Found {len(vehicles)} vehicle(s):\")\n            for vehicle_id, vehicle in vehicles.items():\n                print(f\"  Vehicle ID: {vehicle_id}, Name: {vehicle.name}\")\n                status = vehicle.get_latest_status()\n                if status:\n                    print(f\"    Engine: {status.engineOn}, Doors: {status.doorOpen}, Lock: {status.doorLock}\")\n                else:\n                    print(\"    Could not retrieve vehicle status (vehicle might be offline).\")\n        else:\n            print(\"No vehicles found.\")\n\n    except Exception as e:\n        print(f\"An error occurred: {e}\")\n        print(\"Please ensure your username, password, PIN, and region are correct and your vehicle is connected.\")","lang":"python","description":"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."},"warnings":[{"fix":"Keep the library updated to the latest version (`pip install --upgrade hyundai-kia-connect-api`) and review release notes for significant changes.","message":"The 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.","severity":"breaking","affected_versions":"All versions, especially older ones, due to external API volatility."},{"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.","message":"Authentication tokens expire, and the library handles refresh automatically. However, frequent requests can trigger rate limiting or temporary bans from the upstream API.","severity":"gotcha","affected_versions":"All versions."},{"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.","message":"A 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.","severity":"gotcha","affected_versions":"All versions."},{"fix":"Double-check the correct region for your account. The `Regions` enum provides options like `USA`, `EU`, `CA`, `AU`, `KR`, `IN`.","message":"Regional 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.","severity":"gotcha","affected_versions":"All versions."}],"env_vars":null,"last_verified":"2026-04-17T00:00:00.000Z","next_check":"2026-07-16T00:00:00.000Z","problems":[{"fix":"Verify your Hyundai/Kia Connect app login details and ensure the `Regions` enum (e.g., `Regions.USA`) matches your account's geographical location.","cause":"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.","error":"Error: Invalid credentials for region: <REGION_CODE>"},{"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.","cause":"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.","error":"KeyError: 'Vehicle not found'"},{"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.","cause":"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).","error":"AttributeError: 'NoneType' object has no attribute 'engineOn'"},{"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.","cause":"Network connectivity issues, upstream API server downtime, or aggressive rate limiting by the Hyundai/Kia servers causing temporary blocks to your IP.","error":"requests.exceptions.ConnectionError: HTTPSConnectionPool(...) Max retries exceeded with url: ..."}]}