API Documentation

Introduction

To expand access to the product infrastructure and data, Clockworks Analytics has implemented a library of Representational State Transfer (REST) web services. The Application Programming Interface (API) to these web services implements Hypertext Transfer Protocol (HTTP) GET and POST requests to retrieve information from the database. The responses to those requests are returned as a JavaScript Object Notation (JSON) string. Data is presented as Uniform Resource Identifiers, commonly known as Resources, representing a logical object with a type, associated data and properties, and can present relationships to other resources through Uniform Resource Locators (URLs).

API Initialization
To access the API, the following pieces of information are required: Uniform Resource Locator (URL) endpoint; and, Unique Subscription Key. The URL and Subscription Key will be provided by Clockworks Analytics once the API subscriber is registered, and need to be included as part of the HTTP header.
Header Name	Header Value
Accept	application/vnd.api+json
Ocp-Apim-Subscription-Key	{Subscription Key}
Content-Type	application/json
ApiVersion	{API Version}
ApiDocVersion	{API Doc Version}

The API version number is included as part of the header to maintain backward compatibility.

In the future, the HTTP header will be extended to included other API-wide settings such as the ability to optionally include the relationships information within the JSON responses.

HTTP Verb Usage

HTTP verbs can be used differently from one REST API to the next. We use our HTTP verbs the following way:

GET - simple retrievals
POST - more complex retrievals
PUT - creating entities/records
PATCH - updating entities/records
OPTIONS - documentation in HTML describing usage

Resources

The REST Application Programming Interface (API) is grouped together based on the resources, classes, types and data defined and used within the product.

Note:

Large data requests are returned in pages consisting of 1,000 data elements. If the requested data spans multiple pages, a "next" property will be included in the "links" object of the returned JSON string. Specific pages can be requested by passing the page[number] parameter as part of the request.
- For example, "https://{URL}/core-base/clients/1?page[number]=3".
Resources property values are stored and presented as invariant unless otherwise noted in the description.
To return a specific fields in the response, a consumer may use the value of fields parameter in a comma-separated list that refers to the names of the fields to be returned. This can be chained for resources based on a resource.
- For example, https://{URL}/core-base/buildings/13?fields[Buildings]=BuildingName,Address
- For example, https://{URL}/core-base//buildings/13/equipment?fields[Buildings]=BuildingName,Address&fields[Equipment]=EquipmentName,Equipment,IsActive

Clients
A Client is defined as a subscribing customer. An API subscriber may have many peer Clients. The Clients view is the default when accessing the API root URL or in the case of any misspelled or invalid URI/URL paths.
Request	Returns
GET /clients	All Clients.
GET /clients/{id}	A Client by ID.
GET /clients/{id}/buildings	All Buildings related to the Client.
GET /clients/{id}/buildingTypes	All Building Types related to the Client.
GET /clients/{id}/analyses	All Analyses available to a specified client
GET /clients/{id}/datasources	All Data Sources related to the Client.
GET /clients/{id}/clientsProvidedFor	All Clients provided with services related to the Client.
OPTIONS /clients	This Help table.
Response Key	Data Type	Allow Nulls?	Description
id	Integer	No	Client ID.
ClientName	String(100)	No	Client name.
ClientAddress	String(250)	Yes	Client address street.
ClientCity	String(100)	Yes	Client address city.
ClientStateName	String(100)	Yes	Client address state, province, or equivalent.
ClientZip	String(10)	Yes	Client address zip code, or equivalent.
ClientPhone	String(10)	Yes	Client phone number (U.S. only. Numbers only).
IsActive	boolean	Yes	Active status
ReportTheme	String(50)	Yes	Clockworks Analytics or Schneider Electric
OrganizationTheme	String(50)	Yes	Organization theme
CountryName	String(50)	Yes	Country name
ParentOrganization	String(100)	Yes	Parent unit

GET https://{URL}/core-base/clients/1

{
  "metadata": {
    "ApiVersion": "1.0"
  },
  "data": [
    {
      "type": "Clients",
      "id": 1,
      "attributes": {
        "ClientName": "Company",
        "ClientAddress": "66 Union Square",
        "ClientCity": "Somerville",
        "ClientStateName": "MA",
        "ClientZip": "02143",
        "ClientPhone": "(857) 598-6439",
        "IsActive": true,
        "ReportTheme": "Clockworks Analytics",
        "OrganizationTheme": "Clockworks Analytics",
        "CountryName": "United States",
        "ParentOrganization": ""
      },
      "relationships": {
        "Buildings": {
          "links": {
            "self": "https://{URL}/core-base/Clients/1/Buildings/",
            "related": "https://{URL}/core-base/Buildings/"
          }
        },
        "BuildingTypes": {
          "links": {
            "self": "https://{URL}/core-base/Clients/1/BuildingTypes/",
            "related": "https://{URL}/core-base/BuildingTypes/"
          }
        },
		"DataSources": {
          "links": {
            "self": "https://{URL}/Clients/1/datasources/"
          }
        },
		"ClientsProvidedFor": {
		  "links": {
			"self": "https://{URL}/core-base/Clients/1/ClientsProvidedFor/"
		  }
		}
      },
      "links": {
        "self": "https://{URL}/core-base/Clients/1/"
      }
    }
  ],
  "links": {
    "self": "https://{URL}/core-base/clients/1/",
    "first": "https://{URL}/core-base/clients/1?page[number]=0"
  }
}

Buildings
A Building is defined as a logical structural unit which may be a single physical structure or multiple structures grouped by a particular criteria. To return a specific fields in the response, a consumer may use the value of fields parameter in a comma-separated list that refers to the names of the fields to be returned.
Request	Returns
GET /buildings	All Buildings.
GET /buildings/{id}	A Building by ID.
GET /buildings/{id}/equipment	All Equipment related to the Building.
GET /buildings/{id}/equipmentclasses	All Equipment Class related to the Building.
GET /buildings/{id}/equipment?classID={id}	Equipment of the given Equipment Class related to the Building.
GET /buildings/{id}/equipmenttypes	All Equipment Types related to the Building.
GET /buildings/{id}/equipment?typeID={id}	Equipment of the given Equipment Type related to the Building.
GET /buildings/{id}/taskrecords	All Tasks related to the Building.
GET /buildings/{id}/buildingbuildingvariables	Values of all Building Variables assigned to the Building.
GET /buildings/{id}/equipmentpoints	All Equipment Points related to the building.
GET /buildings/{id}/points	All Points related to the Building.
OPTIONS /buildings	This Help table.
Response Key	Data Type	Allow Nulls?	Description
id	Integer	No	Building ID.
BuildingName	String(100)	No	Building name.
BuildingTypeID	Integer	No	Building Type ID.
CID	Integer	No	ID of the Client that this Building is assigned to.
Address	String(250)	No	Building address.
BuildingClassDescription	String(1000)	Yes	Description of the categorized Building classification.
BuildingClassID	Integer	No	ID of the categorized Building classification.
BuildingClassName	String(50)	No	Name of the categorized Building classification.
BuildingOwnership	String(50)	Yes	Type of ownership the Buildings is under.
BuildingTypeDescription	String(1000)	No	Description of the specific type under the Building classification.
BuildingTypeName	String(100)	No	Name of the specific type under the Building classification.
BuildingShape	String(50)	Yes	Shape of the Building.
City	String(100)	No	Building City.
ClientName	String(100)	No	Client Name.
Computers	Integer	No	Estimated number of computers in the Building, in range 0-10,000.
CountryName	String(50)	Yes	Country of the Building.
CountryAlpha2Code	String(2)	No	Unique ISO Alpha 2 country code.
DateCreated	ISO Date String	No	Date, in UTC, the Building was created in the system.
DateModified	ISO Date String	No	Date, in UTC, the Building was last modified in the system.
Description	String(1000)	Yes	Description of the Building.
EnvelopeGlassPercentage	Integer	No	Envelope glass percentage of the Building, in range 0-100.
Floors	Integer	Yes	Number of floors in the Building, in range 1-9999.
IsActive	Bit	No	True (1) if the Building is actively receiving data and running diagnostics in the system, False (0) otherwise.
IsVisible	Bit	No	True (1) if the Building is visible to non-administrative users in the system, False (0) otherwise.
Latitude	Decimal(13,10)	Yes	Latitude of the Building.
LCID	Integer	No	Locale identifier for the Building. A locale is a set of information related to the entities language and culture. The locale determines how dates, times, currencies, and numbers are formatted, how items are alphabetically sorted, and how strings are compared.
Location	String(250)	Yes	Additional location information about the Building.
Longitude	Decimal(13,10)	Yes	Longitude of the Building.
MainCoolingSystem	String(50)	Yes	Type of the main cooling system.
MainHeatingSystem	String(50)	Yes	Type of the main heating system.
Occupants	Integer	Yes	Estimated number of Building occupants, in range 1-99,999.
OperatingHours	Integer	No	Building operating hours, in range 0-168.
Phone	String(10)	Yes	Building phone number (U.S. only).
RoofConstruction	String(50)	Yes	Type of roof construction.
SASLink	String(100)	Yes	Space Accounting Software link URL.
SASReferenceID	String(50)	Yes	Space Accounting Software reference ID.
StateID	Integer	Yes	The State ID.
StateName	String(100)	Yes	Building state, province, or equivalent.
Area	Integer	No	Area of the Building, in range 0-9,999,999,999.
TimeZone	String(50)	No	Building time zone.
TimeZoneDisplayName	String(xx)	Yes	The time zone display name.
UnitSystem	Bit	No	True (1) if the Building data is measured in SI units, False (0) if is measured in IP units.
WebsiteLink	String(100)	Yes	Building specific website link URL.
WeatherFileDisplayName	String(150)	Yes	Yes, The weather file display name.
WeatherFileGFID	Integer	Yes	The building Weather File ID.
YearBuilt	Integer	Yes	4-digit year the Building was built.
Zip	String(10)	Yes	Zip code, or equivalent of the Building.

