Skip to main content

A Python library to communicate with Carson Living Residences (

Project description

Python Carson Living is a library written in Python that exposes the devices as Python objects.

Please note, that Carson does not provide an official API documentation, therefore this project is solely based on reverse engineering.

Getting started


Carson Living Python should work against Python 2.x >= 2.7 and Python 3.x >= 3.5.

# Installing from PyPi
$ pip install carson_living

# Installing latest development
$ pip install \

Initialize a Carson API object

# Initializing an API object
carson = Carson("", 'your password')
# >> Martin
# >> ey...

You are also able to pass a valid JWT token during initialization which would prevent a login action as long as the token is valid:

# Initializing an API object with a valid token
carson = Carson("", 'your password', 'ey....')
# >> Martin

Since Carson Living uses JWT token with very long validity, it is recommended to save the active token via carson.token, whenever one needs to reinitialize the API later on. The API library is robust to handle expired JWT tokens (and 401 handling), so no need to check before.

Carson entities

The library currently supports the following entities and actions.

  • User (carson.user): read

  • Building (carson.buildings): read

  • Doors (building.doors): read, open

  • Cameras (building.cameras): read, images, video

Door entities

Doors can be “buzzed” open via

# Open all Unit Doors of Main Building
for door in carson.first_building.doors:
    if door.is_unit_door:
        print('Opening Unit Door {}'.format(

Camera entities

Eagle Eye cameras can produce live images and videos but also allow access to passed recordings (see API). The API can download the image and video directly into a provided file object or just pass a generated url with an eagle_eye auth key A=c000..... Please note, that the url can only be accessed as long as the auth_key is valid. Therefore it may make sense to force the eagle eye api to refresh the auth key before generating a image or video url.

  • Directly save a live image:

for camera in building.cameras:
    with open('image_{}.jpeg'.format(camera.entity_id), 'wb') as file:
  • Directly save a live video of 10s:

for camera in building.cameras:
    with open('video_{}.flv'.format(camera.entity_id), 'wb') as file:
        camera.get_video(file, timedelta(seconds=10))
  • Directly download a image from a timestamp:

three_hours_ago = datetime.utcnow() - timedelta(hours=3)
# download all images from 3 hours ago
for camera in building.cameras:
    with open('image_{}.jpeg'.format(camera.entity_id), 'wb') as file:
        camera.get_image(file, three_hours_ago)
  • Directly download a recorded video from a timestamp:

three_days_ago = datetime.utcnow() - timedelta(days=3)
# download all videos from 3 days ago
for cam in building.cameras:
    with open('video_{}.flv'.format(cam.entity_id), 'wb') as file:
        cam.get_video(file, timedelta(seconds=5), three_days_ago)
  • The Carson API is also able to produce authenticated URLs that can be handled externally. Please not, that the auth_key has a limited lifetime. Therefore it makes sense to update the auth_key manually before retrieving predefined URLs. Note, the Eagle Eye API in Carson is associated with a building, so it is sufficient to update it once for all cameras in the same building. The function signature of the the _url function is identical to the previous ones (minus the file object).

# Update Session Auth Key of Eagle Eye once in a while if using
# generated authenticated URLs.
# Note, this is not needed for get_image() or get_video()
for cam in building.cameras:
    img_url = cam.get_image_url(three_days_ago)
    # >>
    response = requests.get(img_url)
    with open('image_{}_with_url.jpeg'.format(cam.entity_id), 'wb') as file:
    # do only 1 cam.

Use cam.get_video_url() the same way.

CLI Tool

Checkout ./scripts/ for further API implementation examples.

Development Notes

Request Headers

The library currently works with the following base headers:

User-Agent: Carson/1.0.171 (; build:245; iOS 13.1.0) Alamofire/1.0.171
X-Device-Type: ios
X-App-Version: 1.0.171(245)

Code Documentation

The code follow the Google Python Styleguide for docstring.

Git Branching Strategy

This project uses gitflow as a git branching model.

Open Items

The following is not supported by the API yet and remains TODO.

  • Expose visitor functionality (/visitors)

  • Expose thread / messaging functionality (/threads)

  • Expose delivery functionality (/deliveries)

  • Expose dashboard functionality (/dashboard)

  • Expose service functionality (/service)

  • Integrate Twilio (twilio/access-token/)

  • Expand and extract EagleEye API (into separate project?).


python-carson-living is released under the Apache License Version 2.0. See the LICENSE file for more details.

Credits && Thanks

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

carson_living-0.0.5.tar.gz (18.0 kB view hashes)

Uploaded source

Built Distributions

carson_living-0.0.5-py3-none-any.whl (23.3 kB view hashes)

Uploaded py3

carson_living-0.0.5-py2-none-any.whl (23.3 kB view hashes)

Uploaded py2

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page