- Technical support

For Software developers

First published 8th April 2015, last updated 6th April 2016.

Alan Smith

Alan Smith

NBS Labs manager

The data within the BIM Toolkit is documented to a common schema and API access to this information is available. In this article, NBS Labs Manager Alan Smith introduces software developers to these capabilities.

Introduction

The BIM Toolkit provides a unified classification system and clear levels of detail and information for over 5,000 construction objects. It also offers the ability to create plans of work to assign deliverables to project participants. All of this data can be exported and verified using innovative technologies developed with the BIM Academy to identify that the right information has been provided at the right time in the project lifecycle.

Right from the start of the BIM Toolkit software development cycle, we were thinking about how we could make this plan of work data accessible to other software providers so that innovative solutions can be developed using our data schema.

The areas of the toolkit we thought the industry would benefit most from were:

  • The data within a project plan of work - such as tasks, deliverables, participants and project meta data
  • The level of definition templates
  • The new unified classification system

dpow Schema

The plan of work can be exported to a number of formats, offering the flexibility to use project data in a number of ways. The formats available are Microsoft Excel, COBie, IFC and dpow. Dpow is an export format we developed with BIM Academy to facility the conversion of digital plans of work to COBie and IFC format for verification.

The dpow file is intended to be used to digitally archive or back up projects, or to be used as a template to create a new project. For example, a dpow file could be sent electronically to bidders or a new project lead and used to create a new project. In addition, the file can also be used to transfer information for use in 3rd party platforms.

dpow schema

Class diagram of the dpow schema

The structure of the object model is fairly simple. A plan of work comprises of a number of project stages, which in turn have collections of roles, tasks and deliverables and their classification(s). Deliverables are separated in to Spaces, Assets and Assemblies so that they can easily be translated in to their COBie equivalents.