GET https://{URL}/core-base/buildings/13

GET https://{URL}/core-base/buildings/13?fields[Buildings]=BuildingName,Address

GET https://{URL}/core-base//buildings/13/equipment?fields[Buildings]=BuildingName,Address&fields[Equipment]=EquipmentName,Equipment,IsActive

{
  "metadata": {
    "ApiVersion": "1.0"
  },
  "data": [
    {
      "type": "Buildings",
      "id": 13,
      "attributes": {
        "BuildingName": "Company Headquarters",
        "BuildingTypeID": 1,
        "CID": 1
      },
      "relationships": {
        "Equipment": {
          "links": {
            "self": "https://{URL}/core-base/Buildings/13/Equipment/",
            "related": "https://{URL}/core-base/Equipment/"
          }
        },
        "EquipmentTypes": {
          "links": {
            "self": "https://{URL}/core-base/Buildings/13/EquipmentTypes/",
            "related": "https://{URL}/core-base/EquipmentTypes/"
          }
        },
        "EquipmentClasses": {
          "links": {
            "self": "https://{URL}/core-base/Buildings/13/EquipmentClasses/",
            "related": "https://{URL}/core-base/EquipmentClasses/"
          }
        },
        "TaskRecords": {
          "links": {
            "self": "https://{URL}/core-base/Buildings/13/TaskRecords/",
            "related": "https://{URL}/core-base/TaskRecords/"
          }
        },
		"BuildingBuildingVariables": {
          "links": {
            "self": "https://{URL}/core-base/Buildings/13/BuildingBuildingVariables/"
          }
        },
        "Points": {
          "links": {
            "self": "https://{URL}/core-base/Buildings/13/Points/",
            "related": "https://{URL}/core-base/Points/"
          }
        }
      },
      "links": {
        "self": "https://{URL}/core-base/Buildings/13/"
      }
    }
  ],
  "links": {
    "self": "https://{URL}/core-base/buildings/13/",
    "first": "https://{URL}/core-base/buildings/13?page[number]=0"
  }
}

Building Types
Building Types are sub-classes of Building Classes, and are used to more accurately classify Buildings (e.g., Hospital→ Inpatient Hospital, Laboratory→Life Sciences Laboratory, etc.). If Building Types are requested for a Client (e.g., GET /clients/{id}/buildingtypes), only Building Types of Buildings for which the current API user is authorized to access will be returned.
Request	Returns
GET /buildingTypes	All Building Types.
GET /buildingTypes/{id}	A Building Type by ID.
OPTIONS /buildingTypes	This Help table.
Response Key	Data Type	Allow Nulls?	Description
id	Integer	No	Building Type ID.
BuildingTypeName	String(100)	No	Building Type name.
BuildingTypeDescription	String(1000)	No	Building Type description.

GET https://{URL}/core-base/buildingtypes/15

{
  "metadata": {
    "ApiVersion": "1.0"
  },
  "data": [
    {
      "type": "BuildingTypes",
      "id": 15,
      "attributes": {
        "BuildingTypeName": "Academic Building",
        "BuildingTypeDescription": "Main auditorium"
      },
      "relationships": {},
      "links": {
        "self": "https://{URL}/BuildingTypes/15/"
      }
    }
  ],
  "links": {
    "self": "https://{URL}/buildingtypes/15/",
    "first": "https://{URL}/buildingtypes/15?page[number]=0"
  }
}

Building Variables
Building Variables describe Building data points, such as Electricity Costs, along with related Engineering Units and default values.
Request	Returns
GET /buildingvariables	All Building Variables.
GET /buildingvariables/{id}	A Building Variable by ID.
OPTIONS /buildingvariables	This Help table.
Response Key	Data Type	Allow Nulls?	Description
id	Integer	No	Building Variable ID.
BuildingVariableDescription	String(100)	No	Building Variable description.
BuildingVariableDisplayName	String(1000)	No	Building Variable display name.
BuildingVariableName	String(1000)	No	Building Variable name.
IPDefaultValue	Integer	No	IP Engineering Unit default value.
IPEngUnitID	Integer	No	IP Engineering Unit ID.
IPEngUnits	String(50)	No	IP Engineering Unit.
SIDefaultValue	Integer	No	SI Engineering Unit default value.
SIEngUnitID	Integer	No	SI Engineering Unit ID.
SIEngUnits	String(50)	No	SI Engineering Unit.

https://{URL}/buildingvariables/15

{
  "metadata": {
    "ApiVersion": "1.0"
  },
  "data": [
    {
      "type": "BuildingVariables",
      "id": 15,
      "attributes": {
        "BuildingVariableDescription": "Hour of the day that building or zone stops being occupiable, represented in military time (for example, 6pm = 18).",
        "BuildingVariableDisplayName": "OccupiedEndHour",
        "BuildingVariableName": "OccupiedEndHour",
        "IPDefaultValue": "24",
        "IPEngUnitID": 27,
        "IPEngUnits": "non-dimensional",
        "SIDefaultValue": "24",
        "SIEngUnitID": 27,
        "SIEngUnits": "non-dimensional"
      },
      "relationships": {},
      "links": {
        "self": "https://{URL}/core-base/BuildingVariables/15"
      }
    }
  ],
  "links": {
    "self": "https://{URL}/core-base/buildingvariables/15",
    "first": "https://{URL}/core-base/buildingvariables/15?page[number]=0"
  }
}

Data Sources
Data Sources describe the source of Equipment data points. Examples are the physical location of the Equipment in a particular Building, and the system controls that integrate with the piece of Equipment.
Request	Returns
GET /clients/{id}/datasources	All Data Sources defined for the Client.
GET /datasources/{id}/points	All Points defined for the DataSources.
OPTIONS /datasources	This Help table.
Response Key	Data Type	Allow Nulls?	Description
id	Integer	No	Datasource ID.
BMSInfoID	Integer	Yes	BMS Information ID.
BMSInfoName	String(100)	No	BMS Information name.
CID	Integer	No	Client ID.
DataSourceName	String(100)	No	Data Source name.
Description	String(1000)	Yes	Data Source description.
DTSID	Integer	No	Data Transfer Service ID.
DTSName	String(250)	No	Data Transfer Service name.
Endpoint	String(512)	Yes	The BMS info endpoint.
ExtraInfo	String(1000)	Yes	Extra info about the BMS.
IncludeInHealthEmails	Boolean	No	Data Source included in automatic health email notifications.
Installer	String(100)	Yes	The Data Source installer name or info.
IPList	String(500)	Yes	IP List.
IsActive	Boolean	No	Is the Data Source active?
IsRealTime	Boolean	No	Is the Data Source is updated in real time. If it's false, it means the data source is updated via csv at the end of the day.
IsIntegrated	Boolean	No	Is the Data Source integrated?
ReferenceID	String(100)	No	Data Source Reference ID.
TimeOffset	Integer	No	This value is a corrective hourly offset integer that can be negative. Used to adjust the recorded timestamp on incoming data if the data source is inaccurate in comparison to it's location and timezone. Default 0.
VendorProductID	Integer	No	Vendor Product ID.
VendorProductRetrievalMethodID	Integer	No	Vendor Product Retrieval Method ID.

https://{URL}/clients/{id}/datasources
https://{URL}/datasources/{id}/points

