Skip to content

Field naming

The server's JSON uses legacy, inconsistent key names (sublocation_uid, location_uid, trackable_object_uid, mac). The SDK exposes one canonical name per concept and maps to the wire key for you, per endpoint. You always use the SDK name — in method parameters and on returned model fields alike.

Wire ↔ SDK mapping

SDK name Wire key(s) Notes
area_uid sublocation_uid, sl_uid An area is the server's "sublocation".
site_uid location_uid A site is the server's "location".
tag_uid / tag_uids trackable_uid, trackable_object_uid, dev_id, obj_uid A tag is the server's "trackable object". A list of tag uids is sent as the Rails array param track_uid[]=.
mac_address mac Bare 12-hex MAC on nodes, tags, and badges.

The same rename applies at the resource level: client.tags wraps the server's trackable_objects resource.

Live streaming frames follow the identical mapping — see Streaming for the per-message-type surface.

Passing wire keys explicitly

Models are populated by name or alias, so an explicitly-passed wire key is still accepted. On create/update, an explicit wire key wins over the canonical alias if you somehow pass both:

# Both are accepted; the SDK sends the server's `location_uid` either way.
client.areas.create(name="Bay 3", site_uid=site.uid)
client.areas.create(name="Bay 3", location_uid=site.uid)  # explicit wire key

Prefer the canonical name — the wire-key form exists only for forward-compat and one-off escape hatches.

The .raw escape hatch

Every model preserves the untouched server payload on .raw. Use it to reach keys the typed surface doesn't rename or expose:

alarm = client.alarms.list_active()[0]
alarm.tag_uid          # canonical field
alarm.raw["trackable_object_uid"]  # the original wire key, still there

Deliberately not renamed

A few identifiers are the same on the wire and the SDK surface — don't expect a mapping for these:

  • win_uid — identical on the wire and the method surface.
  • mac_address on Node and associations — already the server's field name there (only the streaming/OTA mac frames are renamed).
  • TDOA Schedule server-side blobs — inspect them via Schedule.raw.