The BUS Methodology API endpoints

All of the API endpoints for each object type in the API are listed here along with the methods that can be called on those methods, and some usage guidance.


accounts

Overview

These endpoints provide access to the user accounts objects in the BUS methodology database.

Permissions

Users have read/write access to accounts within their partner group, and they can delete accounts.

Endpoints

GET /api/accounts Retrieve multiple account objects
No Parameters
POST /api/accounts Create multiple account objects
Parameter Type Required Other Attributes
email string True unique: True
name string True
partner objectid True data_relation: {'resource': 'partners', 'field': '_id', 'embeddable': True}
phoneNumber string True
status string False allowed: ['INVITED', 'ACTIVE']
readonly: True
GET /api/accounts/{_id} Retrieve an account object
Path Parameter Type Required Other Attributes
_id string True
PATCH /api/accounts/{_id} Update an account object
Path Parameter Type Required Other Attributes
_id string True
Parameter Type Required Other Attributes
email string False unique: True
name string False
partner objectid False data_relation: {'resource': 'partners', 'field': '_id', 'embeddable': True}
phoneNumber string False
status string False allowed: ['INVITED', 'ACTIVE']
readonly: True
DELETE /api/accounts/{_id} Delete an account object
Path Parameter Type Required Other Attributes
_id string True

benchmarks

Overview

These endpoints provide access to the benchmark objects in the BUS methodology database.

A benchmark is essentially a set of object id's for surveys that are part of a benchmark set.

Permissions

Only 'Platform Architect' users can write to this resource. All other user types have read access.

Endpoints

GET /api/benchmarks Retrieve multiple benchmark objects
No Parameters
POST /api/benchmarks Create multiple benchmark objects
Parameter Type Required Other Attributes
country string True
name string True
surveyType string True
surveys list False schema: {'type': 'objectid', 'data_relation': {'resource': 'surveys', 'field': '_id', 'embeddable': False}}
year number True
GET /api/benchmarks/{_id} Retrieve a benchmark object
Path Parameter Type Required Other Attributes
_id string True
PATCH /api/benchmarks/{_id} Update a benchmark object
Path Parameter Type Required Other Attributes
_id string True
Parameter Type Required Other Attributes
country string False
name string False
surveyType string False
surveys list False schema: {'type': 'objectid', 'data_relation': {'resource': 'surveys', 'field': '_id', 'embeddable': False}}
year number False

occupant_responses

Overview

These endpoints provide access to the occupant response objects in the BUS methodology database.

An occupant response object exists for every survey response obtained.

Permissions

'Account Managers' are prohibited from writing to this resource. All other user types have read/write access.

Row level access is defined by the partner under which a user account exists.

Endpoints

GET /api/occupant_responses Retrieve multiple occupant response objects
No Parameters
POST /api/occupant_responses Create multiple occupant response objects
Parameter Type Required Other Attributes
questions list False schema: {'type': 'dict', 'schema': {'name': {'type': 'string', 'required': True}, 'response': {'required': True}}}
survey objectid False data_relation: {'resource': 'surveys', 'field': '_id', 'embeddable': True}
GET /api/occupant_responses/{_id} Retrieve an occupant response object
Path Parameter Type Required Other Attributes
_id string True
PATCH /api/occupant_responses/{_id} Update an occupant response object
Path Parameter Type Required Other Attributes
_id string True
Parameter Type Required Other Attributes
questions list False schema: {'type': 'dict', 'schema': {'name': {'type': 'string', 'required': True}, 'response': {'required': True}}}
survey objectid False data_relation: {'resource': 'surveys', 'field': '_id', 'embeddable': True}

partners

Overview

These endpoints provide access to the partner objects in the BUS methodology database.

Users will belong to one partner. Users related to a partner are able to view and edit surveys that the partner has been entitled to have access to.

Permissions

Users have read/write access to their own partner.

Endpoints