{
  "metadata": {
    "ApiVersion": "1.0"
  },
  "data": [
    {
      "type": "DataSource",
      "id": 15,
      "attributes": {
        "BMSInfoID": "1",
        "BMSInfoName": "Name",
		"CID": "2",
        "DataSourceName": "Name",
		"DTSID": "3",
        "DTSName": "Main auditorium",
		"IPList": "Academic Building",
        "IsActive": "True",
		"IsIntegrated": "False",
        "ReferenceID": "4"
      },
      "relationships": {},
      "links": {
        "self": "http://{URL}/Clients/2/DataSources"
      }
    }
  ],
  "links": {
    "self": "http://{URL}/Clients/2/DataSources",
    "first": "http://{URL}/Clients/2/DataSources?page[number]=0"
  }
}

Engineering Units
Engineering Units describe Imperial (IP) and Système international (SI) measurement units referenced within Clockworks, such as Fahrenheit (F), Celsius (C), kilowatt hours (kWh), etc.
Request	Returns
GET /engineeringunits	All Engineering Units.
GET /engineeringunits/{id}	An Engineering Unit by ID.
OPTIONS /engineeringunits	This Help table.
Response Key	Data Type	Allow Nulls?	Description
id	Integer	No	Engineering Unit ID.
EngUnits	String(100)	No	Engineering Unit name.
EngUnitsDescription	String(1000)	No	Engineering Unit description.
DateModified	ISO Date String	No	Date, in UTC, the Engineering Unit was modified in the system.
DateCreated	ISO Date String	No	Date, in UTC, the Engineering Unit was created in the system.
MinValue	Floating Point	No	The minimum range boundary for the Engineering Unit.
MaxValue	Floating Point	No	The maximum range boundary for the Engineering Unit.

GET https://{URL}/core-base/engineeringunits/15

{
  "metadata": {
    "ApiVersion": "1.0"
  },
  "data": [
    {
      "type": "EngineeringUnits",
      "id": 15,
      "attributes": {
        "EngUnits": "F",
        "EngUnitsDescription": "Fahrenhiet",
		"DateModified":"2015-05-15 18:18:44.700",
		"DateCreated":"2015-05-15 18:18:44.700",
		"MinValue":"-50",
		"MaxValue":"1500"
      },
      "relationships": {},
      "links": {
        "self": "https://{URL}/EngineeringUnits/15/"
      }
    }
  ],
  "links": {
    "self": "https://{URL}/EngineeringUnits/15/",
    "first": "https://{URL}/EngineeringUnits/15?page[number]=0"
  }
}

Equipment
Equipment are defined as a mechanical device associated with a Building.
Request	Returns
GET /equipment	All Equipment.
GET /equipment/{id}	A piece of Equipment by ID.
GET /equipment/{id}/analyses	All Analyses related to the piece of Equipment.
GET /equipment/{id}/points	All Points related to the piece of Equipment.
GET /equipment/{id}/vpoints	All VirtualPoints (i.e., calculated)related to the piece of Equipment.
GET /equipment/{id}/vprepoints	All Virtual PrePoints (i.e., estimated) to the piece of Equipment.
GET /equipment/{id}/taskrecords	All Tasks related to the piece of Equipment.
GET /equipment/{id}/equipmentequipmentvariables	Values of all Equipment Variables assigned to the piece of Equipment.
OPTIONS /equipment	This Help table.
Response Key	Data Type	Allow Nulls?	Description
id	Integer	No	Equipment ID.
BID	Integer	No	ID of the Building with which this piece of Equipment is associated.
EquipmentName	String(50)	No	Equipment name.
EquipmentLocation	String(250)	Yes	Additional location information about the piece of Equipment.
SerialNumber	String(50)	Yes	Serial number of the piece of Equipment.
Description	String(1000)	Yes	Equipment description.
EquipmentTypeID	Integer	No	ID of the specific type under the Equipment classification.
IsActive	Bit	No	True (1) if the piece of Equipment is actively receiving data and running Diagnostics in the system, False (0) otherwise.
IsVisible	Bit	No	True (1) if the piece of Equipment is visible to non-administrative users in the system, False (0) otherwise.
DateCreated	ISO Date String	No	Date, in UTC, the piece of Equipment was created in the system.
DateModified	ISO Date String	No	Date, in UTC, the piece of Equipment was last modified in the system.
ExternalEquipmentTypeName	String(100)	Yes	Customers external name of the type of the Equipment.
EquipmentNotes	String(5000)	Yes	Additional user notes and information about the Equipment, in HTML.
ManufacturerModelID	Integer	No	Manufacturer Model ID.
CMMSReferenceID	String(50)	Yes	CMMS Reference or Asset ID for integration.
CMMSLink	String(100)	Yes	CMMS integration direct link to asset.
CMMSLocationID	String(50)	Yes	CMMS asset location.
CMMSSiteID	String(50)	Yes	CMMS asset Site ID.

GET https://{URL}/core-base/equipment/94008

{
  "metadata": {
    "ApiVersion": "1.0"
  },
  "data": [
    {
      "type": "Equipment",
      "id": 94008,
      "attributes": {
        "BID": 5817,
        "EquipmentName": "(DTH) AHU-21",
        "EquipmentLocation": "Headquarters",
        "SerialNumber": null,
        "Description": "Main air handler",
        "EquipmentTypeID": 174,
        "IsActive": true,
        "IsVisible": true,
        "DateCreated": "2016-04-28T18:07:35.643",
        "DateModified": "2016-04-28T18:07:36.29",
        "ExternalEquipmentTypeName": null,
        "EquipmentNotes": null
      },
      "relationships": {
        "Analyses": {
          "links": {
            "self": "https://{URL}/core-base/Equipment/94008/Analyses/"
          }
        },
        "Points": {
          "links": {
            "self": "https://{URL}/core-base/Equipment/94008/Points/"
          }
        },
        "TaskRecords": {
          "links": {
            "self": "https://{URL}/core-base/Equipment/94008/TaskRecords/",
            "related": "https://{URL}/core-base/TaskRecords/"
          }
        },
		"EquipmentEquipmentVariables": {
          "links": {
            "self": "https://{URL}/core-base/Equipment/94008/EquipmentEquipmentVariables/"
          }
        }
      },
      "links": {
        "self": "https://{URL}/core-base/Equipment/94008/"
      }
    }
  ],
  "links": {
    "self": "https://{URL}/core-base/equipment/94008/",
    "first": "https://{URL}/core-base/equipment/94008?page[number]=0"
  }
}

Equipment Classes
Equipment Classes describe common classes of Equipment such as Air Handler, Boiler, Chiller, or Utilities.
Request	Returns
GET /equipmentclasses	All Equipment Classes.
GET /equipmentclasses/{id}	An Equipment Class by ID. The Equipment Class ID must be used by at least one piece of Equipment associated with the Client.
GET /equipmentclasses/{id}/equipmenttypes	All Equipment Types related to the Equipment Class. The Equipment Class ID must be used by at least one piece of Equipment associated with the Client.
OPTIONS /equipmentclasses	This Help table.
Response Key	Data Type	Allow Nulls?	Description
id	Integer	No	Equipment Class ID.
EquipmentClassName	String(50)	No	Name of the Equipment Class.
EquipmentClassDescription	String(50)	No	Name of the Equipment Class.

GET https://{URL}/core-base/equipmentclasses/9

{
  "metadata": {
    "ApiVersion": "1.0"
  },
  "data": [
    {
      "type": "EquipmentClasses",
      "id": 9,
      "attributes": {
        "EquipmentClassName": "Zone Equipment",
        "EquipmentClassDescription": "This class includes zone level terminal units."
      },
      "relationships": {
        "EquipmentTypes": {
          "links": {
            "self": "https://{URL}/core-base/EquipmentClasses/9/EquipmentTypes/",
            "related": "https://{URL}/core-base/EquipmentTypes/"
          }
        }
      },
      "links": {
        "self": "https://{URL}/core-base/EquipmentClasses/9/"
      }
    }
  ],
  "links": {
    "self": "https://{URL}/core-base/equipmentclasses/9/",
    "first": "https://{URL}/core-base/equipmentclasses/9?page[number]=0"
  }
}

Equipment Points
Equipment Points describes a relationship of equipment and point for a building.
Request	Returns
GET/buildings/{id}/equipmentpoints	All Equipment Points related to the building.
Response Key	Data Type	Allow Nulls?	Description
EID	Integer	No	Equipment ID.
PID	Integer	No	Point ID.
EPID	Integer	No	ID of the Equipment Point association.

GET https://{URL}/core-base/buildings/3/equipmentpoints

