The Solar API provides solar potential data through the buildingInsights and dataLayers endpoints. To use Solar API data, understanding the following concepts may be helpful:
Solar irradiance and insolation
A building's solar potential is largely based on the amount of sunlight it receives, along with other factors. Solar irradiance is the amount of light that falls on a given area, while solar insolation is a measurement of the average solar irradiance an area receives over time.
A kilowatt (kW) is a measure of power, or the rate at which something uses energy, while a kilowatt-hour (kWh) is a measure of energy used or energy capacity. Solar irradiance is measured in kilowatts, while solar insolation is measured in kilowatt-hours.
1 kWh/kW equals 1 sun hour, which is defined as one hour where the intensity of sunlight reaches an average of 1,000 Watts (1 kilowatt) of energy per square meter.
For example, if a part of a roof has a solar insolation of 2000 kWh/kW/year, a 1 kW solar panel array placed there will produce 2000 kWh/year. A 4 kW array placed in the same location will produce 8000 kWh/year.
Standard Test Conditions are an industry standard benchmark used to determine solar panel power output. At STC, the amount of power a solar panel outputs becomes its maximum power rating, or capacity. A 1 kW panel will generate 1 kWh of energy under STC.
Sunniness and sunshine quantiles
The Solar API defines "sunniness" as the level of sunlight received by a particular section of a roof relative to the rest of the roof, annually on average. Some parts of a roof may be darker than others, due to shade from nearby buildings or tree cover, while other parts of a roof may be fully exposed to the sky at all times and therefore receive more sunlight.
The sunshineQuantiles field in the buildingInsights response provides 11 buckets, or deciles, of the sunniness of a roof or part of a roof. The Solar API takes all of the points on the roof, sorts them by their "sunniness," and identifies the highest, lowest, and 9 intermediate evenly spaced values.
For example, assume that the sunniest part (1%) of a given roof receives 1100 kWh/kW/year, while the darkest part (also 1%) of the same roof receives 400 kWh/kW/year. The next darkest 20% of the roof receives 500 kWh/kW/year. The next sunniest 50% of the roof receives 900 kWh/kW/year. The remaining 28% receives 1000 kWh/kW/year.
Rasters
The dataLayers endpoint returns solar information encoded in GeoTIFFs, which are a type of raster.
A raster is composed of a matrix of cells, or pixels, arranged in rows and columns. Each pixel contains a value that represents information about that location, such as elevation, tree canopy, sunlight, among others.
Rasters store discrete and continuous data. Discrete data, such as land cover or soil type, is thematic, or categorical. Continuous data represents phenomena that have no clear boundaries, such as elevation or aerial imagery.
Rasters are composed of bands, which measure different characteristics of a dataset. Rasters can have a single band or multiple bands. Each band is composed of a matrix of cells, or pixels, which store information. Pixels can store float or integer values.
The bit depth of a pixel indicates the number of values that a pixel can store, based on the formula 2n, where n is the bit depth. For example, an 8-bit pixel can store up to 256 (28) values ranging from 0 to 255.
Flux
You can request flux maps using the dataLayers endpoint. The Solar API defines flux as the annual amount of sunlight on roofs in kWh/kW/year. In calculating flux, the Solar API takes the following variables into account:
- Location information: The Solar API uses hourly solar irradiance data from various weather sets, which are typically on a 4 to 10 km grid. The API computes the position of the sun in the sky at each hour of the year. This is location-dependent and may vary as a result.
- Weather patterns (clouds): These are accounted for in the solar irradiance data.
- Shade from nearby obstacles: Shading from trees, other buildings, and other parts of the roof are taken into account in calculations.
- Orientation: The pitch and azimuth of each part of the roof.
- True efficiency: The values computed by the Solar API are independent of the panel efficiency. To calculate energy production, you must multiply by the kilowattage of the panels and factor in other system losses. For more information, see Calculate solar costs and savings.
The Solar API does not take the following variables into account:
- Inverter efficiency and other losses: Most values are computed in DC kWh, but some are converted to AC kWh assuming an 85% system efficiency.
- Soiling and snow: These are not included in the calculations.