README

A PHP class that provides access to Ubiquiti's official UniFi Cloud API for their Site Manager platform.

Introduction

This client provides a modern and convenient way to interact with the official UniFi Cloud API using PHP. It uses Guzzle for HTTP requests and supports various operations to interact with UniFi deployments programmatically.

This client supports the official UniFi Cloud API up to version 0.1.

Important Note

This is not a replacement for our original API Client which offers more functions and endpoints, but does not support connections through unifi.ui.com: https://github.com/Art-of-WiFi/UniFi-API-client

Requirements

• a server with:
  • PHP 8.1 or higher installed.
  • the php-curl module installed and enabled.
• direct network connectivity between this server and https://api.ui.com where the UniFi Cloud API is hosted.
• an API key that can be obtained as follows:
  • Sign in to the UniFi Site Manager at https://unifi.ui.com.
  • From the left navigation bar, click on API.
  • Click Create API Key.
  • Copy the key and store it securely, as it will only be displayed once.
  • Click Done to ensure the key is hashed and securely stored.

Installation

The package needs to be installed using Composer/packagist for easy inclusion in your projects by executing the following command from your project directory:

composer require art-of-wifi/unifi-cloud-api-client

Follow these installation instructions if you don't have Composer installed already.

Developer Documentation

Usage

Below is a basic example of how to use the UniFi Cloud API Client:

<?php

require 'vendor/autoload.php';

use UniFiCloudApiClient\Client\UniFiClient;

$apiKey = 'your_api_key_here';

try {
    // Initialize the UniFi Cloud API client, optionally you can pass a different base URI
    $unifiClient = UniFiClient::getInstance($apiKey);
    
    // Enable debug mode, optional
    $unifiClient->setDebug(true);
    
    // Set a custom timeout to override the default value of 10 seconds, optional
    $unifiClient->setTimeout(5);
    
    // Fetch and echo the version
    echo 'UniFi Cloud API client version: ' . $unifiClient->getVersion() . PHP_EOL;
    
    // List all hosts
    $hosts = $unifiClient->hosts->list();
    print_r($hosts);
    
    // Get host by ID
    $hostId = 'your_host_id_here';
    $host = $unifiClient->hosts->get($hostId);
    print_r($host);
    
    // List all sites
    $sites = $unifiClient->sites->list();
    print_r($sites);
    
    // List all devices with optional filter parameters
    $devices = $unifiClient->devices->list(
        ['900A6F00301100000000074A6BA90000000007A3387E0000000063EC9853:123456789', '900A6F00301100000000074A6BA90000000007A3387E0000000063EC9853:987654321'], 
        '2024-07-15T07:01:13Z'
    );
    print_r($devices);

    echo 'Effective URI:   ' . $unifiClient->getEffectiveUri() . PHP_EOL;
    echo 'Transfer time:   ' . $unifiClient->getTransferTime() . ' seconds' . PHP_EOL;
    echo 'Response status: ' . $unifiClient->getResponseStatusCode() . PHP_EOL;
} catch (Exception $e) {
    echo "Error: " . $e->getMessage() . "\n";
}

Getter and Setter Methods

There are several getter and setter methods available to interact with the UniFi Cloud API client:

API Reference

List Hosts

API Route

GET /ea/hosts

Description

Retrieve a list of all hosts associated with the UI account making the API call.

Usage

$hosts = $unifiClient->hosts->list();

Example Response

[
  "data" => [
    [
      "hardwareId" => "eae0f123-0000-5111-b111-f833f56eade5",
      "id" => "900A6F00301100000000074A6BA90000000007A3387E0000000063EC9853:123456789",
      "ipAddress" => "192.168.220.114",
      "isBlocked" => false,
      "lastConnectionStateChange" => "2024-06-23T03:59:52Z",
      "latestBackupTime" => "2024-06-22T11:55:10Z",
      "owner" => true,
      "registrationTime" => "2024-04-17T07:27:14Z",
      "reportedState" => [...], // Replace [...] with actual data structure
      "type" => "console",
      "userData" => [...], // Replace [...] with actual data structure
    ]
  ],
  "httpStatusCode" => 200,
  "traceId" => "a7dc15e0eb4527142d7823515b15f87d"
]

Get Host by ID

API Route

GET /ea/hosts/{id}

Description

Retrieve detailed information about a specific host by ID.

Usage

$hostId = 'your_host_id_here';
$host = $unifiClient->hosts->get($hostId);

Example Response

