eToolLCD API

Overview

The upcoming eToolLCD API exposes impact result data of the main eToolLCD application and can be used for a variety of purposes such as building your dashboard.

Authentication

The eToolLCD API is using Auth2 JWT token with token refresh rotation. These authentication steps will be finalised on the delivery time.

Autherntication API

Authorisation

The authorisation of the impact result data follows the authorisation for the logged-in user to view the design’s information.

Design Authorisation

API INITIATION

The initial refresh token is retrievable from the API Keys in the Organisation tab. It is only accessible for organisation admin.
Click on the New Refresh Token and follow the prompt. When the refresh token has been successfully created, it will show you a textbox which you can copy into the clipboard.
Note: For security purpose, eTool never store any refresh token created. 

To make the API function calls, you need an access token. 
An access token is retrievable from the POST call to GenerateAccessTokenFromRefreshToken.

POST GETACCESSTOKENFROMREFRESHTOKEN

Overview:

URL

https://www.etoollcd.com/Api/Shared/GenerateAccessFromRefreshToken

Methods Supported

POST

Description

Allows you to get a new refresh token and access token.

Mandatory Parameters

RefreshToken

For the first access token, use refresh token previously retrieved from the organisation page. Then use the rotated refresh token which is the output of this call.

Output

Token

New access token, which is valid for the duration specified during the refresh token creation.

RefreshToken

New rotated refresh token, please save this for the next call. 

 

API Functions / Methods

At this stage, there are only four functions/methods for calling the eToolLCD API which is to get results.  We will likely expand on the available functions/methods in the future.  

GET GETDESIGNS

Overview:

URL

https://www.etoollcd.com/extapi/getdesigns

Methods Supported

GET

Description

Allows you to retrieve all designs in your organisation.

 

GET GETMODULES

Overview:

URL

https://www.etoollcd.com/extapi/getmodules

Methods Supported

GET

Description

Allows you to retrieve all modules.

 

GET GETINDICATORS

Overview:

URL

https://www.etoollcd.com/extapi/getindicators

Methods Supported

GET

Description

Allows you to retrieve all indicators.

 

GET GETIMPACTDESIGNDETAILS

Overview:

URL

https://www.etoollcd.com/extapi/getimpactdesigndetails?indicatorId=<IndicatorID>&aggregator=<aggregator>&groupFields=<groupFields>&<optional parameters>

Methods Supported

GET

Description

Allows you to retrieve impact results from all designs in your organisation, based on the grouping fields and optional filters.

Mandatory Parameters

indicatorId

Indicator Id for impact. You can get the list of indicators from GETINDICATORS() call.

aggregator

Sum / Average / Min / Max

groupFields

Comma separated list of fields by which the aggregate results will be grouped: DesignFunctionName, NestedTemplateName, NestedTemplateId, NestedTemplateQuantity, NestedTemplateUnit, ElementId, CategoryCode, CategoryName, ElementDescription, ElementType, ElementQuantity, ElementUnits, ElementRecurrenceFrequency, ElementProcessName, MaterialWasteFactor, MaterialMass, ProcessID, DisposalName, OpenLoopRecovery, ClosedLoopRecovery, Operational Source, Operational Demand, MasterTemplateId, MasterTemplateName, FunctionTypeName, YearOccurence, Module, Module Description, UniqueAssetId

Leaving the groupFields blank will remove the grouping and list all the granularities, however, data flooding may occur if a large number of groupings is requested for many designs.

Optional Parameters (filters)

designIds

Comma separated designId. You can get the list of designs from GETDESIGNS() call.

nestedTemplateIds

Comma separated nestedTemplateId

categoryIds

Comma separated building element categoryIds

  • 1 = Substructure
  • 8 = Superstructure
  • 44 = Internal finishes
  • 54 = Fittings, furnishings and equipment
  • 64 = Services equipment
  • 132 = Prefabricated buildings and building units
  • 137 = Work to existing building
  • 151 = External works
  • 191 = Facilitating works
  • 211 = Project/design team
  • 1016 = Undefined

disposalNames

Comma separated disposalNames

masterTemplateIds

Comma separated masterTemplateIds

yearOccurences

Comma separated year occurrences in ages, from year 0 onwards.

lifeCycleStages

Comma separated life cycle stage.

modules

Comma separated modules. You can get the list of designs from GETMODULES() call. At this stage the available options for the modules are: 

  • A1A3 = Product Stage
  • A4 = Transport of Equipment and Materials
  • A5 = Construction
  • B1 = General Use
  • B2B3 = Maintenance and Repair
  • B4 = Replacement
  • B5 = Refurbishment
  • B6 = Integrated Operational Energy Use
  • B6+ = Non-integrated Energy
  • B7 = Operational Water Use
  • C1 = Deconstruction and Demolition
  • C2 = Transport of Waste Offsite
  • C3 = Waste Processing
  • C4 = Disposal
  • D1 = Operational Energy Exports
  • D2 = Closed Loop Recycling
  • D3 = Open Loop Recycling
  • D4 = Materials Energy Recovery
  • D5 = Direct Reuse

elementIds

Comma separated elementIds

Example Calls and Responses

1) Retrieving the sum of all impact results grouped by Module

Example Call: https://www.etoollcd.com/extapi/getimpactdesigndetails?indicatorId=1&aggregator=Sum&groupFields=Module

Example Response:

{
  [
    ...
    {
      "Module": "D4",
      "ImpactValue": 10.303008941247342
    },
    {
      "Module": "B6",
      "ImpactValue": 508875.7753625
    }
    ...
  ]
}

 

