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 NameHeader 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:

  1. GET - simple retrievals

  2. POST - more complex retrievals

  3. PUT - creating entities/records

  4. PATCH - updating entities/records

  5. 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}/buildingsAll Buildings related to the Client.
GET /clients/{id}/buildingTypesAll Building Types related to the Client.
GET /clients/{id}/analyses

All Analyses available to a specified client

GET /clients/{id}/datasourcesAll Data Sources related to the Client.
GET /clients/{id}/clientsProvidedForAll Clients provided with services related to the Client. 

OPTIONS /clients

This Help table.

Response Key
Data TypeAllow 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).

IsActivebooleanYesActive status
ReportThemeString(50)YesClockworks Analytics or Schneider Electric
OrganizationThemeString(50)YesOrganization theme
CountryNameString(50)YesCountry name
ParentOrganizationString(100)YesParent 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. 

RequestReturns

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}/buildingbuildingvariablesValues of all Building Variables assigned to the Building.
GET /buildings/{id}/equipmentpointsAll Equipment Points related to the building.
GET /buildings/{id}/pointsAll Points related to the Building.

OPTIONS /buildings

This Help table.

Response Key
Data TypeAllow Nulls?Description

id

IntegerNoBuilding ID.

BuildingName

String(100)NoBuilding name.

BuildingTypeID

IntegerNoBuilding Type ID.

CID

IntegerNoID of the Client that this Building is assigned to.
AddressString(250)NoBuilding address.
BuildingClassDescriptionString(1000)YesDescription of the categorized Building classification.
BuildingClassIDIntegerNoID of the categorized Building classification.
BuildingClassNameString(50)NoName of the categorized Building classification.
BuildingOwnershipString(50)YesType of ownership the Buildings is under.
BuildingTypeDescriptionString(1000)NoDescription of the specific type under the Building classification.
BuildingTypeNameString(100)NoName of the specific type under the Building classification.
BuildingShapeString(50)YesShape of the Building.
CityString(100)NoBuilding City.
ClientNameString(100)NoClient Name.
ComputersIntegerNoEstimated number of computers in the Building, in range 0-10,000.
CountryNameString(50)YesCountry of the Building.
CountryAlpha2CodeString(2)NoUnique ISO Alpha 2 country code.
DateCreatedISO Date StringNoDate, in UTC, the Building was created in the system.
DateModifiedISO Date StringNoDate, in UTC, the Building was last modified in the system.
DescriptionString(1000)YesDescription of the Building.
EnvelopeGlassPercentageIntegerNoEnvelope glass percentage of the Building, in range 0-100.
FloorsIntegerYesNumber of floors in the Building, in range 1-9999.
IsActiveBitNoTrue (1) if the Building is actively receiving data and running diagnostics in the system, False (0) otherwise.
IsVisibleBitNoTrue (1) if the Building is visible to non-administrative users in the system, False (0) otherwise.
LatitudeDecimal(13,10)YesLatitude of the Building.
LCIDInteger
NoLocale identifier for the Building. 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.
LocationString(250)YesAdditional location information about the Building.
LongitudeDecimal(13,10)YesLongitude of the Building.
MainCoolingSystemString(50)YesType of the main cooling system.
MainHeatingSystemString(50)YesType of the main heating system.
OccupantsIntegerYesEstimated number of Building occupants, in range 1-99,999.
OperatingHoursIntegerNoBuilding operating hours, in range 0-168.
PhoneString(10)YesBuilding phone number (U.S. only).
RoofConstructionString(50)YesType of roof construction.
SASLinkString(100)YesSpace Accounting Software link URL.
SASReferenceIDString(50)YesSpace Accounting Software reference ID.

StateID

IntegerYesThe State ID.
StateNameString(100)YesBuilding state, province, or equivalent.
AreaIntegerNoArea of the Building, in range 0-9,999,999,999.
TimeZoneString(50)NoBuilding time zone.

TimeZoneDisplayName

String(xx)Yes

The time zone display name.

