Preliminary Solar Proposal API
What is a Preliminary Solar Proposal?The Preliminary Solar Proposal was created to improve and expedite the residential solar PV shopping experience. Like a ballpark estimate, the Preliminary Solar Proposal API instantly computes an estimated installation size based on the homeowner’s location and electricity demands then calculates the system’s expected financial and environmental impact, within an acceptable range. These key selling points can then be used to educate the homeowner in a format chosen by the provider, while guiding the prospect towards an informed purchasing decision.
All requests must contain a valid API key in the header of the request:
x-api-key: <your API key>
Defining Solar/Financial Products & Homeowner Inputs
The input data required for the API allows providers to tailor calculations to their specific financial lending and solar products. If the product information is not known, the default values may be used. The API also requires the homeowner’s location and electricity usage (homeowner inputs) to determine how to accurately size the PV system.
|financing_term||integer||(Optional) Loan term length in years (default: 20)|
|bill_offset||number||(Optional) Percentage to offset the bill (default: 1)|
|financing_rate||number||(Optional) Financing rate for the cost of solar (default:.0399)|
|zipcode||string||Valid 5-digit US zip code (example: 10001)|
|avg_bill||integer||Average monthly electricity bill (example: 150)|
The endpoint requires you to post a JSON structure in the body of the request.
EXAMPLEThe code snippet example below shows a properly formed request.
Preliminary Proposal ResponseThe Preliminary Proposal response shares the key aspects of the solar PV system calculated from the product information and homeowner inputs. The response to the request will be a JSON structure in the body.
Response DataThe response data includes the PV system sizing information, as well as the key financial and environmental savings information, and all associated costs. Additionally, the homeowner’s zip code is expanded to city and state.
|install_size_min||integer||Minimum installation size (in kW)|
|install_size_max||integer||Maximum installation size (in kW)|
|install_size||integer||Recommended installation size (in kW)|
|panels_min||integer||Estimated minimum number of panels needed|
|panels_max||integer||Estimated maximum number of panels needed|
|savings||integer||Lifetime savings on utility bills|
|monthly_payment_min||integer||Minimum monthly payments to own home solar|
|monthly_payment_max||integer||Maximum monthly payments to own home solar|
|inc_home_value||integer||Increase in home value with solar installed|
|incentive||integer||Incentive estimation received when installing solar|
|util_bill_no_solar||integer||Est. utility bill if solar is not installed|
|tree_seedlings||integer||Tree seedlings grown for 10 years with solar installed|
|co2_tons||integer||Tons of CO2 offset with solar installed|
|gal_of_gas||integer||Gallons of gasoline offset with solar installed|
|home_electricity||number||Homes’ electricity use for one year with solar installed|
|trash_bags||integer||Trash bags of waste recycled instead of landfilled with solar installed|
|errors||array of strings||If any non-critical errors occurred, then they will be placed here. For example, if an optional input was provided but was not in the correct type (e.g. financing_term provided as a string instead of integer).|
|req_id||str||36-character string unique to each request. Can be used with other endpoints to keep track of one specific user (e.g. a lead conversion)|
|city||str||City of the zip code provided in the request|
|state||str||State of the zip code provided in the request|
Response CodesResponses will have a status header with a numeric value. This value is what you should check for when writing code to then parse the response. The only response that should be read and parsed is a 200 response.
|400||Bad request – malformed request|
|403||API key is missing or invalid|
|422||Invalid input – zip code or avg_bill is invalid|
Putting it all together
The code snippet example below shows a properly formed request.
“co2_tons”: 10, “errors”: ,
“state”: “New York”,