GET GETIMPACTGROUPDETAILS (TBA)

Overview:

URL

https://www.etoollcd.com/extapi/getimpactgroupdetails?orgid=<orgId>&indicatorId=<IndicatorID>&aggregator=<aggregator>&groupFields=<groupFields>Module,CategoryName&<optional parameters>

Methods Supported

GET

Description

Allows you to retrieve impact results from all designs in your organisation, based on the grouping fields and optional filters.

Mandatory Parameters

orgId

Organisation Id associated with your organisation

indicatorId

Indicator Id for impact.  At this stage the available options for the indicatorID are: 

  • 1 = Global Warming Potential 
  • 3 = Australian Dollar
  • 25 = British Pounds Sterling
  • 26 = Euro
  • 45 = US Dollar
  • 46 = New Zealand Dollar
  • 54 = Material Mass

aggregator

Sum / Average / Min / Max

groupFields

Comma separated list of fields by which the aggregate results will be grouped: DesignName, DesignCertified, DesignFavourite, DesignPurpose, ScenarioTree, ScenarioTitle, ParentScenarioID, DesignFunctionName, NestedTemplateName, NestedTemplateId, NestedTemplateQuantity, NestedTemplateQuantity, ProcessID, DisposalName, CategoryCode, CategoryName, MasterTemplateId, MasterTemplateName, FunctionTypeName, ElementType, YearOccurence, LifeCycleStage, Module, Module Description

Data flooding may occur if a large number of groupings is requested for many designs.

Optional Parameters (filters)

designIds

Comma separated designId

nestedTemplateIds

Comma separated nestedTemplateId

categoryIds

Comma separated building element categoryIds

  • 1 = Substructure
  • 8 = Superstructure
  • 44 = Internal finishes
  • 54 = Fittings, furnishings and equipment
  • 64 = Services equipment
  • 132 = Prefabricated buildings and building units
  • 137 = Work to existing building
  • 151 = External works
  • 191 = Facilitating works
  • 211 = Project/design team
  • 1016 = Undefined

disposalIds

Comma separated disposalIds

masterTemplateIds

Comma separated masterTemplateIds

yearOccurenceAges

Comma separated year occurrences in ages, from year 0 onwards.

yearOccurenceDates

Comma separated year occurrences in calendar years (2020, 2021, 2022, etc).

modules

Comma separated modules. At this stage the available options for the modules are: 

  • A1A3 = Product Stage
  • A4 = Transport of Equipment and Materials
  • A5 = Construction
  • B1 = General Use
  • B2B3 = Maintenance and Repair
  • B4 = Replacement
  • B5 = Refurbishment
  • B6 = Integrated Operational Energy Use
  • B6+ = Non-integrated Energy
  • B7 = Operational Water Use
  • C1 = Deconstruction and Demolition
  • C2 = Transport of Waste Offsite
  • C3 = Waste Processing
  • C4 = Disposal
  • D1 = Operational Energy Exports
  • D2 = Closed Loop Recycling
  • D3 = Open Loop Recycling
  • D4 = Materials Energy Recovery
  • D5 = Direct Reuse

elementIds

Comma separated elementIds

designPurposeID

Comma separated design purpose

  • 1 = Target Setting – Business as Usual
  • 2 = Target Setting – Improved
  • 3 = Target Setting – Scenario
  • 4 = Target Setting – Final
  • 5 = LCA – Proposed
  • 6 = LCA – Improved
  • 7 = LCA – Scenario
  • 8 = LCA – Final
  • 9 = LCA – Audit
  • 10 = LCA – Business as Usual
  • 11 = LCA – As Built

isFavourite

Boolean value where 1 signifies that the design is marked as a favourite for that structure (there is only one favourite design per structure, intended to indicate the design team’s favourite design. 0 signifies the design is not marked as a favourite.

isCertified

Boolean value where 1 signifies that the design is certified (independently reviewed). 0 signifies the design is not certified.

Example Calls and Responses

1) Retrieving the sum of all impact results grouped by Module

Example Call: https://www.etoollcd.com/extapi/getimpactgroupdetails?orgid=1&indicatorId=1&aggregator=Sum&groupFields=Module

Example Response:

{
  "Result": [
    ...
    {
      "Module": "D4",
      "ImpactValue": 10.303008941247342
    },
    {
      "Module": "B6",
      "ImpactValue": 508875.7753625
    }
    ...
  ]
}

 

2) Retrieving the average of all impact results grouped by categoryName for module A1A3

Example Call: https://www.etoollcd.com/extapi/getimpactgroupdetails?orgid=12&indicatorId=1&aggregator=Average&groupFields=Module,CategoryName&modules=A1A3

Example Response:

{
  "Result": [
    ...
    {
      "Module": "A1A3",
      "CategoryName": "Civil Engineering Structure",
      "ImpactValue": 19386.449602815534
    },
    {
      "Module": "A1A3",
      "CategoryName": "Balustrades and handrails",
      "ImpactValue": 1549.6984477864078
    }
    ...
  ]
  ,
  "CategoryDictionary": [
    ...
    {
      "CategoryName": 1,
      "ImpactValue": “Substructure”
    },
    {
      "CategoryName": 2,
      "ImpactValue": “Standard foundations”
    }
    ...
  ]
}
Throttling: 

API calls are being processed on a first come first serve basis. There is a limit of 15 seconds applied for each call to assure no calls are bottlenecking the API network.

 

 

 

Leave A Comment?

You must be logged in to post a comment.