UnitSystemBitNoTrue (1) if the Building data is measured in SI units, False (0) if is measured in IP units.
WebsiteLinkString(100)YesBuilding specific website link URL.

WeatherFileDisplayName

String(150)Yes

Yes, The weather file display name.

WeatherFileGFID

IntegerYes

The building Weather File ID.

YearBuiltIntegerYes4-digit year the Building was built.
ZipString(10)YesZip 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

idIntegerNoBuilding Type ID.
BuildingTypeNameString(100)NoBuilding Type name.
BuildingTypeDescriptionString(1000)NoBuilding 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

idIntegerNoBuilding Variable ID.
BuildingVariableDescriptionString(100)NoBuilding Variable description.
BuildingVariableDisplayNameString(1000)NoBuilding Variable display name.
BuildingVariableNameString(1000)NoBuilding Variable name.
IPDefaultValueIntegerNoIP Engineering Unit default value.
IPEngUnitIDIntegerNoIP Engineering Unit ID.
IPEngUnitsString(50)NoIP Engineering Unit.
SIDefaultValueIntegerNoSI Engineering Unit default value.
SIEngUnitIDIntegerNoSI Engineering Unit ID.
SIEngUnitsString(50)NoSI 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}/pointsAll Points defined for the DataSources.

OPTIONS /datasources

This Help table.

Response Key

Data Type

Allow Nulls?

Description

id

IntegerNoDatasource ID.
BMSInfoIDIntegerYesBMS Information ID.
BMSInfoNameString(100)NoBMS Information name.
CIDIntegerNoClient ID.
DataSourceNameString(100)NoData Source name.

Description

String(1000)YesData Source description.
DTSIDIntegerNoData Transfer Service ID.
DTSNameString(250)NoData Transfer Service name.

Endpoint

String(512)Yes

The BMS info endpoint.

ExtraInfo

String(1000)Yes

Extra info about the BMS.

IncludeInHealthEmails

BooleanNo

Data Source included in automatic health email notifications.

Installer

String(100)Yes

The Data Source installer name or info.

IPListString(500)YesIP List.
IsActiveBooleanNoIs the Data Source active?
IsRealTime BooleanNoIs 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

BooleanNoIs the Data Source integrated?
ReferenceIDString(100)NoData Source Reference ID.

TimeOffset

IntegerNo

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

IntegerNo

Vendor Product ID.

VendorProductRetrievalMethodID

IntegerNo

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

idIntegerNoEngineering Unit ID.
EngUnitsString(100)NoEngineering Unit name.
EngUnitsDescriptionString(1000)NoEngineering Unit description.
DateModifiedISO Date StringNoDate, in UTC, the Engineering Unit was modified in the system.
DateCreatedISO Date StringNoDate, in UTC, the Engineering Unit was created in the system.
MinValueFloating PointNoThe minimum range boundary for the Engineering Unit.
MaxValueFloating PointNoThe 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.
RequestReturns
GET /equipment
All Equipment.
GET /equipment/{id}A piece of Equipment by ID.
GET /equipment/{id}/analysesAll Analyses related to the piece of Equipment.
GET /equipment/{id}/pointsAll Points related to the piece of Equipment.
GET /equipment/{id}/vpointsAll VirtualPoints (i.e., calculated)related to the piece of Equipment.
GET /equipment/{id}/vprepointsAll 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}/equipmentequipmentvariablesValues of all Equipment Variables assigned to the piece of Equipment.
OPTIONS /equipment
This Help table.
Response Key
Data TypeAllow Nulls?Description
idIntegerNoEquipment ID.
BIDIntegerNoID of the Building with which this piece of Equipment is associated.
EquipmentNameString(50)NoEquipment name.
EquipmentLocationString(250)YesAdditional location information about the piece of Equipment.
SerialNumberString(50)YesSerial number of the piece of Equipment.
DescriptionString(1000)YesEquipment description.
EquipmentTypeIDIntegerNoID of the specific type under the Equipment classification.
IsActiveBitNoTrue (1) if the piece of Equipment is actively receiving data and running Diagnostics in the system, False (0) otherwise.
IsVisibleBitNoTrue (1) if the piece of Equipment is visible to non-administrative users in the system, False (0) otherwise.
DateCreatedISO Date StringNoDate, in UTC, the piece of Equipment was created in the system.
DateModifiedISO Date StringNoDate, in UTC, the piece of Equipment was last modified in the system.
ExternalEquipmentTypeNameString(100)YesCustomers external name of the type of the Equipment.
EquipmentNotesString(5000)YesAdditional user notes and information about the Equipment, in HTML.
ManufacturerModelIDIntegerNoManufacturer Model ID.
CMMSReferenceIDString(50)YesCMMS Reference or Asset ID for integration.
CMMSLinkString(100)YesCMMS integration direct link to asset.
CMMSLocationIDString(50)YesCMMS asset location.
CMMSSiteIDString(50)YesCMMS 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}/equipmenttypesAll 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 TypeAllow Nulls?Description
idIntegerNoEquipment Class ID.
EquipmentClassNameString(50)NoName of the Equipment Class.
EquipmentClassDescriptionString(50)NoName 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}/equipmentpointsAll Equipment Points related to the building.
Response Key
Data TypeAllow Nulls?Description
EIDIntegerNoEquipment ID.
PIDIntegerNoPoint ID.
EPIDIntegerNoID 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}/pointtypesAll Point Types for the related Equipment Type.