{
  "meta": {
    "ApiVersion": "1.0"
  },
  "data": [
    {
      "type": "Buildings",
      "id": 13,
      "links": {
        "self": "https://{URL}/core-base/Buildings/13/"
      },
      "attributes": {
        "BuildingName": "KGS Headquarters",
        "BuildingTypeID": 1,
        "CID": 1
      }
    }
  ],
  "links": {
    "self": "https://{URL}/core-base/buildings/13/equipmentpoints",
    "first": "https://{URL}/core-base/buildings/13/equipmentpoints?page[number]=0",
    "last": "https://{URL}/core-base/buildings/13/equipmentpoints?page[number]=0"
  },
  "included": [
    {
      "type": "EquipmentPoints",
      "id": 20266,
      "links": {
        "self": "https://{URL}/core-base/EquipmentPoints/20266/"
      },
      "attributes": {
        "EPID": 20266,
        "EID": 2741,
        "PID": 19560
      }
    }
  ]
}

Equipment Types
Equipment Types describe subsets of Equipment Classes, such as AHU with Economizer or AHU with Heat Recovery being types of Air Handlers.
Request	Returns
GET /equipmenttypes	All Equipment types resources.
GET /equipmenttypes/{id}	An Equipment type resource by ID. The Equipment Type ID must be used by at least one piece of Equipment associated with the Client.
GET /equipmenttypes/{id}/pointtypes	All Point Types for the related Equipment Type.
OPTIONS /equipmenttypes	This Help table.
Response Key	Data Type	Allow Nulls?	Description
id	Integer	No	Equipment Type ID.
EquipmentTypeName	String(100)	No	Name of the Equipment Type.
EquipmentTypeDescription	String(max)	No	Description of the Equipment Type.
EquipmentClassID	Integer	No	ID of the associated Equipment Class.

GET https://{URL}/core-base/equipmenttypes/168

{
	"metadata": {
		"ApiVersion": "1.0"
	},
	"data": [{
		"type": "EquipmentTypes",
		"id": 168,
		"attributes": {
			"EquipmentTypeName": "Whole Building Utilities",
			"EquipmentTypeDescription": "Collection of points from multiple utility meters",
			"EquipmentClassID": 34
		},
		"relationships": ":{
			"PointTypes":{
				"links":{"self":"http://core-base/EquipmentTypes/168/PointTypes",
				"related":"http://{URL}/core-base/PointTypes"}
			}
		},",
		"links": {
			"self": "https://{URL}/core-base/EquipmentTypes/168/"
		}
	}],
	"links": {
		"self": "https://{URL}/core-base/equipmenttypes/168/",
		"first": "https://{URL}/core-base/equipmenttypes/168?page[number]=0"
	}
}

Equipment Variables
Equipment Variables describe Equipment data points, such as Electricity Costs, along with related Engineering Units and default values.
Request	Returns
GET /equipmentvariables	All Equipment Variables.
GET /equipmentvariables/{id}	A Equipment Variable by ID.
OPTIONS /equipmentvariables	This Help table.
Response Key	Data Type	Allow Nulls?	Description
id	Integer	No	Equipment Variable ID.
EquipmentVariableDescription	String(100)	No	Equipment Variable description.
EquipmentVariableDisplayName	String(1000)	No	Equipment Variable display name.
EquipmentVariableName	String(1000)	No	Equipment Variable name.
IPDefaultValue	Integer	No	IP Engineering Unit default value.
IPEngUnitID	Integer	No	IP Engineering Unit ID.
IPEngUnits	String(50)	No	IP Engineering Unit.
SIDefaultValue	Integer	No	SI Engineering Unit default value.
SIEngUnitID	Integer	No	SI Engineering Unit ID.
SIEngUnits	String(50)	No	SI Engineering Unit.

https://{URL}/core-base/EquipmentVariables/5

{
  "metadata": {
    "ApiVersion": "1.0"
  },
  "data": [
    {
      "type": "EquipmentVariables",
      "id": 5,
      "attributes": {
        "EquipmentVariableDescription": "Cooling coil capacity",
        "EquipmentVariableDisplayName": "CoolingCoilCapacity",
        "EquipmentVariableName": "CoolingCoilCapacity",
        "IPDefaultValue": "0",
        "IPEngUnitID": 11,
        "IPEngUnits": "TONS",
        "SIDefaultValue": "0",
        "SIEngUnitID": 41,
        "SIEngUnits": "kW"
      },
      "relationships": {},
      "links": {
        "self": "https://{URL}/core-base/EquipmentVariables/5"
      }
    }
  ],
  "links": {
    "self": "https://{URL}/core-base/equipmentvariables/5",
    "first": "https://{URL}/core-base/equipmentvariables/5?page[number]=0"
  }
}

Equipment Equipment Variables
Equipment Equipment Variables are data points and values such as Electricity Costs for that Equipment.
Request	Returns
GET /equipment/{id}/equipmentequipmentvariables	Values of Equipment Variables assigned to the piece of Equipment.
Response Key	Data Type	Allow Nulls?	Description
id	Integer	No	Unique ID for the Equipment Variable for the piece of Equipment.
EVID	Integer	No	Equipment Variable ID.
Value	String(2500)	No	Value of the Equipment Variable for the piece of Equipment.
DateModified	ISO Date String	No	Last date modified.

https://{URL}/core-base/equipment/24473/equipmentequipmentvariables

{
  "data": [
    {
      "type": "Equipment",
      "id": 24473,
      "links": {
        "self": "https://{URL}/core-base/Equipment/24473/"
      },
      "attributes": {
        "BID": 1235,
        "EquipmentName": "Bldg1_AHU1",
        "EquipmentLocation": "Demo Bldg1, A wing penthouse\nBldg1_AHU1",
        "SerialNumber": "4A65078BR2309",
        "Description": "AHU w/Economizer serving kitchen and dining areas",
        "EquipmentTypeID": 174,
        "IsActive": true,
        "IsVisible": true,
        "DateCreated": "2013-12-06T17:11:43.46",
        "DateModified": "2021-09-27T20:01:56.233",
        "ExternalEquipmentTypeName": null,
        "EquipmentNotes": "<div>Filters = 20 x 25 x 2</div>\n<div>Fan belt = A37/4L390</div>",
        "ManufacturerModelID": 60,
        "CMMSReferenceID": null,
        "CMMSLink": null,
        "CMMSLocationID": null,
        "CMMSSiteID": null
      },
      "relationships": {
        "Analyses": {
          "links": {
            "self": "https://{URL}/core-base/Equipment/24473/Analyses/",
            "related": "https://{URL}/core-base/Equipment/24473/Analyses/"
          },
          "data": []
        },
        "EquipmentEquipmentVariables": {
          "links": {
            "self": "https://{URL}/core-base/Equipment/24473/EquipmentEquipmentVariables/"
          },
          "data": [
            {
              "type": "EquipmentEquipmentVariables",
              "id": 181825
            },
            {
              "type": "EquipmentEquipmentVariables",
              "id": 83620
            }
          ]
        },
        "Points": {
          "links": {
            "self": "https://{URL}/core-base/Equipment/24473/Points/"
          },
          "data": []
        },
        "VPoints": {
          "links": {
            "self": "https://{URL}/core-base/Equipment/24473/VPoints/"
          },
          "data": []
        },
        "VPrePoints": {
          "links": {
            "self": "https://{URL}/core-base/Equipment/24473/VPrePoints/"
          },
          "data": []
        },
        "TaskRecords": {
          "links": {
            "self": "https://{URL}/core-base/Equipment/24473/TaskRecords/",
            "related": "https://{URL}/core-base/Equipment/24473/TaskRecords/"
          },
          "data": []
        }
      }
    }
  ],
  "links": {
    "self": "https://{URL}/core-base/equipment/24473/equipmentequipmentvariables",
    "first": "https://{URL}/core-base/equipment/24473/equipmentequipmentvariables?page[number]=0",
    "last": "https://{URL}/core-base/equipment/24473/equipmentequipmentvariables?page[number]=0"
  },
  "included": [
    {
      "type": "EquipmentEquipmentVariables",
      "id": 181825,
      "attributes": {
        "EVID": 128,
        "Value": "15",
        "DateModified": "2016-07-05T18:49:28.37"
      }
    },
    {
      "type": "EquipmentEquipmentVariables",
      "id": 83620,
      "attributes": {
        "EVID": 2,
        "Value": "0.10755",
        "DateModified": "2016-07-05T18:49:28.45"
      }
    }
    }
  ],
  "meta": {
    "ApiVersion": "1.0"
  }
}

