/
Fetching Projects (API)

Fetching Projects (API)

Mar 22, 2022

The request process typically works in the following manner:

  1. Authenticate the initiating process/user

  2. Send project parameter values to DDX

  3. Response sent to the user with the project's information, including its design data

Methods

Get a project's information

Returns a project's basic information and lists its design phases using the information passed on through the parameters.

Project ID will be required in order to identify the project.

Note: Project ID refers to the id returned by creating a project through the API, instead of the Project Number.

Request

Method

URL

GET

api/v1/project_detail

 

Method

Request body properties (JSON)

TYPE

Required

Obs

GET

authToken

String

Yes

 

GET

projectId

String

Optional (either projectId or id are required)

Refers to the UI's "Project number".

GET

id

String

Optional (either projectId or id are required)

It's DDx's ID for the project.

 

Sample request:

 

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

Response

Status

Response

200

Example responses will be shown below-

{
    "projectName": "Some project name",
    "projectId": "est_ocp_test4",
    "status": "Active",
    "projectCategory": "Whole building",
    "constructionTypeName": "New construction",
    "officeLocation": "Colonia Office",
    "country": "UY",
    "state": "Colonia",
    "city": "Colonia del Sacramento",
    "zipcode": "70000",
    "climateZone": null,
    "designEnergyCode": "ASHRAE 90.1-2001",
    "baselineEUI": 99.8,
    "estimatedOccupancyYear": 2025,
    "energyTarget": 20.2,
    "renewables": null,
    "useType1": "Parking",
    "useType1Area": 1000,

    "updatedAt": "2022-01-24T19:37:47.000Z",
    "createdAt": "2021-01-12T19:51:01.000Z",

   "design_phases": [
    {
       "reportingYear": 2020,
       "projectPhase": "Concept",
       "energyModelingTool": null,
       "predictedEUI": 51.896,
       "lightingPowerDensity": 23.15,
       "windowToWallRatio": 40,
       "electricityProducedOffSite": null,
       "naturalGasCombustedOnSite": null,
       "districtSteam": null,
       "diesel": null,
       "electricityFromRenewablesOnSite": null,
       "occupancySensorsIncluded": "NO",
       "daylightingSensorsIncluded": "NO",
       "chillerType": null
    }
   ]
}

400

{"error": {message: "Invalid Value or Mandatory values are missing."} }

Note: List of all error messages provided in appendix below

401

{"message": "Invalid Auth Token."}

401

{"message": "Auth Token Expired."}

404

{"message": "Project not found."}

500

{"error":"Something went wrong. Please try again later."}

API Testing & Calls

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

Test API URL For GET Project

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

 

Production API URL for Authentication

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

Production API URL for GET Project

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

Fetching all firms' projects

Returns all projects' basic information and lists its design phases using the information passed on through the parameters.

Request

Method

URL

GET

api/v1/projects

 

Method

Request body properties (JSON)

TYPE

Required

Obs

GET

authToken

String

Yes

 

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


Response

Status

Response

200

Example responses will be shown below-

[{
    "projectName": "Some project name",
    "projectId": "est_ocp_test4",
    "status": "Active",
    "projectCategory": "Whole building",
    "constructionTypeName": "New construction",
    "officeLocation": "Colonia Office",
    "country": "UY",
    "state": "Colonia",
    "city": "Colonia del Sacramento",
    "zipcode": "70000",
    "climateZone": null,
    "designEnergyCode": "ASHRAE 90.1-2001",
    "baselineEUI": 99.8,
    "estimatedOccupancyYear": 2025,
    "energyTarget": 20.2,
    "renewables": null,
    "useType1": "Parking",
    "useType1Area": 1000,

   "updatedAt": "2022-01-24T19:37:47.000Z",
   "createdAt": "2021-01-12T19:51:01.000Z",
   "design_phases": [
    {
       "reportingYear": 2020,
       "projectPhase": "Concept",
       "energyModelingTool": null,
       "predictedEUI": 51.896,
       "lightingPowerDensity": 23.15,
       "windowToWallRatio": 40,
       "electricityProducedOffSite": null,
       "naturalGasCombustedOnSite": null,
       "districtSteam": null,
       "diesel": null,
       "electricityFromRenewablesOnSite": null,
       "occupancySensorsIncluded": "NO",
       "daylightingSensorsIncluded": "NO",
       "chillerType": null
    }
   ]
}, ...]

400

{"error": {message: "Invalid Value or Mandatory values are missing."} }

Note: List of all error messages provided in appendix below

401

{"message": "Invalid Auth Token."}

401

{"message": "Auth Token Expired."}

404

{"message": "Project not found."}

500

{"error":"Something went wrong. Please try again later."}

API Testing & Calls

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

Test API URL to Fetch all projects

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

 

Production API URL for Authentication

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

Production API URL for GET Project

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

Status Codes

All status codes are standard HTTP status codes. The below ones are used in this API.

2XX - Success of some kind

4XX - Error occurred on client’s part

5XX - Error occurred in server’s part

Specific field-level errors will be reported. 

Status Code

Description

200

OK

201

Created

202

Accepted (Request accepted, and queued for execution)

400

Bad request

401

Authentication failure

403

Forbidden

404

Resource not found

405

Method Not Allowed

409

Conflict Specific field-level errors will be reported

412

Precondition Failed

413

Request Entity Too Large By default this is 1 MB but it is configurable on the server

500

Internal Server Error

501

Not Implemented

503

Service Unavailable