OPTIONS /equipmenttypes

This Help table.

Response Key

Data Type

Allow Nulls?

Description

idIntegerNoEquipment Type ID.
EquipmentTypeNameString(100)NoName of the Equipment Type.
EquipmentTypeDescriptionString(max)NoDescription of the Equipment Type.
EquipmentClassIDIntegerNoID 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

idIntegerNoEquipment Variable ID.
EquipmentVariableDescriptionString(100)NoEquipment Variable description.
EquipmentVariableDisplayNameString(1000)NoEquipment Variable display name.
EquipmentVariableNameString(1000)NoEquipment Variable name.
IPDefaultValueIntegerNoIP Engineering Unit default value.
IPEngUnitIDIntegerNoIP Engineering Unit ID.
IPEngUnitsString(50)NoIP Engineering Unit.
SIDefaultValueIntegerNoSI Engineering Unit default value.
SIEngUnitIDIntegerNoSI Engineering Unit ID.
SIEngUnitsString(50)NoSI 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 KeyData TypeRequired?Description

Returns

POST /equipmentequipments

CIDArray of IntegerYes

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


BIDArray of IntegerYes

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.

AssignedEquipmentTypeNameStringNoName 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.

PointTypeNameStringNoName 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 /analysesAll Analysis resources
GET /analyses/{id}An Analysis by ID. The Analysis ID must be available to the Subscriber.
OPTIONS
This Help table.
Request
ReturnsAllow Nulls?Description
AID
IntegerNoAnalysis ID.
AnalysisNameString(150)NoAnalysis name.
AnalysisDescriptionString(5000)YesDescription of the Analysis.
AnalysisTeaserString(1000)YesSummarized 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.
RequestPayload KeyData TypeRequired?DescriptionReturns
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.

BIDArray of IntegerNoAn array of Client Building IDs.
EIDArray of IntegerNoAn array ofClient Equipment IDs.
AIDArray of IntegerNoAn array ofAnalysis IDs.
ECIDArray of IntegerNoAn array ofEquipment Class IDs.
StartDateISO Date StringYesStart Date, in format "YYYY-MM-DD".
EndDateISO Date StringYesEnd Date, in format "YYYY-MM-DD".
AnalysisIntervalStringYesAnalysis Interval - "HalfDay", "Daily", "Weekly", or "Monthly".
OPTIONS /diagnostics
-This Help table.
Response KeyData TypeAllow Nulls?Description
AEIDIntegerNoAnalysis Equipment relationship pair ID. Unique per AnalysisInterval and StartDate.
AIDIntegerNoAnalysis ID.
AnalysisNameStringNoAnalysis Name.
BIDIntegerNoBuilding ID.
ComfortPriorityDoubleNoComfort Priority (0-10).
CostSavingsFloatNoAvoidable Costs, in Building Currency.
EnergyPriorityDoubleNoEnergy Priority (0-10).
EIDIntegerNoEquipment ID.
EquipmentNameStringNoName of the piece of Equipment.
MaintenancePriorityDoubleNoMaintenance Priority (0-10).
NotesSummaryStringNoDiagnostic summary details.
StartDateISO Date StringNo

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.