Equipment Equipments
Equipment to Equipments provides a list of related equipment
Request	Payload Key	Data Type	Required?	Description	Returns
POST /equipmentequipments	CID	Array of Integer	Yes	An array of Client IDs If BID is specified, CID is optional. One BID or CID is required.	Equipment to Equipments relationships. A list of related equipmentIDs to equipment for provided clients and/or Buildings
POST /equipmentequipments	BID	Array of Integer	Yes	An array of Building IDs If CID is specified, BID is optional. One BID or CID is required.
Response Key					Data Type	Allow Nulls?	Description
PrimaryEID					Integer	No	Unique ID for the Equipment Variable for the piece of Equipment.
AssignedEID					Integer	No	Equipment Variable ID.
DateCreated					ISO Date String	No	Date created.

POST https://{URL}/core-base/equipmentequipments Payload: { "CID":[79] }

{
  "data": [
    {
      "type": "EquipmentEquipment",
      "id": 562054,
      "attributes": {
        "PrimaryEID": 19716,
        "AssignedEID": 358577,
        "DateCreated": "2020-07-01T14:46:44.007"
      }
    }
  ],
  "links": {
    "first": "https://{URL}/core-base/equipmentequipments?page[number]=0&spko=data:sids:tkkxu1nu",
    "last": "https://{URL}/core-base/equipmentequipments?page[number]=0&spko=data:sids:tkkxu1nu"
  },
  "meta": {
    "ApiVersion": "1.0"
  }
}

Equipment Types Equipment Types
Equipment Type to Equipment Types provides a list of related equipment types
Request	Returns
GET/equipmenttypesequipmenttypes	All Equipment type to Equipment type relationships.
Response Key	Data Type	Allow Nulls?	Description
id	Integer	No	ID of the equipment type to equipment type relationship
PrimaryEquipmentTypeID	Integer	No	Primary Equipment Type ID.
PrimaryEquipmentTypeName	String	No	Name of the Primary Equipment Type.
AssignedEquipmentTypeID	Integer	No	Assigned Equipment Type ID.
AssignedEquipmentTypeName	String	No	Name of the Assigned Equipment Type.

GET https://{URL}/core-base/equipmenttypesequipmenttypes

{
	"data": [
		{
			"type": "EquipmentTypeEquipmentType",
			"id": 799,
			"attributes": {
				"PrimaryEquipmentTypeID": 151,
				"PrimaryEquipmentTypeName": "HW Primary Loop",
				"AssignedEquipmentTypeID": 1,
				"AssignedEquipmentTypeName": "Finned Tube Radiator"
			}
		},
		{
			"type": "EquipmentTypeEquipmentType",
			"id": 2848,
			"attributes": {
				"PrimaryEquipmentTypeID": 162,
				"PrimaryEquipmentTypeName": "Open Floor Plan Zone Group",
				"AssignedEquipmentTypeID": 1,
				"AssignedEquipmentTypeName": "Finned Tube Radiator"
			}
		},
		{
			"type": "EquipmentTypeEquipmentType",
			"id": 814,
			"attributes": {
				"PrimaryEquipmentTypeID": 168,
				"PrimaryEquipmentTypeName": "Whole Building Utilities",
				"AssignedEquipmentTypeID": 1,
				"AssignedEquipmentTypeName": "Finned Tube Radiator"
			}
		}
	],
	"links": {
		"first": "https://{URL}/core-base/equipmenttypesequipmenttypes?page[number]=0&spko=data:sids:emd1bqap",
		"next": "https://{URL}/core-base/equipmenttypesequipmenttypes?page[number]=1&spko=data:sids:emd1bqap",
		"last": "https://{URL}/core-base/equipmenttypesequipmenttypes?page[number]=1&spko=data:sids:emd1bqap"
	},
	"meta": {
		"ApiVersion": "1.0"
	}
}

Equipment Types Point Types
Equipment Type to Point Types provides a list of related point types
Request	Returns
GET/equipmenttypespointtypes	All Equipment type to Point type relationships.
Response Key	Data Type	Allow Nulls?	Description
id	Integer	No	ID of the equipment type to point type relationship
EquipmentTypeID	Integer	No	Equipment Type ID.
EquipmentTypeName	String	No	Name of the Equipment Type.
PointTypeID	Integer	No	Point Type ID.
PointTypeName	String	No	Name of the Point Type.

GET https://{URL}/core-base/equipmenttypespointtypes

