Space Management

Last Updated on : 2023-11-23 03:12:19download

A space defines the geographical location, area, and layout information of IoT scenes, and displays the topological relationship between various smart devices in a tree structure. You can add physical resources (mainly smart devices) to each node of the tree structure. For example, lights, air conditioners, and video security devices in rooms.


Flexibly scalable and universal space models across business semantics can cope with business forms of all industries and scenarios. Thus, you can achieve more efficient solutions in diversified scenarios. A space plays multiple roles in IoT application development, including but not limited to:

  • Map a physical space: For example, define a building.
  • Manage user permissions: After defining a space, you can respectively link the space with users and resources, and thus bridge the relationship between resources and users based on the space.
  • Manage physical resources: Under the space, you can add various types of resources, such as devices and mesh networks.

Structural features

The hierarchical structure constructed by the space has the following features:

  • A tree-like multi-level structure is presented.
  • Each space has only one root node.
  • Each node has only one parent node and can have multiple child nodes.
  • Resources can be added to each level of nodes.
  • Each resource can be added under multiple nodes.
  • Under the same space tree, a gateway and its sub-devices can enter different levels of space nodes.

Examples of application

Example 1: Space layout and device linkage of a gym

As a multifunction venue, a gym contains different levels of spaces like the gym hall, floors, and rooms for ball games. You can create the desired spaces in the space model, helping implement device linkage. For example, control lights and a basketball court scoreboard.

The following figure shows an example of a space structure. The gym is the root node, and the first floor (including the basketball court) and the second floor (including the table tennis room and badminton court) are child nodes.

Space Model of Gym 
Floor 2
Floor 1
Table Tennis Room 
Badminton Court 
Basketball Court
Light 1
Light 2
Video Security Device 
Entrance Barrier Gate

By creating the structure on top of the space model, you can:

  • Set the gym as the topmost layer of the entire space, which consists of two floors.
  • Specify the basketball court and its scoreboard on the first floor, as well as video security devices.
  • Specify the table tennis room and badminton court on the second floor, as well as the corresponding lights.
  • Utilize the barrier gate as an entry to access control of the gym, facilitating scene linkage of lights and the scoreboard.

Example 2: Digital space construction of smart apartment

As a popular business scenario, smart apartment can involve spaces in various dimensions, such as apartments, units, buildings, room numbers, and public areas. A resident needs permission to devices not only in his room, but also in the public space area. This way, implement the linkage between devices in the specified room and devices in the public area.

The following figure shows an example of a space structure. The apartment is the root node, and Building A, Unit 1, and Floor 1 (including rooms 101 and 102) are child nodes.

Space Model of Some Areas of Building A
Floor 1
Unit 1
Building A
Room 101 
Room 102 
Public Corridor
Device 1 (Entryway Light)
Device 3 (Corridor Light)
End User 

By creating the structure on top of the space model, you can:

  • Set up the five-level structure of apartment > building > unit > floor > room to represent the layout and logical relationship of the physical world.
  • Grant users permission to a specific room, such as Room 101.
  • Grant users permission to a specific device, such as Device 3.
  • Create desired device linkage rules in different spaces.

On top of this space model, you can further extend and iterate features. For example:

  • Access control systems: Add an access control system at the entrance of each building so that only authorized personnel can enter the building.
  • Face recognition: Upgrade conventional door locks to smart locks with face recognition, so residents can enter their room more safely and conveniently.
  • Smart home control: Connect smart home devices (such as lights and air conditioners) with the space model, so residents can control various devices using a specific mobile app or voice commands.
  • Energy management: Install an energy management system to monitor and control the energy usage in the rooms, helping save energy and reduce costs.
  • Video security: Install smart security cameras in buildings and public areas to make the entire smart apartment a safer place.
  • Social interaction: Provide a social platform for residents to exchange and share information with each other. Thus, the whole community becomes more interactive and friendly.

After more and more extended functionalities are in place, smart apartments provide a more convenient and comfortable living experience, while improving the safety and quality of life for residents.

API list

API name API endpoint
Delete Space DELETE:/v2.0/cloud/space/{space_id}
Query Resources in Space GET:/v2.0/cloud/space/{space_id}/resource
Create Space POST:/v2.0/cloud/space/creation
Query Space GET:/v2.0/cloud/space/{space_id}
Query Space List GET:/v2.0/cloud/space/child
Modify Space Information PUT:/v2.0/cloud/space/{space_id}
Query Parent-Child Relationship GET:/v2.0/cloud/space/relation


Item Limits
The number of devices under a single space node 100
The number of child nodes in a single space 100
The number of levels in a single space 10 levels


What are the differences between space, home, and asset?

The concepts of home and asset often appear in certain business scenarios of Tuya, and both are the upper-level business packaging of a space. As a more abstract model, a space only retains the most fundamental data of topologies and resource association. The space does not include the upper-level business data of assets and homes such as a room in a home.

  • If you want to get upper-level business data, see Asset Management and Home Management.

  • In order to apply the space model in the upper-level business, Tuya can also help you upgrade the underlying space into an upper-level asset or home. This way, you can seamlessly connect and use upper-layer business capabilities, such as OEM app.