DiagnosticHyperlinkStringNoDiagnostic 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. 

RequestPayload KeyData TypeRequired?DescriptionReturns
POST /pointsPIDArray of IntegersYesArray of Point IDs.Description of the Points.
OPTIONS /points
-This Help table.
Response Key
Data TypeAllow Nulls?Description
idIntegerNoPoint ID.
PointNameString(50)NoPoint Name.
PointTypeIDIntegerNoID of the categorized Point type.
PointTypeNameString(50)NoName of the specific type under the Point classification.
PointClassIDIntegerNoID of the categorized Point classification.
PointClassNameString(50)NoName of the categorized Point classification.
DataSourceIDIntegerNoData source ID.
DateCreatedISO Date StringNo

Date, in UTC, the Point was created in the system.

DateModifiedISO Date StringNoDate, in UTC, the Point was last modified in the system.
TimeZoneString(50)NoPoints timezone (TimeZoneInfo) ID. Used for rawdata ISO Date String timestamp conversions from UTC.
ReferenceIDString(250)NoUnique reference identifier for the Point on a BMS data source.
SamplingIntervalIntegerNoInterval, in minutes, (> 0) in which data is extracted from the clients end and sent to Default = 5 minutes.
RelPctErrorDoubleNoRelative 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.
IsSubscriptionBasedBitNoTrue (1) if the Point is subscription based and the data transfer service is configured to use optimized polling for this Point, False (0) otherwise.
IsActiveBitNo

True (1) if the Point is actively receiving data and Diagnostics requiring this Point as input are running in the system, False (0) otherwise.

PowerDoubleNoIncoming power raw data modifier.
MultiplyDoubleNoIncoming multiply raw data modifier.
AdditionDoubleNoIncoming addition raw data modifier.
PowerMatlabDoubleNoAnalysis input power raw data modifier.
MultiplyMatlabDoubleNoAnalysis input multiply raw data modifier.
AdditionMatlabDoubleNoAnalysis 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 /pointclassesAll Point Classes
GET /pointclasses/{id}A Point Class by ID.
GET /pointclasses/{id}/pointtypesAll Point Types related to the Point Class.
OPTIONS /pointclasses
This Help table.
Response
ReturnsAllow Nulls?Description
ID
IntegerNoPoint Class ID.
PointClassNameString(50)NoPoint Class name.
PointClassDescriptionString(50)NoDescription of the Point Class.
IPEngUnitIDIntegerNoIP Engineering Unit ID.
SIEngUnitIDIntegerNoSI 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 /pointtypesAll 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
ReturnsAllow Nulls?Description
ID
IntegerNoPoint Type ID.
EnabledForArray of StringsNoWhat the Point Type is enabled for: "Point", "VPoint", and/or "VPrePoint".
DisplayNameString(50)NoDisplay Name of the Point Type.
PointTypeNameString(50)No

Name of the Point Type.

PointTypeDescriptionString(100)YesDescription of the Point Type.
PointClassIDIntegerNoID 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.
RequestPayload KeyData TypeRequired?DescriptionReturns
POST /rawdataCIDArray of IntegerYesA single element array of a Client ID.Raw Data for by the given criteria.
PIDArray of IntegersYesArray of Point IDs.
StartDateISO Date StringYesUTC Start Date, in format "YYYY-MM-DD".
EndDateISO Date StringYesUTC End Date, in format "YYYY-MM-DD".
OPTIONS /rawdata-This Help table.
Response Key
Data Type
Allow Nulls?Description
IDInteger
NoRaw 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).
PIDInteger
NoPoint ID.
EIDInteger
NoEquipment ID. If the Point is shared across multiple pieces of Equipment, then this ID is for the primary related piece of Equipment.
DateLoggedUTCISO Date String
NoDate, in UTC, the Point value was logged.
DateLoggedLocalISO Date String
NoDate, in local timezone, the Point value was logged.
RawValueString
No

