Response Structure
The following sections provide the specifications and syntax for each API response schema.
Top-level response payload schema
{
"addressFoundFull": "197 RANDALL RD, BALLSTON SPA, NY 12020", // assembled from "addressFoundComponents"
"addressFoundComponents": ADDRESS_COMPONENTS, // refer to the Address Components schema
"baseBuilding": BASE_BUILDING, // refer to the Base Building schema
"globalControls": GLOBAL_CONTROLS, // refer to the Global Controls schema
"defaultModelControls": MODEL_CONTROLS, // refer to the Model Controls schema
"timelines": [ RESPONSE_TIMELINE ], // refer to the Response Timeline schema
"typical": TYPICAL, // if requested in global controls, refer to the Typical schema
}
Address Found
Address Found Full
{
"addressFoundFull": "197 RANDALL RD, BALLSTON SPA, NY 12020"
}
Address Found Components
Refer to the Address Components schema.
Timelines
// RESPONSE_TIMELINE
{
"id": "<UUID>", // generated if not provided
"radiantId": "<UUID>", // generated by the API
"label": "<adjective>-<animal>", // generated if not provided
"comparedTo": "OTHER_TIMELINE", // if missing it defaults to STATUS_QUO
"models": [ RESPONSE_MODEL ], // refer to the Response Model schema
// Timeline results
// Timeline costs and differences are provided if incoming models define "appliedOn" and "includeCostAnalysis" is true
"totalEnergyCosts": 0.0, // utility cost over "timelineDurationInYears".
// "totalInstallationCosts": 0.0,
"totalEmissions": {
"co2": 0.0, // CO2 emissions over "timelineDurationInYears".
},
// Timeline results compared to Status Quo or any other timeline specified in "comparedTo"
"totalEnergyCostsDifference": 0.0, // utility cost compared to different timeline over "timelineDurationInYears"
"totalEmissionsDifference": {
"co2": 0.0 // CO2 emissions compared to different timeline over "timelineDurationInYears"
},
// TBD: Include financial analysis properties here.
//
// ("ROI" | "cashFlow" | "SIR" | "MIRR" | "differences" | "installedCosts" | "energyCosts")
//
"financialIndicators": {
"ROI": 0.0, //
"SIR": 0.0, //
"MIRR": 0.0, //
"cashFlow": {
"monthly": [0.0, ..., 0.0], // monthly electricity difference/savings - loan cost
"annual": 0.0, // annual electricity difference/savings - loan cost
"averageMonthly": 0.0, // annual electricity difference/savings - loan cost / 12
},
},
}
Models
// RESPONSE_MODEL
{
"id": "<UUID>", // generated if not provided
"radiantId": "<UUID>", // generated by the API
"label": "<adjective>-<animal>", // generated if not provided
"appliedOn": "<DATE>", // date in the YYYY-MM-DD format, only if property was passed in in the request
"modelControls": MODEL_CONTROLS, // if provided in the request
"loans": [ LOAN ], // optional, refer to the Loan schema
"incentives": [ INCENTIVE ], //optional, refer to the Incentive schema
"automatedMeasures": AUTOMATED_MEASURES, //optional, refer to the Automated Measures schema
"customMeasures": [ CUSTOM_MEASURE ], // optional, refer to the Custom Measure schema
"requestedImprovedBuilding": IMPROVED_BUILDING, // this is an exact mirror of what was requested as the "improvedBuilding" for this model
"appliedImprovedBuilding": IMPROVED_BUILDING, // refer to the Improved Building schema
"userData": { // optional, user-defined labels (only strings) to associate with the model, mirrored in the response
"myKey": "aValue",
},
// Model results
"modelCosts": {
"totalInstalledCost": 1650.0, // sum of (fixedCost + (variableCostRate * variableCostMultiplier)) for all one time costs
"totalIncentives": 0.0, // sum of all incentives
"netModelCost": 0.0, // net cost = totalImplementationCost - totalIncentives
},
"energyTotals": ENERGY_TOTALS,
"energyEndUses": ENERGY_END_USES,
"energyCosts": ENERGY_COSTS,
"emissionTotals": EMISSION_TOTALS,
// Model results compared against the existing building (either BASE or the previous model in the timeline)
"energyTotalsDifferenceWithBase": ENERGY_TOTALS,
"energyCostsDifferenceWithBase": ENERGY_COSTS,
"emissionTotalsDifferenceWithBase": EMISSION_TOTALS
"energyTotalsDifferenceWithPreviousModel": ENERGY_TOTALS,
"energyCostsDifferenceWithPreviousModel": ENERGY_COSTS,
"emissionTotalsDifferenceWithPreviousModel": EMISSION_TOTALS,
// TBD: Review financial indicators
"financialIndicators": {
"ROI": 0.0, //
"SIR": 0.0, //
"MIRR": 0.0, //
"cashFlow": {
"monthly": [0.0, ..., 0.0], // monthly electricity difference/savings - loan cost
"annual": 0.0, // annual electricity difference/savings - loan cost
"averageMonthly": 0.0, // annual electricity difference/savings - loan cost / 12
},
}
}
Provided Base Building
This object reflects the baseBuilding from the request. Refer to the Base Building schema.
Applied Base Building
This object reflects the modeled base building, including all characteristics populated by Radiant Labs using our common schema and defaulting engine. Refer to the Base Building schema.
Requested Improved Building
This feature is not yet supported, but will reflect the improvedBuilding from the request. Refer to the Improved Building schema.
Applied Improved Building
This feature is not yet supported, but will reflect the modeled improved building, including all characteristics populated by Radiant Labs using our common schema and defaulting engine. Refer to the Improved Building schema.
Model Costs
Energy Totals
// ENERGY_TOTALS
{
// given if resolution included "hourly"
// it is guaranteed the timeseries will contain 8760 datapoints
"hourly": ENERGY_TOTALS_PER_FUEL_TIME_SERIES,
// given if resolution included "monthly"
// it is guaranteed the timeseries will contain 12 datapoints
"monthly": ENERGY_TOTALS_PER_FUEL_TIME_SERIES,
// given if resolution included "annual"
// it is guaranteed the timeseries will only contain 1 datapoint
"annual": ENERGY_TOTALS_PER_FUEL_TIME_SERIES,
}
Energy Totals per Fuel Time Series
// ENERGY_TOTALS_PER_FUEL_TIME_SERIES
{
"coalTotal": {
"metricTons": [0.0, ..., 0.0],
"mbtu": [0.0, ..., 0.0]
},
"electricityTotal": {
"kwh": [0.0, ..., 0.0],
"mbtu": [0.0, ..., 0.0]
},
"fuelOilTotal": {
"gallons": [0.0, ..., 0.0],
"mbtu": [0.0, ..., 0.0]
},
"naturalGasTotal": {
"ccf": [0.0, ..., 0.0],
"mbtu": [0.0, ..., 0.0]
},
"propaneTotal": {
"gallons": [0.0, ..., 0.0],
"mbtu": [0.0, ..., 0.0]
},
"woodCordTotal": {
"mbtu": [0.0, ..., 0.0]
},
"woodPelletsTotal": {
"mbtu": [0.0, ..., 0.0]
},
// "total" is present if the "energyStandard" property was provided in the global controls' units object
"total": {
"mbtu": [0.0, ..., 0.0]
}
}
Energy End Uses
// ENERGY_END_USES
{
// given if resolution included "hourly"
// it is guaranteed the timeseries will contain 8,760 datapoints
"hourly": ENERGY_END_USES_PER_FUEL_TIME_SERIES,
// given if resolution included "monthly"
// it is guaranteed the timeseries will contain 12 datapoints
"monthly": ENERGY_END_USES_PER_FUEL_TIME_SERIES,
// given if resolution included "annual"
// it is guaranteed the timeseries will only contain 1 datapoint
"annual": ENERGY_END_USES_PER_FUEL_TIME_SERIES,
}
Energy End Uses per Fuel Time Series
{
"electricity": {
"heating": {
"mbtu": [0.0, ..., 0.0],
"kwh": [0.0, ..., 0.0]
},
"heatingFansPumps": {
"mbtu": [0.0, ..., 0.0],
"kwh": [0.0, ..., 0.0]
},
"heatingHeatPumpBackup": {
"mbtu": [0.0, ..., 0.0],
"kwh": [0.0, ..., 0.0]
},
"heatingHeatPumpBackupFansPumps": {
"mbtu": [0.0, ..., 0.0],
"kwh": [0.0, ..., 0.0]
},
"cooling": {
"mbtu": [0.0, ..., 0.0],
"kwh": [0.0, ..., 0.0]
},
"coolingFansPumps": {
"mbtu": [0.0, ..., 0.0],
"kwh": [0.0, ..., 0.0]
},
"hotWater": {
"mbtu": [0.0, ..., 0.0],
"kwh": [0.0, ..., 0.0]
},
"lightingInterior": {
"mbtu": [0.0, ..., 0.0],
"kwh": [0.0, ..., 0.0]
},
"lightingGarage": {
"mbtu": [0.0, ..., 0.0],
"kwh": [0.0, ..., 0.0]
},
"lightingExterior": {
"mbtu": [0.0, ..., 0.0],
"kwh": [0.0, ..., 0.0]
},
"mechVent": {
"mbtu": [0.0, ..., 0.0],
"kwh": [0.0, ..., 0.0]
},
"refrigerator": {
"mbtu": [0.0, ..., 0.0],
"kwh": [0.0, ..., 0.0]
},
"freezer": {
"mbtu": [0.0, ..., 0.0],
"kwh": [0.0, ..., 0.0]
},
"dehumidifier": {
"mbtu": [0.0, ..., 0.0],
"kwh": [0.0, ..., 0.0]
},
"dishwasher": {
"mbtu": [0.0, ..., 0.0],
"kwh": [0.0, ..., 0.0]
},
"clothesWasher": {
"mbtu": [0.0, ..., 0.0],
"kwh": [0.0, ..., 0.0]
},
"clothesDryer": {
"mbtu": [0.0, ..., 0.0],
"kwh": [0.0, ..., 0.0]
},
"rangeOven": {
"mbtu": [0.0, ..., 0.0],
"kwh": [0.0, ..., 0.0]
},
"ceilingFan": {
"mbtu": [0.0, ..., 0.0],
"kwh": [0.0, ..., 0.0]
},
"television": {
"mbtu": [0.0, ..., 0.0],
"kwh": [0.0, ..., 0.0]
},
"plugLoads": {
"mbtu": [0.0, ..., 0.0],
"kwh": [0.0, ..., 0.0]
},
"poolHeater": {
"mbtu": [0.0, ..., 0.0],
"kwh": [0.0, ..., 0.0]
},
"poolPump": {
"mbtu": [0.0, ..., 0.0],
"kwh": [0.0, ..., 0.0]
},
"permanentSpaHeater": {
"mbtu": [0.0, ..., 0.0],
"kwh": [0.0, ..., 0.0]
},
"permanentSpaPump": {
"mbtu": [0.0, ..., 0.0],
"kwh": [0.0, ..., 0.0]
},
"pv": {
"mbtu": [0.0, ..., 0.0],
"kwh": [0.0, ..., 0.0]
}
},
"naturalGas": {
"heating": {
"mbtu": [0.0, ..., 0.0],
"ccf": [0.0, ..., 0.0]
},
"heatingHeatPumpBackup": {
"mbtu": [0.0, ..., 0.0],
"ccf": [0.0, ..., 0.0]
},
"hotWater": {
"mbtu": [0.0, ..., 0.0],
"ccf": [0.0, ..., 0.0]
},
"clothesDryer": {
"mbtu": [0.0, ..., 0.0],
"ccf": [0.0, ..., 0.0]
},
"rangeOven": {
"mbtu": [0.0, ..., 0.0],
"ccf": [0.0, ..., 0.0]
},
"poolHeater": {
"mbtu": [0.0, ..., 0.0],
"ccf": [0.0, ..., 0.0]
},
"permanentSpaHeater": {
"mbtu": [0.0, ..., 0.0],
"ccf": [0.0, ..., 0.0]
},
"lighting": {
"mbtu": [0.0, ..., 0.0],
"ccf": [0.0, ..., 0.0]
},
"fireplace": {
"mbtu": [0.0, ..., 0.0],
"ccf": [0.0, ..., 0.0]
}
},
"fuelOil": {
"heating": {
"mbtu": [0.0, ..., 0.0],
"gallons": [0.0, ..., 0.0]
},
"heatingHeatPumpBackup": {
"mbtu": [0.0, ..., 0.0],
"gallons": [0.0, ..., 0.0]
},
"hotWater": {
"mbtu": [0.0, ..., 0.0],
"gallons": [0.0, ..., 0.0]
},
"clothesDryer": {
"mbtu": [0.0, ..., 0.0],
"gallons": [0.0, ..., 0.0]
},
"rangeOven": {
"mbtu": [0.0, ..., 0.0],
"gallons": [0.0, ..., 0.0]
},
"lighting": {
"mbtu": [0.0, ..., 0.0],
"gallons": [0.0, ..., 0.0]
},
"fireplace": {
"mbtu": [0.0, ..., 0.0],
"gallons": [0.0, ..., 0.0]
}
},
"propane": {
"heating": {
"mbtu": [0.0, ..., 0.0],
"gallons": [0.0, ..., 0.0]
},
"heatingHeatPumpBackup": {
"mbtu": [0.0, ..., 0.0],
"gallons": [0.0, ..., 0.0]
},
"hotWater": {
"mbtu": [0.0, ..., 0.0],
"gallons": [0.0, ..., 0.0]
},
"clothesDryer": {
"mbtu": [0.0, ..., 0.0],
"gallons": [0.0, ..., 0.0]
},
"rangeOven": {
"mbtu": [0.0, ..., 0.0],
"gallons": [0.0, ..., 0.0]
},
"lighting": {
"mbtu": [0.0, ..., 0.0],
"gallons": [0.0, ..., 0.0]
},
"fireplace": {
"mbtu": [0.0, ..., 0.0],
"gallons": [0.0, ..., 0.0]
}
},
"woodCord": {
"heating": {
"mbtu": [0.0, ..., 0.0],
},
"heatingHeatPumpBackup": {
"mbtu": [0.0, ..., 0.0],
},
"hotWater": {
"mbtu": [0.0, ..., 0.0],
},
"clothesDryer": {
"mbtu": [0.0, ..., 0.0],
},
"rangeOven": {
"mbtu": [0.0, ..., 0.0],
},
"lighting": {
"mbtu": [0.0, ..., 0.0],
},
"fireplace": {
"mbtu": [0.0, ..., 0.0],
}
},
"woodPellets": {
"heating": {
"mbtu": [0.0, ..., 0.0],
},
"heatingHeatPumpBackup": {
"mbtu": [0.0, ..., 0.0],
},
"hotWater": {
"mbtu": [0.0, ..., 0.0],
},
"clothesDryer": {
"mbtu": [0.0, ..., 0.0],
},
"rangeOven": {
"mbtu": [0.0, ..., 0.0],
},
"lighting": {
"mbtu": [0.0, ..., 0.0],
},
"fireplace": {
"mbtu": [0.0, ..., 0.0],
}
},
"coal": {
"heating": {
"mbtu": [0.0, ..., 0.0],
"metricTons": [0.0, ..., 0.0]
},
"heatingHeatPumpBackup": {
"mbtu": [0.0, ..., 0.0],
"metricTons": [0.0, ..., 0.0]
},
"hotWater": {
"mbtu": [0.0, ..., 0.0],
"metricTons": [0.0, ..., 0.0]
},
"clothesDryer": {
"mbtu": [0.0, ..., 0.0],
"metricTons": [0.0, ..., 0.0]
},
"rangeOven": {
"mbtu": [0.0, ..., 0.0],
"metricTons": [0.0, ..., 0.0]
},
"lighting": {
"mbtu": [0.0, ..., 0.0],
"metricTons": [0.0, ..., 0.0]
},
"fireplace": {
"mbtu": [0.0, ..., 0.0],
"metricTons": [0.0, ..., 0.0]
}
}
}
Property |
Notes |
|---|---|
|
Excludes heat pump backup and fans/pumps |
|
Includes supply fan (air distribution) or circulating pump (hydronic distribution or geothermal loop) |
|
Excludes heat pump backup fans/pumps |
|
Includes supply fan (air distribution) or circulating pump (hydronic distribution) during heat pump backup |
|
Excludes fans/pumps |
|
Includes supply fan (air distribution) and circulating pump (geothermal loop) |
|
Negative value for any power produced |
Energy Costs
// ENERGY_COSTS
{
// given if resolution included "hourly"
"hourly": ENERGY_COSTS_PER_FUEL_TIME_SERIES,
// given if resolution included "monthly"
"monthly": ENERGY_COSTS_PER_FUEL_TIME_SERIES,
// given if resolution included "annual"
"annual": ENERGY_COSTS_PER_FUEL_TIME_SERIES,
}
Energy Costs per Fuel Time Series
// ENERGY_COSTS_PER_FUEL_TIME_SERIES
{
"coalTotal": [0.0, ..., 0.0],
"electricityTotal": [0.0, ..., 0.0],
"fuelOilTotal": [0.0, ..., 0.0],
"naturalGasTotal": [0.0, ..., 0.0],
"propaneTotal": [0.0, ..., 0.0],
"woodCordTotal": [0.0, ..., 0.0],
"woodPelletsTotal": [0.0, ..., 0.0],
"total": [0.0, ..., 0.0],
}
Emissions Totals
// EMISSION_TOTALS
{
// given if resolution included "hourly"
"hourly": EMISSION_TOTALS_PER_FUEL_TIME_SERIES,
// given if resolution included "monthly"
"monthly": EMISSION_TOTALS_PER_FUEL_TIME_SERIES,
// given if resolution included "annual"
"annual": EMISSION_TOTALS_PER_FUEL_TIME_SERIES,
}
Total Emissions per Fuel Time Series
// EMISSION_TOTALS_PER_FUEL_TIME_SERIES
{
"coalTotal": {
"co2": [0.0, ..., 0.0]
},
"electricityTotal": {
"co2": [0.0, ..., 0.0]
},
"fuelOilTotal": {
"co2": [0.0, ..., 0.0]
},
"naturalGasTotal": {
"co2": [0.0, ..., 0.0]
},
"propaneTotal": {
"co2": [0.0, ..., 0.0]
},
"woodCordTotal": {
"co2": [0.0, ..., 0.0]
},
"woodPelletsTotal": {
"co2": [0.0, ..., 0.0]
},
"total": {
"co2": [0.0, ..., 0.0]
}
}
Typical
The typical object, if requested, is an independently generated version of a typical, comparable baseBuilding. The typicalBuilding has the same addressFull (i.e. physical location for regional properties, such as weather), conditionedFloorArea, yearBuilt, and storiesCount. Any remaining characteristics of the baseBuilding are removed and based on our defaulting engine. The schema of this object follows the same schema as Model.