GET /api/partners Retrieve multiple partner objects
No Parameters
POST /api/partners Create multiple partner objects
Parameter Type Required Other Attributes
activePartner boolean False default: True
admin boolean False default: False
invoiceContact dict False schema: {'name': {'type': 'string'}, 'address': {'type': 'dict', 'schema': {'addressLines': {'type': 'string'}, 'postcode': {'type': 'string'}, 'country': {'type': 'string'}}}, 'phoneNumber': {'type': 'string'}, 'email': {'type': 'string'}}
invoiceContact.address dict False schema: {'addressLines': {'type': 'string'}, 'postcode': {'type': 'string'}, 'country': {'type': 'string'}}
invoiceContact.address.addressLines string False
invoiceContact.address.country string False
invoiceContact.address.postcode string False
invoiceContact.email string False
invoiceContact.name string False
invoiceContact.phoneNumber string False
name string True unique: True
surveys list False schema: {'type': 'objectid', 'data_relation': {'resource': 'surveys', 'field': '_id', 'embeddable': True}}
default: []
GET /api/partners/{_id} Retrieve a partner object
Path Parameter Type Required Other Attributes
_id string True
PATCH /api/partners/{_id} Update a partner object
Path Parameter Type Required Other Attributes
_id string True
Parameter Type Required Other Attributes
activePartner boolean False default: True
admin boolean False default: False
invoiceContact dict False schema: {'name': {'type': 'string'}, 'address': {'type': 'dict', 'schema': {'addressLines': {'type': 'string'}, 'postcode': {'type': 'string'}, 'country': {'type': 'string'}}}, 'phoneNumber': {'type': 'string'}, 'email': {'type': 'string'}}
invoiceContact.address dict False schema: {'addressLines': {'type': 'string'}, 'postcode': {'type': 'string'}, 'country': {'type': 'string'}}
invoiceContact.address.addressLines string False
invoiceContact.address.country string False
invoiceContact.address.postcode string False
invoiceContact.email string False
invoiceContact.name string False
invoiceContact.phoneNumber string False
name string False unique: True
surveys list False schema: {'type': 'objectid', 'data_relation': {'resource': 'surveys', 'field': '_id', 'embeddable': True}}
default: []

questions

Overview

These endpoints provide access to the questions objects in the BUS methodology database.

This set of questions defines all of the standard questions asked in BUS surveys, and stores the history of how these question definitions have changed.

Permissions

Users have read-only access to the questions list.

Endpoints

GET /api/questions Retrieve multiple question objects
No Parameters
POST /api/questions Create multiple question objects
Parameter Type Required Other Attributes
choices dict False keyschema: {'type': 'string', 'regex': '\\d+'}
group string False
max number False nullable: True
maxValue string False
min number False nullable: True
minValue string False
name string True
oldCode string False
questionSets list False schema: {'type': 'string'}
range number False nullable: True
min: 1
title string True
type string True allowed: ['boolean', 'shortText', 'paragraph', 'integer', 'time', 'date', 'singleChoice', 'multipleChoice', 'leftHandScale', 'rightHandScale', 'centeredScale']
GET /api/questions/{_id} Retrieve a question object
Path Parameter Type Required Other Attributes
_id string True
PATCH /api/questions/{_id} Update a question object
Path Parameter Type Required Other Attributes
_id string True
Parameter Type Required Other Attributes
choices dict False keyschema: {'type': 'string', 'regex': '\\d+'}
group string False
max number False nullable: True
maxValue string False
min number False nullable: True
minValue string False
name string False
oldCode string False
questionSets list False schema: {'type': 'string'}
range number False nullable: True
min: 1
title string False
type string False allowed: ['boolean', 'shortText', 'paragraph', 'integer', 'time', 'date', 'singleChoice', 'multipleChoice', 'leftHandScale', 'rightHandScale', 'centeredScale']
GET /api/questions/{name} Retrieve a question object
Parameter Type Required Other Attributes
name string True

survey_statistics

Overview

These endpoints provide access to the survey statistics objects in the BUS methodology database.

A survey statistics object contains statistics relating to the responses for each questions that was asked.

Adding benchmark={benchmark._id} will cause the api to compare this survey to a benchmark and create relevant statistics.

