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.

Resource URL

POST /calculate

All requests must contain a valid API key in the header of the request:

x-api-key: <your API key>

Input Data

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.

Name Type Description
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)

Input Parameters

The endpoint requires you to post a JSON structure in the body of the request.


The code snippet example below shows a properly formed request.

“zipcode”: “10001”,
“avg_bill”: 150,
“price_per_w”: 3.5,
“financing_term”: 15,
“bill_offset”: 1,
“financing_rate”: 0.0299,

Preliminary Proposal Response

The 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 Data

The 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.
Name Type Description
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 Codes

Responses 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.
Type Description
200 Valid request
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.

“city”: “Schenectady”,
“co2_tons”: 10, “errors”: [],
“gal_of_gas”: 1020,
“homes_electricty”: 1.09,
“inc_home_value”: 20080,
“incentive”: 11837,
“install_size”: 12,
“install_size_max”: 13,
“install_size_min”: 11,
“monthly_payment_max”: 181,
“monthly_payment_min”: 153,
“panels_min”: 33,
“panels_max”: 39,
“req_id”: “099d463c-9b51-49ac-8057-ad46afebc037”,
“savings”: 75752,
“state”: “New York”,
“trash_bags”: 396,
“tree_seedlings”: 289,
“util_bill_no_solar”: 279