Home

The Cumulocity Python API (c8y_api) module is a pure Python implementation of Cumulocity IoT's REST interface.

→ Getting started with the Cumulocity Python API

REST API Connector

The Cumulocity Python API (c8y_api module) provides a convenience wrapper around the standard Cumulocity REST API (see also the OpenAPI documentation).

The CumulocityRestApi class provides the fundamental wrapping around authentication and basic get, post, put, delete commands. The CumulocityApi class is your entrypoint into higher level funct ions, grouped by contexts like inventory, users, and measurements. Each of these contexts is documented in detail within the main-api-classes section.

The CumulocityDeviceRegistry class provides an additional entry point for devices, wrapping the entire bootstrap mechanism. See also the Device integration documentation at Cumulocity.

Application Helpers

The Cumulocity Python API (c8y_api.app module) is designed to be particularly useful for developing Cumulocity microservices. For this, the module provides two helper classes that take care of microservice specific authentication.

The SimpleCumulocityApp class should be used for single tenant microservices. It automatically reads the microservice's environment to determines the microservice access credentials.

The MultiTenantCumulocityApp class should be used for multi-tenant microservices which need to handle requests for arbitrary Cumulocity tenants. It reads the microservice's environment to determine the necessary bootstrap credentials and provides additional functions to dynamically obtain CumulocityApi instances for specific tenants.

Main API Classes

The Cumulocity Python API's main API classes provide access to various contexts within the Cumulocity REST API. Use it to read existing data or modify in bulk.

See also the Object model section for object creation and object-oriented access in general.

→ Inventory
→ DeviceInventory
→ Identity
→ Binaries
→ Measurements
→ Events
→ Alarms
→ Users
→ GlobalRoles
→ InventoryRoles
→ Subscriptions
→ Tokens
→ Operations
→ BulkOperations
→ Applications
→ TenantOptions
→ AuditRecords

Object Models

The Cumulocity Python API's object model provides object-oriented access to the Cumulocity REST API. Use it to create and modify single objects within the Database.

These objects can also be used directly within the Main API classes to modify data in bulk.

→ ManagedObject
→ Device
→ DeviceGroup
→ ExternalId
→ Binary
→ Measurement
→ Event
→ Alarm
→ Series
→ Subscription
→ Availability
→ Fragment
→ NamedObject
→ User
→ CurrentUser
→ TfaSettings
→ GlobalRole
→ Permission
→ ReadPermission
→ WritePermission
→ AnyPermission
→ Operation
→ BulkOperation
→ Application
→ ApplicationSetting
→ ApplicationSubscription
→ TenantOption
→ AuditRecord
→ Change

Measurement Additions

The Cumulocity Python API's measurements API (see also classes Measurements and Measurement) includes the following additions to allow easy creation of standard measurement values including units.

Effectively, each of the value classes represent a value fragment, e.g. Celsius:

{"unit": "°C", "value": 22.8}

These values can easily be combined, e.g. when constructing a measurement:

m = Measurement(
    type='cx_LevelMeasurement', source=device_id, time='now',
    cx_Levels={
        'oil': Liters(8.4),
        'gas': Liters(223.18),
        'h2o': Liters(1.2),
        'bat': Percentage(85)
    })

→ Units
→ Celsius
→ Centimeters
→ Count
→ CubicMeters
→ Grams
→ Kelvin
→ Kilograms
→ Liters
→ Meters
→ Percentage
→ Value

Auxiliary Tools

The Cumulocity Python API's standard packages (see Main API classes and Model classes) represent what the Cumulocity REST API provides. The c8y_tk (for "Cumulocity toolkit") module provides additional auxiliary tools that cover useful functionality beyond the REST API but applicable in many projects.

The c8y_tk.notification2 module provides listener implementations that allow straightforward development of Notification 2.0 applications without additional overhead.

→ Listener
→ QueueListener
→ AsyncListener
→ AsyncQueueListener

The c8y_tk.analytics module provides helper functions that allow parallel query processing to maximise performance when dealing with large datasets as well as easy transformation of a Cumulocity Series to Pandas' data frames and series as well as NumPy arrays.

→ ParallelExecutor
→ to_data_frame
→ to_numpy
→ to_series

The c8y_tk.app module provides auxiliary tools for implementing both interactive and micro service applications.

→ CumulocityApp
→ SubscriptionListener