Overview

The 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, OperationalSource, OperationalDemand, MasterTemplateId, MasterTemplateName, FunctionTypeName, YearOccurence, Module, ModuleDescription, UniqueAssetId, EmissionsScope, CustomFieldProject, CustomFieldStructure, CustomFieldDesign

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.

Knowledge Base

eToolLCD API

Overview

Authentication

Authorisation

API INITIATION

POST GETACCESSTOKENFROMREFRESHTOKEN

Overview:

Mandatory Parameters

Output

API Functions / Methods

GET GETDESIGNS

Overview:

GET GETMODULES

Overview:

GET GETINDICATORS

Overview:

GET GETIMPACTDESIGNDETAILS

Overview:

Mandatory Parameters

Example Calls and Responses

GET GETIMPACTGROUPDETAILS (TBA)

Overview:

Mandatory Parameters

Example Calls and Responses

Throttling:

Leave A Comment? Click here to cancel reply.