The dpow file itself is a JSON file, an open format that is easily readable by software applications using open source libraries, such as Json.NET. Alternatively, BIM Academy have released an XbimExchange package as part of the xBIM software development kit (https://xbim.codeplex.com/), which provides an easy to use dpow object model, serialization and deserialization methods and code to convert to and from COBie and IFC.

Syndication of LOD and LOI information

Linking to object definition pages

We wanted 3rd parties to be able to quickly link to our level of detail and level of information pages. To facilitate this, we offer a public URL with a few query string parameters to customise the output.

https://toolkit.thenbs.com/Definitions/uniclass2015_code?type=view_type&detailLevel=banding

Accepted arguments:

type

  • 'lod' to display level of detail
  • 'loi' to display level of information

detailLevel

  • Typical LOD and LOI bandings range from 2-6

For example,

https://toolkit.thenbs.com/definitions/Ss_30_40_95_40/?type=lod&detailLevel=2

Embedding an object definition within an iframe

For those looking for a bit more customisation or the ability to embed object definitions in to their own website, we would recommend linking to our object definition pages via an iframe. Alternatively, JavaScript may be added to a page to launch the definition in a new window.

<iframe style="width:600px;height:450px;border:1px solid black;" src="https://toolkit.thenbs.com/definitions/Ss_30_40_95_40/?type=lod&detailLevel=5"></iframe>

Try it out,

Classification:

Type:

Banding:

Syndicating Object Definitions

The most recent release of the BIM Toolkit introduced the ability to syndicate the list of BIM Toolkit Object Definitions within your website. The widget displays a high level A-Z summary of the available object definitions, then allows users to drill down and see the full list of definitions.

To get the widget running on your website, simply insert the following HTML snippet:

<!-- Syndication code starts here -->

<!-- Include required JavaScript files -->
<script src="//code.jquery.com/jquery-1.12.0.min.js"></script>
<script src="//cdn.datatables.net/1.10.10/js/jquery.dataTables.min.js"></script>
<script src="//cdn.datatables.net/responsive/2.0.1/js/dataTables.responsive.min.js"></script>
<script id="btk_syndication-script" src="https://toolkit.thenbs.com/scripts/pdt-syndication.js"></script>
<!--[if lte IE 9]>
    <script type='text/javascript' src='//cdnjs.cloudflare.com/ajax/libs/jquery-ajaxtransport-xdomainrequest/1.0.3/jquery.xdomainrequest.min.js'></script>
<![endif]-->

<!-- Include required CSS files -->
<link href="https://toolkit.thenbs.com/content/css/pdt-syndication.css" type="text/css" rel="stylesheet" />
<link rel="stylesheet" href="https://maxcdn.bootstrapcdn.com/font-awesome/4.5.0/css/font-awesome.min.css" />
<link href="//cdn.datatables.net/1.10.10/css/jquery.dataTables.min.css" type="text/css" rel="stylesheet" />
<link href="//cdn.datatables.net/responsive/2.0.1/css/responsive.dataTables.min.css" type="text/css" rel="stylesheet" />

<!-- Include required HTML -->
<div id="btk_syndicator">
    <p>Loading level-2 BIM definitions...</p>
</div>

<script>
    btkjQuery(function () {
        btkjQuery('#btk_syndicator').showPDTs();
    });
</script>

<!-- Syndication code ends -->

Try it out:

Loading Uniclass2015...

Syndicating Uniclass2015

It is also possible to syndicate a Uniclass2015 widget to your website. The widget allows searching, filtering and sorting of classification codes.

To get the widget running on your website, simply insert the following HTML snippet:

<!-- Syndication code starts here -->

<!-- Include required JavaScript files -->
<script src="//code.jquery.com/jquery-1.12.0.min.js"></script>
<script src="//cdn.datatables.net/1.10.10/js/jquery.dataTables.min.js"></script>
<script src="//cdn.datatables.net/responsive/2.0.1/js/dataTables.responsive.min.js"></script>
<script id="btk_syndication-script" src="https://toolkit.thenbs.com/scripts/classification-syndication.js"></script>
<!--[if lte IE 9]>
    <script type='text/javascript' src='//cdnjs.cloudflare.com/ajax/libs/jquery-ajaxtransport-xdomainrequest/1.0.3/jquery.xdomainrequest.min.js'></script>
<![endif]-->

<!-- Include required CSS files -->
<link href="https://toolkit.thenbs.com/content/css/classification-syndication.css" type="text/css" rel="stylesheet" />
<link rel="stylesheet" href="https://maxcdn.bootstrapcdn.com/font-awesome/4.5.0/css/font-awesome.min.css" />
<link href="//cdn.datatables.net/1.10.10/css/jquery.dataTables.min.css" type="text/css" rel="stylesheet" />
<link href="//cdn.datatables.net/responsive/2.0.1/css/responsive.dataTables.min.css" type="text/css" rel="stylesheet" />

<!-- Include required HTML -->
<div id="btk_classifications">
    <p>Loading Uniclass2015...</p>
</div>

<script>
    btkjQuery(function () {
        btkjQuery('#btk_classifications').showClassifications();
    });
</script>

<!-- Syndication code ends -->

Try it out:

Loading level-2 BIM definitions...

BIM Toolkit API

We also wanted to offer 3rd parties access to a REST API to query and navigate our unified classification system, and programmatically obtain level of information properties.

Overview

The URL of the API is https://toolkit-api.thenbs.com

BIM Toolkit API

BIM Toolkit API

The API exposes methods to query the Uniclass2015 classification system, obtain object definitions and query BIM Toolkit property definitions

The Uniclass2015 API endpoint exposes 3 methods.

  • A method to query the Uniclass2015 classification system:


    definitions/uniclass2015/{notation}/{depth}

    {notation} - a node of the classification tree, for example Ss_70

    {depth} - the number of branches under the notation to return

  • A method to get the ancestors of a given Uniclass2015 notation (which provides a way of displaying a breadcrumb trail in you application):


    definitions/uniclass2015/ancestors/{notation}

    {notation} - a node of the classification tree, for example Ss_30_40_95_40

  • A method to get a specific LOI banding for an object, which will return the property set that must be completed for the object to pass verification:


    definitions/loi/{notation}/{level}

    {notation} - the Uniclass2015 classification of the object, for example Ss_30_40_95_40

    {level} - the LOI banding to retrieve

The Properties API endpoint exposes 2 methods.

  • A method to query properties by their ID:


    properties/propertybyid/{id}

    {id} - the ID of the property, for example 11426

  • A method to return a list of properties who’s name contains characters that match a specific query:


    properties/propertybyname/{name}

    {name} - the name of the property to search for, for example "compressive"

Sample code

We have made a sample .NET web application available on GitHub to demonstrate the capabilities of the BIM Toolkit API (https://github.com/theNBS/BIMToolkitAPIClient). The sample shows retrieval of the Elements, Products, Spaces and Systems table and the querying of level of information properties in JSON format.

BIM Toolkit API Sample application

BIM Toolkit API sample application

How do I get access to the Public API?

In order to access the Public API and use the sample application you will need an API key. Please email support@thenbs.com to request a key.

further reading