Skip to main content

Space Mapping

When integrating with the Utopi Partner API, it's important to understand how to reliably identify and map spaces within your system. This guide explains the available identifiers and provides best practices for maintaining accurate space mappings over time.

Identifiers​

The API returns multiple identifiers per space:

  • spaceUuid (GUID) – Globally unique, immutable. Use this as your primary key.
  • spaceName (string) – Human-readable label ("A1.1", "1.2B"). Editable by site admins, not standardised across sites. Use for display only.
  • buildingUuid (GUID) – Immutable building identifier.
  • floorNumber (integer) – Floor location. Stable but theoretically mutable.
  • clusterUuid (GUID) – Groups spaces within a cluster apartment. null for standalone units.
  • clusterName (string) – Human-readable cluster label. Same editability concerns as spaceName.

Primary key: spaceUuid​

Always key off spaceUuid. It's unique across all Utopi sites, survives reconfigurations and renames, and provides a stable reference for long-term data tracking.

spaceName is unreliable for matching—naming conventions vary by site, admins can change names at any time, and uniqueness isn't guaranteed.

Initial matching​

When first mapping Utopi spaces to existing records, use the Get all Spaces endpoint to retrieve the complete list of spaces for your site. You can then manually match these against your internal records using spaceName and floorNumberas contextual hints.

Once matched, persist the spaceUuid immediately to avoid repeated fuzzy lookups. Flag ambiguous matches (multiple candidates or zero) for manual resolution with our support team.

Clusters​

Cluster apartments group multiple spaces (bedrooms + shared LKD) under a common clusterUuid. Each space retains its own spaceUuid.

Store all spaceUuid values individually; use clusterUuid to understand grouping. Decide whether to aggregate metrics per bedroom or per cluster based on your requirements.

Support and Questions​

If you have questions about space identification, mapping strategies, or need assistance with data reconciliation:

When contacting support, please include:

  • The site(s) you're working with
  • Example spaces you're trying to map
  • Your current matching approach
  • Any specific edge cases you've encountered

See: Onboarding Process for general onboarding guidance.