[
  "data" => [
    "hardwareId" => "eae0f123-0000-5111-b111-f833f56eade5",
    "id" => "900A6F00301100000000074A6BA90000000007A3387E0000000063EC9853:123456789",
    "ipAddress" => "192.168.220.114",
    "isBlocked" => false,
    "lastConnectionStateChange" => "2024-06-23T03:59:52Z",
    "latestBackupTime" => "2024-06-22T11:55:10Z",
    "owner" => true,
    "registrationTime" => "2024-04-17T07:27:14Z",
    "reportedState" => [...], // Replace [...] with actual data structure
    "type" => "console",
    "userData" => [...], // Replace [...] with actual data structure
  ],
  "httpStatusCode" => 200,
  "traceId" => "a7dc15e0eb4527142d7823515b15f87d"
]

List Sites

API Route

GET /ea/sites

Description

List sites associated with the UI account making the API call.

Usage

$sites = $unifiClient->sites->list();

Example Response

[
  "data" => [
    [
      "hostId" => "900A6F00301100000000074A6BA90000000007A3387E0000000063EC9853:123456789",
      "isOwner" => true,
      "meta" => [
      "desc" => "Default",
      "gatewayMac" => "f4:e2:c6:c2:3f:13",
      "name" => "default",
      "timezone" => "Europe/Riga"
    ],
      "permission" => "admin",
      "siteId" => "661900ae6aec8f548d49fd54",
      "statistics" => [...], // Replace [...] with actual data structure
      "subscriptionEndTime" => "2024-06-27T13:09:46Z"
    ]
  ],
  "httpStatusCode" => 200,
  "traceId" => "a7dc15e0eb4527142d7823515b15f87d"
]

List Devices

API Route

GET /ea/devices

Description

List UniFi devices that are associated with the UI account making the API call, grouped by host.

Usage

$devices = $unifiClient->devices->list(
    ['900A6F00301100000000074A6BA90000000007A3387E0000000063EC9853:123456789', '900A6F00301100000000074A6BA90000000007A3387E0000000063EC9853:987654321'], 
    '2024-07-15T07:01:13Z'
);

Parameters

• hostIds[] (array, optional): List of host IDs.
• time (string, optional): Last processed timestamp of devices.

Example Response

[
  "data" => [
    [
      "devices" => [
        [
          "adoptionTime" => null,
          "firmwareStatus" => "upToDate",
          "id" => "F4E2C6C23F13",
          "ip" => "192.168.1.226",
          "isConsole" => true,
          "isManaged" => true,
          "mac" => "F4E2C6C23F13",
          "model" => "UDM SE",
          "name" => "unifi.yourdomain.com",
          "note" => null,
          "productLine" => "network",
          "shortname" => "UDMPROSE",
          "startupTime" => "2024-06-19T13:41:43Z",
          "status" => "online",
          "uidb" => [
            "guid" => "0fd8c390-a0e8-4cb2-b93a-7b3051c83c46",
            "id" => "e85485da-54c3-4906-8f19-3cef4116ff02",
            "images" => [
              "default" => "3008400039c483c496f4ad820242c447",
              "nopadding" => "67b553529d0e523ca9dd4826076c5f3f",
              "topology" => "8371ecdda1f00f1636a2eefadf0d7d47"
            ]
          ],
          "updateAvailable" => null,
          "version" => "4.0.6"
        ]
      ],
      "hostId" => "900A6F00301100000000074A6BA90000000007A3387E0000000063EC9853:123456789",
      "hostName" => "unifi.yourdomain.com",
      "updatedAt" => "2024-07-15T07:01:13Z"
    ]
  ],
  "httpStatusCode" => 200,
  "traceId" => "a7dc15e0eb4527142d7823515b15f87d"
]

Rate Limiting

The API rate limit is set to 100 requests per minute. If you exceed this limit, the server will respond with a 429 Too Many Requests status code. The client will throw an Exception if this happens.

Important note on general API support

When encountering issues with the official UniFi Cloud API using other libraries, cURL or Postman, please do not open an Issue here. Such Issues will be closed immediately. Please use the Discussions section instead.

Contribute

If you would like to contribute to this repository, please open an issue and include your code there or else create a pull request.

Credits

This class is based on the documentation provided by Ubiquiti for their UniFi Cloud API: https://developer.ui.com/unifi-api/

About Art of WiFi

Art of WiFi develops software and tools that enhance the capabilities of UniFi networks. From captive portals and reporting solutions to device search utilities, our goal is to make UniFi deployments more powerful and easier to manage.

If you're looking for a specific solution or just want to see what else we offer, feel free to explore our web site:

• https://www.artofwifi.net

Important Disclaimer

This PHP class is provided "as is" without any guarantees or warranties. Use at your own risk. The author is not responsible for any damage or losses of any kind caused by the use or misuse of this class.