API unifi_video.api

class unifi_video.api.UnifiVideoAPI(api_key=None, username=None, password=None, addr=u'localhost', port=7080, schema=u'http', verify_cert=True, check_ufv_version=True, utc_offset_sec=None)[source]

Bases: object

Encapsulates a single UniFi Video server.

Parameters:
  • api_key (str) – UniFi Video API key
  • username (str) – UniFi Video account username
  • password (str) – UniFi Video account pasword
  • addr (str) – UniFi Video host address
  • port (int) – UniFi Video host port
  • schema (str) – Protocol schema to use. Valid values: http, https
  • verify_cert (bool) – Whether to verify UniFi Video’s TLS cert when connecting over HTTPS
  • check_ufv_version (bool) – Set to False to use with untested UniFi Video versions
  • utc_offset_sec (int or NoneType) – UniFi Video server’s UTC offset in seconds.

Note

At minimum, you have to

  • provide either an API key or a username:password pair
  • set the host address and port to wherever your UniFi Video is listening at
Variables:
  • _data (dict) – UniFi Video “bootstrap” JSON as a dict
  • base_url (str) – API base URL
  • api_key (str or NoneType) – API key (from input params)
  • username (str or NoneType) – Username (from input params)
  • password (str or NoneType) – Password (from input params)
  • name (str or NoneType) – UniFi Video server name
  • version (str or NoneType) – UniFi Video version
  • jsession_av (str or NoneType) – UniFi Video session ID
  • cameras (UnifiVideoCollection) – Collection of UnifiVideoCamera objects. Includes all cameras that the associated UniFi Video instance is aware of
  • active_cameras (UnifiVideoCollection) – Like UnifiVideoAPI.cameras but only includes cameras that are both connected and managed by the UniFi Video instance.
  • managed_cameras (UnifiVideoCollection) – Includes all cameras that are managed by the UniFi Video instance, whether they’re online or not.
  • recordings (UnifiVideoCollection) – Collection of UnifiVideoRecording objects
delete(url, data=None, raw=False)[source]

Send DELETE request.

Thin wrapper around post(); the same parameter/return semantics apply here.

delete_all_recordings()[source]

Delete all existing recordings

get(url, raw=False, url_params={})[source]

Send GET request.

Parameters:
  • url (str) – API endpoint (relative to the API base URL)
  • raw (str or bool, optional) – Set str filename if you want to save the response to a file. Set to True if you want the to return raw response data.
  • url_params (dict, optional) – URL parameters as a dict. Gets turned into query string and appended to url
Returns:

Response JSON (as dict) when Content-Type response header is application/json

True if raw is str (filename) and a file was successfully written to

Raw response body (as bytes) if the raw input param is of type bool

False on HTTP 4xx - 5xx
Return type:

NoneType, bool, dict, bytes
get_camera(search_term, managed_only=False)[source]

Get camera by its ObjectID, name or overlay text

Parameters:
  • search_term (str) – String to test against name, _id, and overlay_text.
  • managed_only (bool) – Whether to search unmanaged cameras as well.
Returns:

UnifiVideoCamera or NoneType depending on whether or not search_term was matched to a camera.

Tip

Do not attempt to find an unmanaged camera by it’s overlay text; UniFi Video provides limited detail for unmanaged cameras.

get_recordings(rec_type=u'all', camera=None, start_time=None, end_time=None, limit=0, order=u'desc', req_each=False)[source]

Fetch recording listing

Parameters:
  • rec_type (str, optional) – Type of recordings to fetch: all, motion or fulltime
  • camera (UnifiVideoCamera or str or list of UnifiVideoCamera or list of str, optional) – Camera or cameras whose recordings to fetch
  • start_time (datetime or str or int, optional) – Recording start time. (See dt_resolvable_to_ms().)
  • end_time (datetime or str or int, optional) – Recording end time. (See dt_resolvable_to_ms().)
  • order (str, optional) – Sort order: desc or asc. Recordings are sorted by their start time.
  • limit (int, optional) – Limit the number of recordings
  • req_each (bool, optional) – Whether to save bandwidth on the initial request and to fetch each recordings’ details individually or to ask for each recordings’ details to be included in the one and only initial request. True can potentially save you in total bytes transferred but will cost you in the number of HTTP requests made.
Returns:

Iterable[UnifiVideoRecording]

Note

You can use naive datetime objects or strings when you want to mark time in the UniFi Server’s local time. Otherwise, use Unix timestamps (int, in seconds) or timezone aware datetime objects.

static params_to_query_str(params_dict)[source]

Build query string from dict of URL parameters

Parameters:params_dict (dict) – URL parameters
Returns:Query string
Return type:str
post(url, data=None, raw=False, _method=None)[source]

Send POST request.

Parameters:
  • url (str) – API endpoint (relative to the API base URL)
  • data (dict or NoneType) – Request body
  • raw (str or bool) – Filename (str) if you want the response saved to a file, True (bool) if you want the response body as return value
Returns:

See get().
put(url, data=None, raw=False)[source]

Send PUT request.

Thin wrapper around post(); the same parameter/return semantics apply here.

refresh_cameras()[source]

GET cameras from the server and update camera collections

Touches UnifiVideoAPI.cameras, UnifiVideoAPI.active_cameras, and UnifiVideoAPI.managed_cameras

refresh_recordings(limit=300)[source]

GET recordings from the server and update self.recordings.

Parameters:limit (int) – Limit the number of recording items to fetch (0 for no limit).