{
	"data": [
		[
        {
            "type": "EquipmentTypePointType",
            "id": 1,
            "attributes": {
                "EquipmentTypeID": 219,
                "EquipmentTypeName": "Pump Condensate Boiler",
                "PointTypeID": 1015,
                "PointTypeName": "BoilerPumpRun"
            }
        },
        {
            "type": "EquipmentTypePointType",
            "id": 2,
            "attributes": {
                "EquipmentTypeID": 219,
                "EquipmentTypeName": "Pump Condensate Boiler",
                "PointTypeID": 1014,
                "PointTypeName": "BoilerPumpStatus"
            }
        }
	],
	"links": {
		"first": "https://{URL}/core-base/equipmenttypespointtypes?page[number]=0&spko=data:sids:emd1bqap",
		"next": "https://{URL}/core-base/equipmenttypespointtypes?page[number]=1&spko=data:sids:emd1bqap",
		"last": "https://{URL}/core-base/equipmenttypespointtypes?page[number]=1&spko=data:sids:emd1bqap"
	},
	"meta": {
		"ApiVersion": "1.0"
	}
}

Analyses
When an Analysis is applied to a piece of Equipment, a Diagnostic is generated describing any issues.
Request	Returns
GET /analyses	All Analysis resources
GET /analyses/{id}	An Analysis by ID. The Analysis ID must be available to the Subscriber.
OPTIONS	This Help table.
Request	Returns	Allow Nulls?	Description
AID	Integer	No	Analysis ID.
AnalysisName	String(150)	No	Analysis name.
AnalysisDescription	String(5000)	Yes	Description of the Analysis.
AnalysisTeaser	String(1000)	Yes	Summarized description of the Analysis.

GET https://{URL}/core-base/analyses

{
  "metadata": {
    "ApiVersion": "1.0"
  },
  "data": [
    {
      "type": "Analysis",
      "id": 82,
      "attributes": {
        "AnalysisName": "Building Energy",
        "AnalysisTeaser": "Building Utility Performance",
        "AnalysisDescription": "UTILITY PERFORMANCE: Actual and expected baseline performance based\n\n  
								INFO: Actual and expected utility use\n    Cost calculation: Not applicable\n    Priorities: Not applicable"
      },
      "relationships": {},
      "links": {
        "self": "https://{URL}/core-base/Analysis/82/"
      }
    }
  ],
  "links": {
    "self": "https://{URL}/core-base/analyses/82/",
    "first": "https://{URL}/core-base/analyses/82?page[number]=0"
  }
}

Diagnostics
Diagnostics are the results of an Analysis being applied to a piece of Equipment.
Request	Payload Key	Data Type	Required?	Description	Returns
POST /diagnostics	CID	Array of Integer	Yes	A single element array of a Client ID.	Diagnostics by the given criteria. Diagnostics will only be returned if the Diagnostic's StartDate is within the StartDate and EndDate of the request. The Diagnostic's StartDate varies based on the AnalysisInterval value. See StartDate response key below for definition of the Diagnostic's StartDate for the different AnalysisInterval values.
	BID	Array of Integer	No	An array of Client Building IDs.
	EID	Array of Integer	No	An array ofClient Equipment IDs.
	AID	Array of Integer	No	An array ofAnalysis IDs.
	ECID	Array of Integer	No	An array ofEquipment Class IDs.
	StartDate	ISO Date String	Yes	Start Date, in format "YYYY-MM-DD".
	EndDate	ISO Date String	Yes	End Date, in format "YYYY-MM-DD".
	AnalysisInterval	String	Yes	Analysis Interval - "HalfDay", "Daily", "Weekly", or "Monthly".
OPTIONS /diagnostics	-				This Help table.
Response Key		Data Type	Allow Nulls?	Description
AEID		Integer	No	Analysis Equipment relationship pair ID. Unique per AnalysisInterval and StartDate.
AID		Integer	No	Analysis ID.
AnalysisName		String	No	Analysis Name.
BID		Integer	No	Building ID.
ComfortPriority		Double	No	Comfort Priority (0-10).
CostSavings		Float	No	Avoidable Costs, in Building Currency.
EnergyPriority		Double	No	Energy Priority (0-10).
EID		Integer	No	Equipment ID.
EquipmentName		String	No	Name of the piece of Equipment.
MaintenancePriority		Double	No	Maintenance Priority (0-10).
NotesSummary		String	No	Diagnostic summary details.
StartDate		ISO Date String	No	Start date of the Analysis data range. For AnalysisInterval value of "Weekly", the value represents the first day, Sunday, of the week that is analyzed. For AnalysisInterval value of "Monthly", the value represents the first day of the month that is analyzed. For AnalysisInterval values of "Daily" and "HalfDay", the value is the analyzed day.
DiagnosticHyperlink		String	No	Diagnostic link to Classic Diagnostic's page

POST https://{URL}/core-diag/diagnostics
Payload: {
            "CID":[79], 
            "StartDate":"2016-12-12", 
            "EndDate":"2016-12-12", 
            "AnalysisInterval":"Daily"
         }

{
  "metadata": {
    "ApiVersion": "1.0"
  },
  "data": [
    {
      "type": "Diagnostics",
      "id": "1992547364",
      "attributes": {
        "AEID": 0,
        "AID": 83,
        "AnalysisName": "Chiller Efficiency",
        "BID": 180,
        "ComfortPriority": 0,
        "CostSavings": 934,
        "EID": 21390,
        "EnergyPriority": 10,
        "EquipmentName": "Chiller-1",
        "MaintenancePriority": 5,
        "NotesSummary": "Cooling efficiency is low.",
        "StartDate": "2016-12-12T00:00:00"
      },
      "relationships": {}
    }
  ],
  "links": {
    "self": "{url}/core-diag/diagnostics/",
    "first": "{url}/core-diag/diagnostics?page[number]=0",
    "next": "{url}/core-diag/diagnostics?page[number]=1"
  }
}

Points
Points are defined as a set of data properties logically grouped under a Point resource. To return a specific fields in the response, a consumer may use the value of fields parameter in a comma-separated list that refers to the names of the fields to be returned.
Request	Payload Key	Data Type	Required?	Description	Returns
POST /points	PID	Array of Integers	Yes	Array of Point IDs.	Description of the Points.
OPTIONS /points	-				This Help table.
Response Key		Data Type	Allow Nulls?	Description
id		Integer	No	Point ID.
PointName		String(50)	No	Point Name.
PointTypeID		Integer	No	ID of the categorized Point type.
PointTypeName		String(50)	No	Name of the specific type under the Point classification.
PointClassID		Integer	No	ID of the categorized Point classification.
PointClassName		String(50)	No	Name of the categorized Point classification.
DataSourceID		Integer	No	Data source ID.
DateCreated		ISO Date String	No	Date, in UTC, the Point was created in the system.
DateModified		ISO Date String	No	Date, in UTC, the Point was last modified in the system.
TimeZone		String(50)	No	Points timezone (TimeZoneInfo) ID. Used for rawdata ISO Date String timestamp conversions from UTC.
ReferenceID		String(250)	No	Unique reference identifier for the Point on a BMS data source.
SamplingInterval		Integer	No	Interval, in minutes, (> 0) in which data is extracted from the clients end and sent to Default = 5 minutes.
RelPctError		Double	No	Relative percent error of the Point values. The absolute error is the magnitude of the difference between the exact value and the approximation. The relative error is the absolute error divided by the magnitude of the exact value. The percent error is the relative error expressed as a percentage. Default = 0.
IsSubscriptionBased		Bit	No	True (1) if the Point is subscription based and the data transfer service is configured to use optimized polling for this Point, False (0) otherwise.
IsActive		Bit	No	True (1) if the Point is actively receiving data and Diagnostics requiring this Point as input are running in the system, False (0) otherwise.
Power		Double	No	Incoming power raw data modifier.
Multiply		Double	No	Incoming multiply raw data modifier.
Addition		Double	No	Incoming addition raw data modifier.
PowerMatlab		Double	No	Analysis input power raw data modifier.
MultiplyMatlab		Double	No	Analysis input multiply raw data modifier.
AdditionMatlab		Double	No	Analysis input addition raw data modifier.

POST https://{URL}/core-base/points

POST https://{URL}/core-base/points?fields[Points]=PointName,PointClassName

Payload: {
            "PID":[582836, 582845]
         }

{
  "metadata": {
    "ApiVersion": "1.0"
  },
  "data": [
    {
      "type": "Points",
      "id": 582836,
      "attributes": {
        "PointName": "QQ01_EDKK",
        "PointTypeName": null,
        "PointClassID": 10,
        "PointClassName": null,
		"PointTypeID": 1406,
        "DataSourceID": 2223,
        "DateModified": "2016-03-24T02:46:00.703",
        "DateCreated": "2016-03-24T02:46:00.703",
        "TimeZone": "Eastern Standard Time",
        "ReferenceID": "739-G1-LJ03-QQ01-QQ01_EDKK",
        "SamplingInterval": 5,
        "RelPctError": 0,
        "IsSubscriptionBased": false,
        "IsActive": true,
        "IsVisible": true,
        "Power": 1.0,
        "Multiply": 1.0,
        "Addition": 0.0,
        "PowerMatlab": 1.0,
        "MultiplyMatlab": 1.0
        "AdditionMatlab": 0.0
      },
      "relationships": {
        "RawData": {
          "links": {
            "self": "https://{URL}/core-base/Points/RawData/"
          }
        }
      }
    },
    {
      "type": "Points",
      "id": 582845,
      "attributes": {
        "PointName": "QQ01_EDKK",
        "PointTypeName": null,
        "PointClassID": 10,
        "PointClassName": null,
		"PointTypeID": 1406,
        "DataSourceID": 2223,
        "DateModified": "2016-03-24T02:46:00.877",
        "DateCreated": "2016-03-24T02:46:00.877",
        "TimeZone": "Eastern Standard Time",
        "ReferenceID": "739-G1-LJ04-QQ01-QQ01_EDKK",
        "SamplingInterval": 5,
        "RelPctError": 0,
        "IsSubscriptionBased": false,
        "IsActive": true,
        "IsVisible": true,
        "Power": 1.0,
        "Multiply": 1.0,
        "Addition": 0.0,
        "PowerMatlab": 1.0,
        "MultiplyMatlab": 1.0
        "AdditionMatlab": 0.0
      },
      "relationships": {
        "RawData": {
          "links": {
            "self": "https://{URL}/core-base/Points/RawData/"
          }
        }
      }
    }
  ],
  "links": {
    "self": "https://{URL}/core-base/points/",
    "first": "https://{URL}/core-base/points?page[number]=0"
  }
}

Point Classes
A Point Class is a grouping of Points by common characteristics.
Request	Returns
GET /pointclasses	All Point Classes
GET /pointclasses/{id}	A Point Class by ID.
GET /pointclasses/{id}/pointtypes	All Point Types related to the Point Class.
OPTIONS /pointclasses	This Help table.
Response	Returns	Allow Nulls?	Description
ID	Integer	No	Point Class ID.
PointClassName	String(50)	No	Point Class name.
PointClassDescription	String(50)	No	Description of the Point Class.
IPEngUnitID	Integer	No	IP Engineering Unit ID.
SIEngUnitID	Integer	No	SI Engineering Unit ID.

GET https://{URL}/core-base/pointclasses/2

{
  "metadata": {
    "ApiVersion": "1.0"
  },
  "data": [
    {
      "type": "PointClasses",
      "id": 2,
      "attributes": {
        "PointClassName": "AirFlow",
        "PointClassDescription": null
      },
      "relationships": {
        "PointTypes": {
          "links": {
            "self": "https://{URL}/core-base/PointClasses/2/PointTypes/"
          }
        }
      },
      "links": {
        "self": "https://{URL}/core-base/PointClasses/2/"
      }
    }
  ],
  "links": {
    "self": "https://{URL}/core-base/pointclasses/2/",
    "first": "https://{URL}/core-base/pointclasses/2?page[number]=0"
  }
}

Point Types
A Point Type is a sub-grouping of Point Classes, defined by Points with specific characteristics.
Request	Returns
GET /pointtypes	All Point Types
GET /pointtypes?enabledFor={value}	All Point Types enabled for "Point", "VPoint", or "VPrePoint"
GET /pointtypes/{id}	A Point Type by ID.
OPTIONS /pointtypes	This Help table.
Response	Returns	Allow Nulls?	Description
ID	Integer	No	Point Type ID.
EnabledFor	Array of Strings	No	What the Point Type is enabled for: "Point", "VPoint", and/or "VPrePoint".
DisplayName	String(50)	No	Display Name of the Point Type.
PointTypeName	String(50)	No	Name of the Point Type.
PointTypeDescription	String(100)	Yes	Description of the Point Type.
PointClassID	Integer	No	ID of the associated Point Class.

GET https://{URL}/core-base/pointtypes/907

{
  "metadata": {
    "ApiVersion": "1.0"
  },
  "data": [
    {
      "type": "PointTypes",
      "id": 907,
      "attributes": {
        "PointClassID": 2,
        "PointTypeName": "AirFlow",
        "DisplayName": "AirFlow",
        "PointTypeDescription": "Generic air flow",
        "EnabledFor": [
          "point"
        ]
      },
      "relationships": {},
      "links": {
        "self": "https://{URL}/core-base/PointTypes/907"
      }
    }
  ],
  "links": {
    "self": "https://{URL}/core-base/pointtypes/907",
    "first": "https://{URL}/core-base/pointtypes/907?page[number]=0"
  }
}

Raw Data
Raw Data are defined as a set of data related to a Point.
Request	Payload Key	Data Type	Required?	Description	Returns
POST /rawdata	CID	Array of Integer	Yes	A single element array of a Client ID.	Raw Data for by the given criteria.
	PID	Array of Integers	Yes	Array of Point IDs.
	StartDate	ISO Date String	Yes	UTC Start Date, in format "YYYY-MM-DD".
	EndDate	ISO Date String	Yes	UTC End Date, in format "YYYY-MM-DD".
OPTIONS /rawdata	-				This Help table.
Response Key		Data Type	Allow Nulls?	Description
ID		Integer	No	Raw Data ID. This ID has no logical value and should not be used. Raw Data records should be referenced with a combination of Point ID (PID), Equipment ID (EID) and the date the data was logged (DateLoggedUTC).
PID		Integer	No	Point ID.
EID		Integer	No	Equipment ID. If the Point is shared across multiple pieces of Equipment, then this ID is for the primary related piece of Equipment.
DateLoggedUTC		ISO Date String	No	Date, in UTC, the Point value was logged.
DateLoggedLocal		ISO Date String	No	Date, in local timezone, the Point value was logged.
RawValue		String	No	Raw value. Note: Large RawValue numeric data value may be returned using scientific notation.
PointName		String(50)	No	Point name.
BuildingSettingBasedEngUnits		String(50)	No	Engineering units of this Point value dictated by the configured Buildings settings for International System of Units (SI) or Imperial Units (IP).

POST https://{URL}/core-rawdata/rawdata
Payload: {
			"CID":[79],
			"PID":[301404],
			"StartDate":"2021-10-30",
			"EndDate":"2021-10-31"
		}

{
  "metadata": {
    "ApiVersion": "1.0"
  },
  "data": [
    {
            "type": "RawData",
            "id": 1998105749,
            "attributes": {
                "PID": 301404,
                "EID": 50400,
                "DateLoggedUTC": "2021-10-30T00:05:00Z",
                "DateLoggedLocal": "2021-10-30T11:05:00",
                "RawValue": "53.558799998",
                "PointName": "SATmp",
                "BuildingSettingBasedEngUnits": "F"
       },
      "relationships": {}
    }
  ],
  "links": {
    "self": "https://{URL}/core-rawdata/rawdata",
    "first": "https://{URL}/core-rawdata/rawdata?page[number]=0",
    "next": "https://{URL}/core-rawdata/rawdata?page[number]=1"
  }
}

VPoints
Virtual Points (VPoints) are defined as calculated data points from an Analysis. The data is derived from a Point's Analysis and Equipment IDs.
Request	Payload Key	Data Type	Required?	Description	Returns
POST /vpoints	EID	Array of Integers	Yes	Array of Equipment IDs.	Virtual Points by the given criteria.
POST /vpoints	AID	Array of Integers	Yes	Array of Analysis IDs.	Virtual Points by the given criteria.
OPTIONS /vpoints	-				This Help table.
Response Key		Data Type	Allow Nulls?	Description
id		Integer	No	Virtual Point ID.
AID		Integer	No	Analysis ID.
EID		Integer	No	Equipment ID.
DateCreated		ISO Date String	No	Date, in UTC, the virtual Point was created in the system. Can be used to determine how far back virtual data may exist for this virtual Point.
PointTypeID		Integer	No	ID of the specific type under the Point classification.

POST https://{URL}/core-base/vpoints
Payload: {
            "EID":[1], 
            "AID":[12]
         }

{
  "metadata": {
    "ApiVersion": "1.0"
  },
  "data": [
    {
      "type": "VPoints",
      "id": 166,
      "attributes": {
        "DateCreated": "2010-11-17T15:44:57.323",
        "PointTypeId": 49,
        "EID": 1,
        "AID": 12
      },
      "relationships": {}
    },
    {
      "type": "VPoints",
      "id": 164,
      "attributes": {
        "DateCreated": "2010-11-17T15:44:57.31",
        "PointTypeId": 50,
        "EID": 1,
        "AID": 12
      },
      "relationships": {}
    },
    {
      "type": "VPoints",
      "id": 167,
      "attributes": {
        "DateCreated": "2010-11-17T15:44:57.34",
        "PointTypeId": 63,
        "EID": 1,
        "AID": 12
      },
      "relationships": {}
    }
  ],
  "links": {
    "self": "https://{URL}/core-base/vpoints/",
    "first": "https://{URL}/core-base/vpoints?page[number]=0"
  }
}

VData
Virtual Data (VData) values are defined as data sets which have been generated by an Analysis of a piece of Equipment.
Request	Payload Key	Data Type	Required?	Description	Returns
POST /vdata	CID	Array of Integer	Yes	A single element array of a Client ID.	Return Virtual Point data that meets the Payload criteria.
	VPID	Array of Integers	Yes	Array of Virtual Point IDs.
	StartDate	ISO Date String	Yes	Start Date in format "YYYY-MM-DD".
	EndDate	ISO Date String	Yes	End Date in format "YYYY-MM-DD".
	AnalysisInterval	String	Yes	Interval - "HalfDay", "Daily", "Weekly", or "Monthly".
OPTIONS /vdata	-				This Help table.
Response Key		Data Type	Allow Nulls?	Description
ID		Integer	No	Virtual Data ID. This ID has no logical value and should not be used. Raw Data records should be referenced with a combination of Point ID (PID), Equipment ID (EID) and the date the data was logged (DateLoggedUTC).
VPID		Integer	No	ID of the Virtual Point to which this piece of data relates.
StartDate		ISO Date String	No	Start date, in UTC, of the Analysis for which the Virtual Data was produced in the system, unless multiple values were produced for this Virtual Point and Analysis.
RawValue		String	Yes	Raw value that was produced for this Analysis and Virtual Point. Note: Large RawValue numeric data values may be returned using scientific notation.
RelPctError		Double	No	Relative percent error of this Virtual Point value produced for this Analysis. The absolute error is the magnitude of the difference between the exact value and the approximation. The relative error is the absolute error divided by the magnitude of the exact value. The percent error is the relative error expressed as a percentage. Default = 0.

POST https://{URL}/core-vdata/vdata
Payload : {
            "CID": [99],
            "VPID": [677934,677935],
            "StartDate": "2017-03-08",
            "EndDate": "2017-03-08",
            "AnalysisInterval": "Daily"
          }

{
  "metadata": {
    "ApiVersion": "1.0"
  },
  "data": [
    {
      "type": "VData",
      "id": "2075745513",
      "attributes": {
        "VPID": "677934",
        "StartDate": "2017-03-08T00:00:00",
        "RawValue": "0",
        "RelPctError": 0
      },
      "relationships": {}
    },
    {
      "type": "VData",
      "id": "1074719851",
      "attributes": {
        "VPID": "677935",
        "StartDate": "2017-03-08T00:00:00",
        "RawValue": "0",
        "RelPctError": 0
      },
      "relationships": {}
    }
  ],
  "links": {
    "self": "https://{URL}/core-vdata/vdata/",
    "first": "https://{URL}/core-vdata/vdata?page[number]=0"
  }
}

Task Records
Task Records are created from Diagnostics to address identified issues.
Request	Payload Key	Data Type	Required?	Description	Returns
GET /taskrecords	-				All Tasks.
GET /taskrecords/{id}	-				A Task by ID.
POST /taskrecords	Status	Array of String	No	Array of Statuses: "Open", "In Process", "Completed". Defaults to all Statuses.	The StartDate and EndDate represent the period of time you are interested in not the Issue Date, Created Date, Modified Date, or Completion Date. Instead, it represents the date range of interest for task activities. Tasks will be returned if they were unresolved at any point in time between the StartDate or EndDate. Tasks completed before the StartDate or created after the EndDate will not be returned. Note: If the Status of a Task was changed after the "EndDate" (e.g., a Task was 'Open' or 'In Process' during the date range, but was subsequently "Completed" after the "EndDate"), the Status at the time of the "EndDate" (either "Open" or "In Process") cannot be accurately determined. If such cases, the "Status" will be returned as "Open".
	StartDate	ISO Date String	Yes	Start Date, in format "YYYY-MM-DD".
	EndDate	ISO Date String	Yes	End Date, in format "YYYY-MM-DD".
	CID	Array of Integers	No	Array of Client IDs.
	BID	Array of Integers	No	Array of Building IDs.
	EID	Array of Integers	No	Array of Equipment IDs.
	HasWorkOrderID	Boolean	No	Flag to filter by with or without work orders in the WorkOrderID field.
	WorkOrderID	Array of String	No	Arrays of work order IDs.
	HasGenerateWorkOrder	Boolean	No	Flag to filter HasGenerateWorkOrder field.
POST /taskrecords	AEID	Array of Integers	Yes	Array of Diagnostic IDs.	All Tasks by AEID(s).
	HasWorkOrderID	Boolean	No	Flag to filter by with or without work orders in the WorkOrderID field.
	WorkOrderID	Array of String	No	Arrays of work order IDs.
	HasGenerateWorkOrder	Boolean	No	Flag to filter HasGenerateWorkOrder field.
OPTIONS /taskrecords	-				This Help table.
Response Key		Data Type	Allow Nulls?	Description
ID		Integer	No	Unique Task ID.
ClientTaskID		Integer	No	Incremental Client Task ID for display purposes.
AEID		Integer	No	ID of the Diagnostic from which the Task was created.
Summary		String(250)	No	Task summary text.
CID		Integer	No	ID of the associated client.
BID		Integer	No	ID of the associated Building.
EID		Integer	No	ID of the associated piece of Equipment.
AID		Integer	No	ID of the associated Analysis.
AnalysisStartDate		ISO Date String	No	Date, in local timezone, the Analysis ran.
Interval		String(25)	No	Analysis time interval over which the Diagnostic relates – "Half Day", "Daily", "Weekly", or "Monthly".
CMMSSiteID		String(50)	Yes	CMMS ID of the Site.
CMMSLocationID		String(50)	Yes	CMMS ID of the Building.
CMMSAssetID		String(50)	Yes	CMMS ID of the piece of Equipment.
WorkOrderID		String(50)	Yes	CMMS Work Order ID if a Work Order has been created from the Task.
DateCreated		ISO Date String	No	Date, in UTC, the Task was created in the system.
DateModified		ISO Date String	No	Date, in UTC, the Task was last modified in the system.
Reporter		String(100)	No	Email address of the user who created the Task.
Assignee		String(100)	No	Email address of the user to whom the Task is currently assigned.
Status		String(15)	No	Task status: "Open", "In Process", or "Completed". If "EndDate" is provided as part of the POST payload, the returned Task Status is as of the "EndDate", otherwise the Task Status is as of today.
Description		String(5000)	Yes	Description of the issue.
Recommendations		String(5000)	Yes	Recommendations for addressing the issue.
Actions		String(5000)	Yes	Actions taken to address the issue.
DateCompleted		ISO Date String	Yes	Date, in UTC, the Task was completed/closed.
AnnualAvoidableCost		String(50)	Yes	Total avoidable cost, in Building currency units.
AnnualAvoidableHeatingUse		String(50)	Yes	Total avoidable heating use cost, in Building currency units.
AnnualAvoidableCoolingUse		String(50)	Yes	Total avoidable cooling use cost, in Building currency units.
AnnualAvoidableElectricUse		String(50)	Yes	Total avoidable electric use cost, in Building currency units.
TaskHyperlink		String	No	Task link to Classic Task's Page.
AdditionalSavings		String(50)	Yes
HasGenerateWorkOrder		Boolean	No	Flag to indicate whether a CMMS polling for Tasks should generate a work order.

POST https://{URL}/core-base/taskrecords
Payload : {
             "Status":["Open", "In Process", "Completed"],
             "StartDate":"2016-01-01", 
             "EndDate":"2016-01-31"
          }

{
  "metadata": {
    "ApiVersion": "1.0"
  },
  "data": [
    {
      "type": "TaskRecords",
      "id": 748,
      "attributes": {
        "AEID": 3874,
        "Summary": "CHW Loop Supply temp lower than setpoint",
        "BID": 65,
        "EID": 4318,
        "AnalysisStartDate": "2016-05-24T00:00:00",
        "ClientTaskID": 4,
        "CMMSSiteID": null,
        "CMMSLocationID": null,
        "CMMSAssetID": null,
        "WorkOrderID": null,
        "DateCreated": "2016-05-25T14:19:34.573",
        "DateModified": "2016-06-06T16:56:28.303",
        "Interval": "Daily",
        "Reporter": "areporter@acme.com",
        "Assignee": "anassignee@acme.com",
        "Status": "Completed",
        "Description": "Supply temp lower than setpoint.",
        "Recommendations": "Check sensor",
        "Actions": "",
        "DateCompleted": "2016-06-06T16:56:28.303",
        "AnnualAvoidableCost": null,
        "AnnualAvoidableHeatingUse": null,
        "AnnualAvoidableCoolingUse": null,
        "AnnualAvoidableElectricUse": null,
        "AdditionalSavings": null,
		"HasGenerateWorkOrder" : false
      },
      "relationships": {},
      "links": {
        "self": "https://{URL}/core-base/TaskRecords/748/"
      }
    }
  ],
  "links": {
    "self": "https://{URL}/core-base/taskrecords/",
    "first": "https://{URL}/core-base/taskrecords?page[number]=0",
    "next": "https://{URL}/core-base/taskrecords?page[number]=1"
  }
}

Task Statuses
A list of available statuses for Task resource.
Request	Returns
GET /taskstatuses	All Task Statuses.
GET /taskstatuses/{id}	A Task Status by ID.
OPTIONS /taskstatuses	This Help table.
Response	Returns	Allow Nulls?	Description
StatusID	Integer	No	Status ID.
StatusName	String(15)	No	Name of the Status.

GET https://{URL}/core-base/taskstatuses/3

{
	"metadata": {
		"ApiVersion": "1.0"
	},
	"data": [
		{
			"type": "TaskStatuses",
			"id": 3,
			"links": {
				"self": "https://{URL}/core-base/TaskStatuses/3/"
			},
			"attributes": {
				"StatusID": 3,
				"StatusName": "In Process"
			}
		}
	],
	"links": {
		"self": "https://{URL}/core-base/taskstatuses/3",
		"first": "https://{URL}/core-base/taskstatuses/3?page[number]=0",
		"last": "http://{URL}/core-base/taskstatuses/3?page[number]=0"
	}
}

Usage Notes and Tips

Based on feedback for the existing External REST API developer community, below are several notes and tips that should be considered when developing against the API.

Paging

Large requests to the External REST API returns the data in pages with up to 1,000 data items per page. Hence, if a POST /diagnostics request is submitted to the External REST API that needs to return 2,500 Diagnostics, this would require 3 sequential requests:

POST {url}/core-diag/diagnostics - returns the first 1,000 Diagnostics
POST {url}/core-diag/diagnostics?page[number]=1 - returns next 1,000 Diagnostics
POST {url}/core-diag/diagnostics?page[number]=2 - returns remaining 500 Diagnostics

To determine if more data needs to be retrieved, check for the existence of the "next" object under "links".

Data Changes

While the historical data within Clockworks is relatively stable, occasionally this historical data may be changed or even deleted. For example:

A given Asset (Building, Equipment, Point) is no longer required and is deleted rather than just made "In Active".
Analysis parameters where updated for a set of Equipment, and hence the existing Diagnostics that reference the Analysis-Equipment pairs need to be "purged and re-run".
A Task was incorrectly created, and was deleted.

As such, care should be taken when attempting to append new data to previously retrieved data as changes may not be reflected. Due to the relatively small number of Client Assets and Tasks, it is recommended these datasets are retrieved in full when required.

Performance Tuning

Minimize Paging

If a large data request is submitted to the External REST API that requires multiple pages to be returned, when a specific page of data is requested (using the ?page[number] option) to guarantee that there is no duplicated data records returned, the full dataset is generated and then the requested page extracted. As the full dataset generation happens each time a page is requested, this can significantly impact performance, and hence it is more efficient to reduce the size of the request to minimize paging. Possible strategies for reducing the request size include:

Equipment: Request Equipment by Building.
Diagnostics: Request daily Diagnostics by Day, and by Building.
Raw Data: Assuming 5 minute data, request by Day in blocks of 3 Points. (3 * 288 data points per day = 864)
VData: Request by Day in blocks of 1,000 VPoints.

Support

For support related to use of the External REST API, submit requests via the Clockworks Analytics Customer Support Desk.

API Documentation

Introduction

API Initialization

HTTP Verb Usage

Resources

Clients

Buildings

Building Types

Building Variables

Data Sources

Engineering Units

Equipment

Equipment Classes

Equipment Points

Equipment Types

Equipment Variables

Equipment Equipment Variables

Equipment Equipments

Equipment Types Equipment Types

Equipment Types Point Types

Analyses

Diagnostics

Points

Point Classes

Point Types

Raw Data

VPoints

VData