Importing a Project (API)

The API POST process typically works in the following manner:

1. Authenticate the initiating process/user

2. Project parameter values to be submitted are verified

3. Send project parameter values to DDX

4. Response sent to the user with a Project ID and Reporting Year

5. Log entry is posted on the Firm Account page in the DDx that is accessible by a firm administrator

Authenticate

Authenticate the user in the DDx and obtain the authentication token (auth token).

Request

After successful authentication, the auth token must be sent with all client requests.

Response

Import project

Creates or updates a project in the DDx using the information passed on through the parameters. Project ID and Reporting Year are mandatory input fields for this call.

Project ID and Reporting Year will be required in order to identify the project. In case the combination of Project ID and Reporting Year does not exist in the DDx a new project will be created.

Note: When an existing project is updated on the DDx all input values for the existing project view are replaced.

Request

Note: The authToken was generated in response to /api/v1/authenticate

Response

The Energy Model Import API feature currently only allows the import of project data for a single project at a time, and it will not allow a project to be deleted or removed from the firm’s account.

The API documentation is primarily written for programmers familiar with Web Services programming standards such as the REST. An initial focus is increasing the number of energy modeling tools linking to the API, but 2030 Commitment firms could also leverage the API as well.

For AIA 2030 Commitment firms that are interested in learning more about the API workflows, see the API Use Cases section for further information.

The API has been developed in an OPEN format, with the intent that an increasing number of vendors and tools to utilize the API.

If you are interested in learning more about how your company or energy modeling tool can utilize the API, please send an e-mail to 2030commitment@aia.org with the subject line of “API Interest” and a description of how you would like to utilize the API.

One thing to note is that as other tools begin to utilize the API, there are the potential for differences between energy model tools for what input fields are transferred to the API. The API contains both mandatory and optional project parameter fields, and it is at the discretion of the energy model tool provider to determine which optional project parameter fields will be included in their implementation

The DDx API allows project data to be transferred from an energy modeling tool to the DDx directly to either create a new project or update a previous project. The project import will only work on energy modeling tools that have enabled the DDx API. Potential use cases include, but are not limited to:

• Within the member firm: A staff member of a firm with a DDx account can use the Firm Key, obtained from a firm administrator, and their User Key to create or update a single project from an energy modeling tool that has enabled the DDx API.

• Outside of the member firm: A member firm working with an energy modeling consultant, engineer or other party can provide the Firm Key and a User Key, so that they can create or update a single project from an energy modeling tool that has enabled the DDx API.

Project teams may update the energy model results at each project phase or at certain phases during the project.

The API provides a one-directional project data import feature via REST based web service (Figure 1 - High-level project data flow). Currently the implementation is for data transfer one project at a time. JSON object(s) will be used as the means of data transfer. Developers can build custom applications, tools, and services that utilize this API to send project information to the DDx.

Clients make standard HTTP requests over an SSL channel. Clients make requests either in aggregate or a specific resource.The format of the URL is: endpoint/version/namespace/resource[?query_parameters]

Figure 1 - High-level project data flow

Open

Figure 2 - Detailed project data flow

Open

Sample API Request For User Authentication-

curl -v -H "Accept: application/json" -H "Content-type: application/json" -X POST -d '{"user_key":"8TNCKY7VCDA7B4FRP","firm_key":"ABCDEF12346"}'

Test API URL For Authentication-

https://stg-2030ddx.aia.org/api/v1/authenticate

Sample API Request For Project Create Or Update-

curl -v -H "Accept: application/json" -H "Content-type: application/json" -X POST -d ' {"authToken":"1680182731c08abd596308089fea74c94", "projectName":"Test API 11", "projectId":"TESTAPI0011", "projectCategory":"Non-Residential", "projectPhase":"Concept", "reportingYear":"2015", "country":"India", "state":"Maharashtra", "zipcode":"400200", "city":"Nagpur", "climateZone":"3C Warm - Marine", "useType1":"Residential - Multi-Family, 5 or more units", "useType1Area":"20000","designEnergyCode":"ASHRAE 90.1-2001", "responsiblePartyForEnergyModel":"Design Engineer", "energyModelingTool":"DOE-2.1E/EnergyPro", "baselineEUI":"45", "predictedEUI":"45", "lightingPowerDensity":"6", "windowToWallRatio":"4", "renewables":"PV;Wind Turbine", "occupancySensorsIncluded":"Yes", "daylightingSensorsIncluded":"No", "electricityProducedOffSite":"4500", "naturalGasCombustedOnSite":"56", "districtSteam":"678", "districtHotWater":"678", "districtChilledWater":"678", "chillerType":"Electric Driven", "diesel":"6000", "electricityFromRenewablesOnSite":"6789"}'

Test API URL For Project Create Or Update

https://stg-2030ddx.aia.org/api/v1/import_project

https://2030ddx.aia.org​​​​​​​/api/v1/authenticate

https://2030ddx.aia.org/api/v1/import_project

When firm users are attempting to transfer project data from an energy modeling tool linked to the DDx API, the first step in the process is authentication. For authentication purposes, two types of keys—the User Key and Firm Key—are required to be provided by the user to generate an authentication token and establish the data link.

Figure 3 - Generating User Key

Open

A User Key can be generated by the Firm user. Figure 3 shows where the user can go to generate and access the user key once it has been created. The key will be a 17 characters string encrypted using 160-bit encryption. This should be sent along with the Firm Key (i.e., Firm ID) for authentication. The User Key along with the Firm Key will be used to generate an authentication token.

Each firm that has a DDx account will be provided a Firm Key which is displayed on Section 2 of the My Account screen (Figure 3). The key will be 11 characters string encrypted using 160-bit encryption. The Firm Key along with the User Key will be used to generate an authentication token.

When a valid User Key along with a valid Firm Key are provided, an authentication token will be generated. The authentication token will be a 16 characters string encrypted using 160-bit encryption and will be valid for 24 hours.

Open

The table identifies the DDx Parameter fields that are currently incorporated into the API. Each row displays the API Parameter name, the entry type and the units. In addition, the “Field Type” column displays if the parameter is “Mandatory” or “Optional”. Also if “text to match DDx selection option” is provided in the “Entry Type” column, then the DDx selection option list for that parameter can be found in the next section.