unifi-controller-api

A Python client library for interacting with Ubiquiti UniFi Network Controllers.

Warning: This package is under active development and is subject to breaking changes, incomplete or incorrect documentation, etc.

Core Features

• Structured Data Models: Opitionally parses API responses into typed Python objects (e.g., UnifiDevice, UnifiSite, UnifiClient, LLDPEntry, UnifiWlanConf).
• Automatic Model Mapping: Translates model codes (e.g., U7PG2) to friendly names ("UniFi® AC Pro AP") via the model_name attribute.
• Convenience Methods: Includes helpers for data export (export_csv, export_json).
• Minimal Dependencies: Requires only requests.
• Python >= 3.9

Installation

pip install unifi-controller-api

Quick Start

from unifi_controller_api import UnifiController

# 1. Initialize & Authenticate
controller = UnifiController(
    controller_url="https://<CONTROLLER_IP_OR_HOSTNAME>", # Use :8443 for UniFi OS, :443 for legacy
    username="<LOCAL_ADMIN_USER>",
    password="<PASSWORD>",
    is_udm_pro=True, # Set True for UniFi OS devices (UDM, Cloud Key Gen2+), False for legacy software/hardware controllers
    verify_ssl=False, # Or path to your CA bundle, set True if using a valid public certificate
    auto_model_mapping=True, # Optional: Attempt to map device model codes to friendly names
    model_db_path=None, # Optional: Path to a custom model database file
    auth_retry_enabled=True, # Optional: Enable automatic retries on authentication failure
    auth_retry_count=3, # Optional: Number of authentication retries
    auth_retry_delay=5 # Optional: Delay in seconds between authentication retries
)

# 2. Fetch Data (Example: Devices for the 'default' site)
site_name = "default" # Use the internal site name
try:
    devices = controller.get_unifi_site_device(site_name=site_name, detailed=True)

    # 3. Use the Typed Data
    for device in devices:
        print(f"- {device.name} ({device.model_name}): {device.ip} / {device.mac}")
        if device.lldp_info:
            print(f"  LLDP: {len(device.lldp_info)} neighbors")

except Exception as e:
    print(f"Error fetching devices for site '{site_name}': {e}")

# Other available methods:
# sites = controller.get_unifi_site()
# clients = controller.get_clients(site_name)
# wlans = controller.get_wlan_conf(site_name)
# alarms = controller.get_alarms(site_name)
# events = controller.get_events(site_name)
# rogue_aps = controller.get_rogue_aps(site_name)
# networks = controller.get_network_conf(site_name)
# report = controller.devices_report(site_names=['site1', 'site2'])

# Exporting data:
# from unifi_controller_api.export import export_csv, export_json
# if devices:
#     export_csv(devices, "devices.csv")
#     export_json(devices, "devices.json")

Connectivity Notes

• Requires direct network access to the controller.
• The controller_url should include the scheme (https) and port (e.g., https://192.168.1.1:443 for UniFi OS, https://unifi.example.com:8443 for older software controllers).
• Requires direct network access to the controller.
• Uses HTTPS port 443 by default for UniFi OS devices (UDM, Cloud Key Gen2+).
• Uses HTTPS port 8443 by default for legacy controllers (Software, Cloud Key Gen1).
• Requires a local controller account, not a UniFi Cloud/SSO account.
• Set is_udm_pro=True when connecting to UniFi OS based controllers (like UDM Pro, UDM SE, Cloud Key Gen2 Plus running UniFi OS). Set to False for software-based controllers or older Cloud Keys not running UniFi OS.
• For verify_ssl: set to False for self-signed certificates (common in local deployments), True if your controller has a valid, publicly trusted SSL certificate, or provide a path to your CA bundle file.
• auto_model_mapping (default True) automatically translates device model codes (e.g., "U7PG2") to human-readable names (e.g., "UniFi AC Pro AP").
• auth_retry_enabled (default True) allows the client to automatically retry authentication on failure, useful for temporary network issues.

Data Models

The library automatically maps JSON API responses to Python data classes located in unifi_controller_api.models. Key models include:

• UnifiSite: Represents a controller site.
• UnifiDevice: Represents a network device (AP, Switch, Gateway).
• LLDPEntry: Holds LLDP neighbor details (nested within UnifiDevice).
• UnifiClient: Represents a connected client (wired or wireless).
• UnifiWlanConf: Represents a Wireless LAN configuration.
• UnifiNetworkConf: Represents a Network configuration.
• UnifiAlarm: Represents a controller alarm.
• UnifiEvent: Represents a controller event.
• UnifiRogueAp: Represents a detected rogue access point.

Use standard object attribute access (e.g., device.ip, site.desc) to work with the data.

Logging

Uses standard Python logging. Configure the unifi_controller_api logger:

import logging
logging.getLogger("unifi_controller_api").setLevel(logging.DEBUG)
# Ensure you have a handler configured (e.g., via logging.basicConfig)
logging.basicConfig(level=logging.INFO) # Example: Show INFO level and above

Disclaimer

This is an unofficial library using APIs that may change without notice. Not affiliated with Ubiquiti Inc. Use at your own risk.