Hyundai/Kia Connect API

Common errors

• Error: Invalid credentials for region: <REGION_CODE>

  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.
  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'

  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.
  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'

  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).
  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: ...

  cause 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.

Warnings

• breaking 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.
  Fix: Keep the library updated to the latest version (`pip install --upgrade hyundai-kia-connect-api`) and review release notes for significant changes.
• gotcha Authentication 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.
• gotcha 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.
  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.
• gotcha 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.
  Fix: Double-check the correct region for your account. The `Regions` enum provides options like `USA`, `EU`, `CA`, `AU`, `KR`, `IN`.

Install

• pip install hyundai-kia-connect-api Install stable version

Imports

• VehicleManager

  from hyundai_kia_connect_api import VehicleManager

• Regions

  from hyundai_kia_connect_api import Regions

• Bluelink
  wrong:

  from hyundai_kia_connect_api import BluelinkAPI

  correct:

  from hyundai_kia_connect_api import Bluelink

  Class name is `Bluelink` (an alias for VehicleManager), not `BluelinkAPI`.
• KiaConnect
  wrong:

  from hyundai_kia_connect_api import KiaConnectAPI

  correct:

  from hyundai_kia_connect_api import KiaConnect

  Class name is `KiaConnect` (an alias for VehicleManager), not `KiaConnectAPI`.

Quickstart

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.")