API Basics
The following table defines important terms for the Tandem Data API:
Term | Definition |
---|---|
facility | Represents the “Twin” of the given building. It can be composed of several “Models”, and the aggregate of those models is the Facility.
In the API, “twin” is synonamous with “facility”.
|
model | Model refers to a source model that was imported into Tandem to make a “facility”. There are usually multiple models per facility. These models correpsond to a source model from a BIM application, such as Revit.
The Tandem Data API will reference them through a URN and most calls to the API are model-specific. For instance, when searching for a named property in a facility composed of 3 models, it is necessary to make 3 separate calls to
/scan with the URN of each model. |
default model | Every facility has a “default model” created automatically. This is used to store “logical” elements that don’t have a physical presence in the building, such as the timeseries data for an IoT device.
The URN for the default model is always the same as the URN for the facility, but with a dtm: prefix instead of dtt:.
|
twinURN | The identifier for a particular twin (aka Facility). It looks something like: urn:adsk.dtt:d6eZt_XtRzqUHT93-vNZxw, with “dtt” prefix.
|
modelURN | The identifier for a particular model within a twin. It looks something like: urn:adsk.dtm:k6ZZZkIYQ9ixvxFDVBNoTg, with “dtm” prefix.
|
elementKey | The unique identifier for an element in the Tandem database. Some REST endpoints will return elementKeys and some will take them as input.
There are two types of keys (short and long, which have extra information embedded in them): shortKeys look something like kzxKBpO4EdOA-ADAT478MgAAAB4 and longKeys looks something like AAAAAN6fOPMFaEovj71TVYMUgi4ACYEZ. For the most part, they are inter-changeable, but see sample code for cases where they must be converted.
|
parameter | A property attached to an element (e.g. Wall, Door, Space). Some parameters are read-only and come from the original source model. For example, the Door Width comes from the source Revit model and cannot be changed.
The Tandem user can also add custom parameters. These are then added to a Facility Template and mapped to a Classification. When an element is Classified, it gets those parameters asssigned to it.
Parameters are in a “global” library and can be used with any Facility by using them in a Facility Template and then applying that Template to a given facility.
|
property | Synonymous with “Parameter”
|
qualProp | A “qualified property” is the unambiguous name for a Parameter in a given model. Because parameter definitions are shared across multiple facilities and multiple models, the qualified property is used in API calls because it is unique to a given model. It will looks something like z:A5c or n:v
|
classification | Tandem allows for flexible, user-defined classification systems. They are used to identify the type of element (e.g. Door, AirConditioner, etc), and to map user-defined parameters to the element.
Classification systems are in the “global” library and can be used with any Facility. This is done by using them in a Facility Template and then applying that Template to a given facility.
|
facility template | Maps parameters to a given classification hierarchy. When a Facility Template is applied to a particular Facilty, parameter definitions with unique identifiers are created within that Facility database.
|
stream | A stream is a logical element, stored in the default model, that represents the timeseries data from an IoT device. Streams have a generic endpoint where you can pass in the elementKey of the particular stream, or they can also publish an “ingestionURL” that self-identifies the stream and provides authorization in the link itself.
|
ingestionURL | A self-contained endpoint that can be used to pipe data in from a specific IoT sensor to a stream.
|