Raw value.

Note: Large RawValue numeric data value may be returned using scientific notation.

PointNameString(50)
NoPoint name.
BuildingSettingBasedEngUnitsString(50)
NoEngineering 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.
RequestPayload KeyData TypeRequired?DescriptionReturns
POST /vpoints

EID

Array of IntegersYesArray of Equipment IDs.Virtual Points by the given criteria.
AIDArray of IntegersYesArray of Analysis IDs.
OPTIONS /vpoints-This Help table.
Response KeyData TypeAllow Nulls?Description
idIntegerNoVirtual Point ID.
AIDIntegerNoAnalysis ID.
EIDIntegerNoEquipment ID.
DateCreatedISO Date StringNoDate, 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. 
PointTypeIDIntegerNoID 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.
RequestPayload KeyData TypeRequired?DescriptionReturns
POST /vdataCIDArray of IntegerYesA single element array of a Client ID.Return Virtual Point data that meets the Payload criteria.
VPIDArray of IntegersYesArray of Virtual Point IDs.
StartDateISO Date StringYesStart Date in format "YYYY-MM-DD".
EndDateISO Date StringYesEnd Date in format "YYYY-MM-DD".
AnalysisIntervalStringYesInterval - "HalfDay", "Daily", "Weekly", or "Monthly".
OPTIONS /vdata-This Help table.
Response KeyData TypeAllow Nulls?Description
IDIntegerNoVirtual 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).
VPIDIntegerNoID of the Virtual Point to which this piece of data relates.
StartDateISO Date StringNoStart 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. 
RawValueStringYes

Raw value that was produced for this Analysis and Virtual Point.

Note: Large RawValue numeric data values may be returned using scientific notation.

RelPctError


DoubleNo

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


StatusArray of StringNoArray 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".

CIDArray of IntegersNoArray of Client IDs.
BIDArray of IntegersNoArray of Building IDs.
EIDArray of IntegersNoArray of Equipment IDs.
HasWorkOrderIDBooleanNoFlag to filter by with or without work orders in the WorkOrderID field.
WorkOrderIDArray of StringNoArrays of work order IDs.
HasGenerateWorkOrderBooleanNoFlag to filter HasGenerateWorkOrder field.

POST /taskrecords

AEID

Array of Integers

Yes

Array of Diagnostic IDs.

All Tasks by AEID(s).


HasWorkOrderIDBooleanNoFlag to filter by with or without work orders in the WorkOrderID field.

WorkOrderIDArray of StringNoArrays of work order IDs.

HasGenerateWorkOrderBooleanNoFlag to filter HasGenerateWorkOrder field.

OPTIONS /taskrecords

-

This Help table.

Response KeyData TypeAllow 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.

CIDIntegerNoID of the associated client.

BID

Integer

No

ID of the associated Building.

EID

Integer

No

ID of the associated piece of Equipment.

AIDIntegerNoID 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.

TaskHyperlinkStringNoTask link to Classic Task's Page.
AdditionalSavingsString(50)Yes
HasGenerateWorkOrderBooleanNoFlag 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:

  1. POST {url}/core-diag/diagnostics - returns the first 1,000 Diagnostics
  2. POST {url}/core-diag/diagnostics?page[number]=1 - returns next 1,000 Diagnostics
  3. 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:

  1. Equipment: Request Equipment by Building.
  2. Diagnostics: Request daily Diagnostics by Day, and by Building.
  3. Raw Data: Assuming 5 minute data, request by Day in blocks of 3 Points. (3 * 288 data points per day = 864)
  4. 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.