Permissions

Row level access to most endpoints is defined by the partner under which a user account exists.

Usage tips

specify benchmark={benchmark._id} to receive the survey including comparison with a benchmark.

Endpoints

GET /api/survey_statistics Retrieve multiple survey statistics objects
Path Parameter Type Required Other Attributes
benchmark string False Only on item GET requests - see description for detail
POST /api/survey_statistics Create multiple survey statistics objects
Path Parameter Type Required Other Attributes
benchmark string False Only on item GET requests - see description for detail
Parameter Type Required Other Attributes
commentsChecked boolean False default: False
responseCount number False nullable: True
statistics dict False keysrules: {'type': 'string', 'regex': '[A-Za-z0-9]+'}
valuesrules: {'type': 'dict', 'schema': {'histogram': {'type': 'dict', 'schema': {'values': {'type': 'list', 'schema': {'type': 'number'}}, 'bins': {'type': 'list', 'schema': {'type': ['number', 'boolean']}}}}, 'mean': {'type': 'number'}, 'median': {'type': 'number'}, 'variance': {'type': 'number'}, 'responseCount': {'type': 'number', 'nullable': True, 'min': 0}}}
survey objectid True data_relation: {'resource': 'surveys', 'field': '_id', 'embeddable': True}
unique: True
GET /api/survey_statistics/{_id} Retrieve a survey statistics object
Path Parameter Type Required Other Attributes
_id string True
benchmark string False Only on item GET requests - see description for detail
PATCH /api/survey_statistics/{_id} Update a survey statistics object
Path Parameter Type Required Other Attributes
_id string True
benchmark string False Only on item GET requests - see description for detail
Parameter Type Required Other Attributes
commentsChecked boolean False default: False
responseCount number False nullable: True
statistics dict False keysrules: {'type': 'string', 'regex': '[A-Za-z0-9]+'}
valuesrules: {'type': 'dict', 'schema': {'histogram': {'type': 'dict', 'schema': {'values': {'type': 'list', 'schema': {'type': 'number'}}, 'bins': {'type': 'list', 'schema': {'type': ['number', 'boolean']}}}}, 'mean': {'type': 'number'}, 'median': {'type': 'number'}, 'variance': {'type': 'number'}, 'responseCount': {'type': 'number', 'nullable': True, 'min': 0}}}
survey objectid False data_relation: {'resource': 'surveys', 'field': '_id', 'embeddable': True}
unique: True

surveys

Overview

These endpoints provide access to the survey objects in the BUS methodology database.

A survey object defines the high-level information for a survey including the list of questions that were asked.

Adding partner={partner._id} will cause the api to filter _ids of surveys to those viewable by the partner provided.

Permissions

Row level access to most endpoints is defined by the partner under which a user account exists.

Endpoints

