Skip to main content

Common Use Cases

This section describes typical scenarios where partners can leverage the Utopi Partner API to deliver value through resident-facing apps and services.

1. Accessing real-time and recent environmental data​

Purpose: Provide up-to-date environmental metrics for comfort and air quality monitoring.

Relevant endpoints:

  • GET /spaces/{spaceuuid} - Get Space Overview with latest environmental metrics (temperature, humidity, CO₂)

Use case examples:

  • Displaying current temperature, humidity, or CO₂ levels to residents.
  • Triggering alerts based on environmental thresholds.

2. Monitoring utility consumption​

Purpose: Track utility usage for sustainability insights and gamification.

Relevant endpoints:

  • GET /spaces/{spaceuuid} - Get Space Overview with latest utility consumption (today/yesterday values)
  • GET /spaces/{spaceuuid}/aggregate/{metrictype}/{granularity} - Get aggregated metrics over time with daily, weekly, or monthly granularity for various metric types

Use case examples:

  • Resident dashboards showing electricity or water consumption.
  • Property management reports on energy efficiency.

Purpose: Understand long-term patterns in environmental and utility data.

Relevant endpoints:

  • GET /spaces/{spaceuuid}/aggregate/{metrictype}/{granularity} - Get aggregated metrics over time with daily, weekly, or monthly granularity for various metric types

Use case examples:

  • Generating reports for sustainability initiatives.
  • Identifying seasonal variations in utility use or environmental conditions.

4. Supporting cluster apartments​

Purpose: Correctly represent shared communal spaces and individual bedrooms in clusters.

Relevant endpoints:

  • GET /spaces - Get all Spaces with cluster information (clusterUuid and clusterName populated for cluster spaces)
  • GET /spaces/{spaceuuid} - Get Space Overview which returns cluster-wide consumption data for cluster spaces, or individual consumption for standalone spaces

Relevant details:

  • Cluster apartments are identified by populated clusterUuid and clusterName fields in the spaces endpoint.
  • For spaces belonging to a cluster, utility data appears under clusterConsumption (aggregated for the whole cluster).
  • For standalone spaces, individual consumption data appears under consumption.
  • Environmental metrics (temperature, humidity, CO₂) are always room-specific, regardless of cluster membership.

Use case examples:

  • Presenting combined utility data for clusters while maintaining individual environmental room data.
  • Facilitating accurate usage insights or gamification for shared accommodation.

5. Controlling device operation​

Purpose: Schedule and control smart device operations for energy management and user comfort.

Relevant endpoints:

  • GET /devices - Get all devices with their basic metadata and identifiers
  • POST /devices/{deviceuuid}/{command}/schedule - Schedule device commands (currently supports standby for Utopi Smart Panel Heaters)

Relevant details:

  • Device control is currently available for Utopi Smart Panel Heaters with the standby command.
  • Scheduling allows setting specific time periods using fromDateTime and toDateTime parameters in ISO 8601 format.
  • Each device has a unique deviceUuid that can be obtained from the devices list endpoint.

Use case examples:

  • Scheduling heater standby during off-peak hours to reduce energy consumption.