GET /api/surveys Retrieve multiple survey objects
No Parameters
POST /api/surveys Create multiple survey objects
Parameter Type Required Other Attributes
buildingAddress dict False schema: {'addressLines': {'type': 'string'}, 'postcode': {'type': 'string'}, 'country': {'type': 'string'}}
buildingAddress.addressLines string False
buildingAddress.country string False
buildingAddress.postcode string False
buildingData dict False schema: {'yearConstructed': {'type': 'number', 'nullable': True}, 'grossInternalArea': {'type': 'string'}, 'grossInternalAreaUnit': {'type': 'string', 'allowed': ['sqmeters', 'sqfeet']}, 'netInternalArea': {'type': 'string'}, 'netInternalAreaUnit': {'type': 'string', 'allowed': ['sqmeters', 'sqfeet']}, 'storeys': {'type': 'number', 'nullable': True}, 'buildingType': {'type': 'string'}, 'glazingType': {'type': 'string'}, 'glazingRatio': {'type': 'string'}, 'workStyle': {'type': 'string'}, 'displayEnergyCertificate': {'type': 'string', 'allowed': ['A+', 'A', 'B', 'C', 'D', 'E', 'F', 'G', 'Unknown']}, 'energyPerformanceCertificate': {'type': 'string', 'allowed': ['A+', 'A', 'B', 'C', 'D', 'E', 'F', 'G', 'Unknown']}, 'sustainabilityLabellingSchemes': {'type': 'list', 'schema': {'type': 'string'}}, 'sustainabilityRatingsAchieved': {'type': 'string'}, 'ventilationType': {'type': 'string'}, 'heatingType': {'type': 'string'}, 'coolingType': {'type': 'string'}, 'lightingType': {'type': 'string'}, 'windowControl': {'type': 'string'}}
buildingData.buildingType string False
buildingData.coolingType string False
buildingData.displayEnergyCertificate string False allowed: ['A+', 'A', 'B', 'C', 'D', 'E', 'F', 'G', 'Unknown']
buildingData.energyPerformanceCertificate string False allowed: ['A+', 'A', 'B', 'C', 'D', 'E', 'F', 'G', 'Unknown']
buildingData.glazingRatio string False
buildingData.glazingType string False
buildingData.grossInternalArea string False
buildingData.grossInternalAreaUnit string False allowed: ['sqmeters', 'sqfeet']
buildingData.heatingType string False
buildingData.lightingType string False
buildingData.netInternalArea string False
buildingData.netInternalAreaUnit string False allowed: ['sqmeters', 'sqfeet']
buildingData.storeys number False nullable: True
buildingData.sustainabilityLabellingSchemes list False schema: {'type': 'string'}
buildingData.sustainabilityRatingsAchieved string False
buildingData.ventilationType string False
buildingData.windowControl string False
buildingData.workStyle string False
buildingData.yearConstructed number False nullable: True
createdBy objectid False data_relation: {'resource': 'partners', 'field': '_id', 'embeddable': True}
name string False
occupantCount integer False nullable: True
participantCount integer False nullable: True
questions list False schema: {'type': 'dict', 'schema': {'name': {'type': 'string', 'required': True}, 'type': {'type': 'string', 'allowed': ['boolean', 'shortText', 'paragraph', 'integer', 'time', 'date', 'singleChoice', 'multipleChoice', 'leftHandScale', 'rightHandScale', 'centeredScale'], 'required': True}, 'group': {'type': 'string'}, 'title': {'type': 'string', 'required': True}, 'oldCode': {'type': 'string'}, 'questionSets': {'type': 'list', 'schema': {'type': 'string'}}, 'min': {'type': 'number', 'nullable': True}, 'max': {'type': 'number', 'nullable': True}, 'range': {'type': 'number', 'nullable': True, 'min': 1}, 'minValue': {'type': 'string'}, 'maxValue': {'type': 'string'}, 'choices': {'type': 'dict', 'keysrules': {'type': 'string', 'regex': '\\d+'}}, '_id': {'type': 'objectid', 'data_relation': {'resource': 'questions', 'field': '_id', 'embeddable': False}}, '_version': {'type': 'integer'}}}
surveyDate number False nullable: True
surveyMethod string False
surveyType string False allowed: ['domestic', 'non-domestic', 'transient', 'wellbeing']
GET /api/surveys/{_id} Retrieve a survey object
Path Parameter Type Required Other Attributes
_id string True
PATCH /api/surveys/{_id} Update a survey object
Path Parameter Type Required Other Attributes
_id string True
Parameter Type Required Other Attributes
buildingAddress dict False schema: {'addressLines': {'type': 'string'}, 'postcode': {'type': 'string'}, 'country': {'type': 'string'}}
buildingAddress.addressLines string False
buildingAddress.country string False
buildingAddress.postcode string False
buildingData dict False schema: {'yearConstructed': {'type': 'number', 'nullable': True}, 'grossInternalArea': {'type': 'string'}, 'grossInternalAreaUnit': {'type': 'string', 'allowed': ['sqmeters', 'sqfeet']}, 'netInternalArea': {'type': 'string'}, 'netInternalAreaUnit': {'type': 'string', 'allowed': ['sqmeters', 'sqfeet']}, 'storeys': {'type': 'number', 'nullable': True}, 'buildingType': {'type': 'string'}, 'glazingType': {'type': 'string'}, 'glazingRatio': {'type': 'string'}, 'workStyle': {'type': 'string'}, 'displayEnergyCertificate': {'type': 'string', 'allowed': ['A+', 'A', 'B', 'C', 'D', 'E', 'F', 'G', 'Unknown']}, 'energyPerformanceCertificate': {'type': 'string', 'allowed': ['A+', 'A', 'B', 'C', 'D', 'E', 'F', 'G', 'Unknown']}, 'sustainabilityLabellingSchemes': {'type': 'list', 'schema': {'type': 'string'}}, 'sustainabilityRatingsAchieved': {'type': 'string'}, 'ventilationType': {'type': 'string'}, 'heatingType': {'type': 'string'}, 'coolingType': {'type': 'string'}, 'lightingType': {'type': 'string'}, 'windowControl': {'type': 'string'}}
buildingData.buildingType string False
buildingData.coolingType string False
buildingData.displayEnergyCertificate string False allowed: ['A+', 'A', 'B', 'C', 'D', 'E', 'F', 'G', 'Unknown']
buildingData.energyPerformanceCertificate string False allowed: ['A+', 'A', 'B', 'C', 'D', 'E', 'F', 'G', 'Unknown']
buildingData.glazingRatio string False
buildingData.glazingType string False
buildingData.grossInternalArea string False
buildingData.grossInternalAreaUnit string False allowed: ['sqmeters', 'sqfeet']
buildingData.heatingType string False
buildingData.lightingType string False
buildingData.netInternalArea string False
buildingData.netInternalAreaUnit string False allowed: ['sqmeters', 'sqfeet']
buildingData.storeys number False nullable: True
buildingData.sustainabilityLabellingSchemes list False schema: {'type': 'string'}
buildingData.sustainabilityRatingsAchieved string False
buildingData.ventilationType string False
buildingData.windowControl string False
buildingData.workStyle string False
buildingData.yearConstructed number False nullable: True
createdBy objectid False data_relation: {'resource': 'partners', 'field': '_id', 'embeddable': True}
name string False
occupantCount integer False nullable: True
participantCount integer False nullable: True
questions list False schema: {'type': 'dict', 'schema': {'name': {'type': 'string', 'required': True}, 'type': {'type': 'string', 'allowed': ['boolean', 'shortText', 'paragraph', 'integer', 'time', 'date', 'singleChoice', 'multipleChoice', 'leftHandScale', 'rightHandScale', 'centeredScale'], 'required': True}, 'group': {'type': 'string'}, 'title': {'type': 'string', 'required': True}, 'oldCode': {'type': 'string'}, 'questionSets': {'type': 'list', 'schema': {'type': 'string'}}, 'min': {'type': 'number', 'nullable': True}, 'max': {'type': 'number', 'nullable': True}, 'range': {'type': 'number', 'nullable': True, 'min': 1}, 'minValue': {'type': 'string'}, 'maxValue': {'type': 'string'}, 'choices': {'type': 'dict', 'keysrules': {'type': 'string', 'regex': '\\d+'}}, '_id': {'type': 'objectid', 'data_relation': {'resource': 'questions', 'field': '_id', 'embeddable': False}}, '_version': {'type': 'integer'}}}
surveyDate number False nullable: True
surveyMethod string False
surveyType string False allowed: ['domestic', 'non-domestic', 'transient', 'wellbeing']
GET /api/surveys/{_id}/access_token Retrieve a shareable long term access token for this survey
Path Parameter Type Required Other Attributes
_id string True
GET /api/surveys/{_id}/occupant_responses_excel Retrieve the last submitted excel proforma for this survey
Path Parameter Type Required Other Attributes
POST /api/surveys/{_id}/occupant_responses_excel Submit an excel proforma for this survey
Path Parameter Type Required Other Attributes
Parameter Type Required Other Attributes
file files True
GET /api/surveys/{_id}/occupant_responses_excel/template Retrieve the template proforma for this survey
Path Parameter Type Required Other Attributes