Loading sunny

Develop A Solar Application

Our big-data geomatics platform contains a wealth of site-specific information on tens of millions of individual properties, derived from high-resolution solar energy simulations. You can put our data to work through our Solar Application Programming Interface (Solar API) to create new Web and mobile solar energy applications.

Building A Solar Application

Sunshot
The development of the Solar Profile, widgets, and the API were funded in part by a DOE SunShot Award

Introduction To The Solar Profile

Every property has a Solar Profile. A Solar Profile is the quantification of the economic and environmental benefits of the energy produced by solar panels installed on the site. We determine these benefits through the following computationally intensive processes:

  1. Place virtual solar panels in a 3D world derived from LiDAR (measurements from lasers mounted on fixed-wing aircraft)
  2. Run a full simulation of the sunlight intensity on each square meter of rooftop surface area, based on typical weather, shadows (near and far horizon), slope and orientation
  3. Draw a polygon representing the buildable area by delineating the contiguous pixels with sufficient sunlight
  4. Fit panels into the polygon to produce a default system size
  5. Compute the energy production for the life of the panels, based on sunlight, efficiency and performance degradation
  6. Determine the levelized cost of energy (LCOE) based on the installed cash price of the system
  7. Calculate the avoided grid electricity costs based on the energy usage (load profile), utility rates, statewide energy inflation rates and applicable incentives
  8. Determine the amount of carbon equivalent emissions avoided through solar energy generation based on the regional grid

In some cases, LiDAR is not available, so our information is derived from Digital Surface Models (DSMs) that have been produced from stereo imagery, as well as four-band imagery that helps to classify vegetation and impermeable surfaces so we can avoid trees and place panels on rooftops. These are not as precise as LiDAR measurements. When there is no 3D data available, the information for the record is based on a 10 kilometer grid, and all the properties within that grid will have the same information. The data related to these interpolated sites are less reliable than the stereo-imagery based DSMs or the LiDAR-based DSMs, but they are still useful for initial calculations.

The result of this simulation is an instant property-level solar model that will be refined through the following successive stages:

  1. Estimate. By interacting with the model to change the system size, installed cost per Watt, intensity of sunlight, or other factors, you can refine the estimated benefits of installing solar panels. The simulation can apply various financing plans, such as leases, loans and PPAs at different rates and terms to understand the relative benefits.
  2. Design. Once a system design if complete, data on equipment elements such as solar panels, inverters and racking will be added to the Solar Profile. These will be applied to further refine the solar benefits, based on both the costs and performance. The designed components can be discovered once the Solar Profile has reached this stage.
  3. Install. When the Solar Profile is in the installation stage, data related to the contractor that will be installing the solar panels is added to the Solar Profile.
  4. Generation. Once the installation is complete, and the solar energy system is generating electricity, the Solar Profile can be queried for historical system performance as well as installed equipment, the installer, the installed cost per Watt, commission date and other factors.

The result is a platform with valuable data for the full lifecycle of solar projects that can be accessed through an API for new, unique solar applications in such fields as solar finance, sales and marketing, ratings, securities, installation, permitting, incentives development, real estate and emissions reduction. If it involves solar energy, Geostellar has the data and interfaces you’ll need for your program.

We look forward to seeing what you create!

Getting Started On A Solar Application

Register for your Geostellar Developer Account

Our API is available to professional software developers, hobbyists, solar installers, equipment distributors, financing companies, rating agencies, analysts, utilities, public administrators, solar sales and marketing organizations, non-profits, researchers, educators and other individuals and groups. Initially, all developers will receive a test account geographically limited to Washington, DC with a limitation on the number of queries to 10,000. Your usage will be governed by the Geostellar Solar Application Development Terms & Conditions. A Commercial or Academic License will be required for to access the full data set and to publish your Solar Application on the Geostellar platform. This might involve either a licensing fee or a partnership agreement. Free academic and research licenses are also available. Once you’ve registered, a developer relations associate will contact you to work out the proper license.

Register as a developer

Your API Key

Once you are registered, you’ll see your API key here:

Your API Key

Add the API Key as a url param `api_key`.

Building a Search String

To build a search string, simply attach the address to look up and your API Key to a URL pointing at Geostellar:

https://geostellar.com/api/v3/documents/search?specified_address= { Search Address } &api_key= { Your API key }

Here is an example:

https://geostellar.com/api/v3/documents/search?specified_address=729+6th+st%2C+washington+dc&api_key=yourAPIKey

Adding a monthly electric bill

Energy savings are calculated using the homeowner's current average monthly electricity bill. By default, the bill is set to a regional average for this address. You can view this average monthly bill by reading the "average_monthly_bill" key in the JSON response.

If you have access to an average monthly bill amount that you would like you use in the calculations, you can specify the monthly bill by adding the url parameter site_overrides[monthly_bill] = 100

The specified monthly bill must be greater than 0, and decimal values will be rounded to the nearest whole dollar, like this:

https://geostellar.com/api/v3/documents/search?specified_address= { Search Address } &monthly_bill= { integer dollars } &api_key= { Your API key }

Here is an example:

https://geostellar.com/api/v3/documents/search?specified_address=729+6th+st%2C+washington+dc&monthly_bill=100&api_key=yourAPIKey

Building A Solar Application

Geostellar’s API uses a JSON format.

The API is organized according to attributes of the Solar Profile. These attributes will give you everything you need to quickly build a robust Solar Application for the Web or a mobile device.

User Attributes

This is a property owner

get Returns information assigned to a particular user and the fields associated them.
/users/:id
Parameter: Value: Type: Description:
api_key String Your Developer API Key
password String User's Password
phone String User's Phone Number
first_name String User's First Name
last_name String User's Description
street_address_1 String User's Street Address Line 1
street_address_2 String User's Street Address Line 2
city String User's City
state String User's State
zip_code String User's Zipcode
https://geostellar.com/api/v3/users/:id
put Updates a user and returns the associated fields.
/users/:id
Parameter: Value: Type: Description:
api_key String Your Developer API Key
auth_token String User's authentication token
password String User's Password
phone String User's Phone Number
first_name String User's First Name
last_name String User's Description
street_address_1 String User's Street Address Line 1
street_address_2 String User's Street Address Line 2
city String User's City
state String User's State
zip_code String User's Zipcode
https://geostellar.com/api/v3/users/:id
post Creates a new user and returns the associated fields.
/users
Parameter: Value: Type: Description:
api_key String Your Developer API Key
password String User's Password
phone String User's Phone Number
first_name String User's First Name
last_name String User's Description
street_address_1 String User's Street Address Line 1
street_address_2 String User's Street Address Line 2
city String User's City
state String User's State
zip_code String User's Zipcode
https://geostellar.com/api/v3/users

Authentication Attributes

This is for authenticating a user

post Logging in as a user.
/authentications
Parameter: Value: Type: Description:
api_key String Your Developer API Key
password String User's Password
https://geostellar.com/api/v3/authentications
delete Logging out as a user.
/authentications
Parameter: Value: Type: Description:
api_key String Your Developer API Key
auth_token String User's authentication token
https://geostellar.com/api/v3/authentications

PV Module Attributes

This is for requesting a solar modules.

get Get the details of a solar module by ID
/pv_modules/:id
Parameter: Value: Type: Description:
api_key String Your Developer API Key
id Integer PV Module's ID
https://geostellar.com/api/v3/pv_modules/:id
get Get a paged list of pv modules
/pv_modules
Parameter: Value: Type: Description:
api_key String Your Developer API Key
start_index Integer Start index for pagination.
https://geostellar.com/api/v3/pv_modules

Incentive Attributes

This is for requesting financial incentives.

get Get the details of an incentive by ID
/incentives/:id
Parameter: Value: Type: Description:
api_key String Your Developer API Key
id Integer Incentive ID (NREL code)
https://geostellar.com/api/v3/incentives/:id
get Get a paged list of incentives
/incentives
Parameter: Value: Type: Description:
api_key String Your Developer API Key
start_index Integer Start index for pagination.
https://geostellar.com/api/v3/incentives

Solar Estimate Attributes

This is for requesting a solar profile.

get Retrieves an estimate for a new address
/documents/search
Parameter: Value: Type: Description:
api_key String Your Developer API Key
specified_address String Address for residence
latitude Double Latitude for residence
longitude Double Longitude for residence
specified_promotional_code String Promotional Code
kwh_per_kw String Kilowatt-Hour per kilowatt of system capacity
cost_per_watt Decimal Cost per Watt for residence
discount_per_watt Decimal Discount per watt for solar system
discount_percent Decimal Discount per watt for solar system
monthly_bill Integer Monthly Bill for residence
lifetime_yrs Integer Lifetime of solar system
price_per_kwh Decimal Price per Kilowatt-Hour for a PPA system
product_kind String Finance Type [cash_product, svc_loan_product, generic_ppa_product, solarown_product]
pv_module_id Integer ID of PV Module (See PV Module Index)
requested_downpayment Integer Downpayment amount for solar system
selected_finance_product_id Integer ID of Selected Finance Product
utility_rate Decimal Utility Rate for residence
utility_rate_inflation Decimal Utility Rate Inflation percentage for residence
https://geostellar.com/api/v3/documents/search
post Saves a solar estimate
/documents
Parameter: Value: Type: Description:
api_key String Your Developer API Key
test Boolean Performs a mock request
referral_email String Homeowner's Email Address
referral_first_name String Homeowner's First Name
referral_last_name String Homeowner's Last Name
referral_mobile String Homeowner's Mobile Phone Number
specified_address String Address for residence
latitude Double Latitude for residence
longitude Double Longitude for residence
specified_promotional_code String Promotional Code
kwh_per_kw String Kilowatt-Hour per kilowatt of system capacity
cost_per_watt Decimal Cost per Watt for residence
discount_per_watt Decimal Discount per watt for solar system
discount_percent Decimal Discount per watt for solar system
monthly_bill Integer Monthly Bill for residence
lifetime_yrs Integer Lifetime of solar system
price_per_kwh Decimal Price per Kilowatt-Hour for a PPA system
product_kind String Finance Type [cash_product, svc_loan_product, generic_ppa_product, solarown_product]
pv_module_id Integer ID of PV Module (See PV Module Index)
requested_downpayment Integer Downpayment amount for solar system
selected_finance_product_id Integer ID of Selected Finance Product
utility_rate Decimal Utility Rate for residence
utility_rate_inflation Decimal Utility Rate Inflation percentage for residence
utm_campaign String UTM Campaign (All UTM values must be present to track)
utm_medium String UTM Medium (All UTM values must be present to track)
utm_source String UTM Source (All UTM values must be present to track)
extra Hash Key-value pairs to store custom data
https://geostellar.com/api/v3/documents
get Retrieves a saved solar estimate
/documents/:id
Parameter: Value: Type: Description:
api_key String Your Developer API Key
id Integer ID of Document
specified_address String Address for residence
kwh_per_kw String Kilowatt-Hour per kilowatt of system capacity
cost_per_watt Decimal Cost per Watt for residence
discount_per_watt Decimal Discount per watt for solar system
discount_percent Decimal Discount per watt for solar system
monthly_bill Integer Monthly Bill for residence
lifetime_yrs Integer Lifetime of solar system
price_per_kwh Decimal Price per Kilowatt-Hour for a PPA system
product_kind String Finance Type [cash_product, svc_loan_product, generic_ppa_product, solarown_product]
pv_module_id Integer ID of PV Module (See PV Module Index)
requested_downpayment Integer Downpayment amount for solar system
selected_finance_product_id Integer ID of Selected Finance Product
utility_rate Decimal Utility Rate for residence
utility_rate_inflation Decimal Utility Rate Inflation percentage for residence
https://geostellar.com/api/v3/documents/:id
put Updates a solar estimate
/documents/:id
Parameter: Value: Type: Description:
api_key String Your Developer API Key
id Integer ID of Document
specified_address String Address for residence
kwh_per_kw String Kilowatt-Hour per kilowatt of system capacity
cost_per_watt Decimal Cost per Watt for residence
discount_per_watt Decimal Discount per watt for solar system
discount_percent Decimal Discount per watt for solar system
monthly_bill Integer Monthly Bill for residence
lifetime_yrs Integer Lifetime of solar system
price_per_kwh Decimal Price per Kilowatt-Hour for a PPA system
product_kind String Finance Type [cash_product, svc_loan_product, generic_ppa_product, solarown_product]
pv_module_id Integer ID of PV Module (See PV Module Index)
requested_downpayment Integer Downpayment amount for solar system
selected_finance_product_id Integer ID of Selected Finance Product
utility_rate Decimal Utility Rate for residence
utility_rate_inflation Decimal Utility Rate Inflation percentage for residence
https://geostellar.com/api/v3/documents/:id

Adding A Solar Potential Heat Map

Solar Heat Map Example

You can add a Solar Potential Heat Map to an existing Google Map by using the address.region.wms_url from the Solar Estimate JSON results and the following function below

addRasterOverlayToMap.js

/*
 * // Example Usage
 * 
 * var map, rasterOverlay, wmsUrl;
 *
 * // Get Raster Url
 * wmsUrl = solarEstimate.address.region.wms_url;
 *
 * // Create A Google Map
 * map = new google.maps.Map(element, mapOptions)
 *
 * // Add Raster to Google Map
 * rasterOverlay = addRasterOverlayToMap(map, wmsUrl);
 *
 */

var addRasterOverlayToMap;

addRasterOverlayToMap = function(googleMap, rasterUrl) {
  var rasterOverlay, tileHeight, tileWidth;

  if (rasterUrl == null) {
    console.log("The raster url provided is null");
    return;
  }

  tileWidth = tileHeight = 256.0;
  googleMap.setTilt(0);

  rasterOverlay = new google.maps.ImageMapType({
    alt: "Solar Raster",
    name: "Solar Raster",
    isPng: false,
    maxZoom: 20,
    minZoom: 14,
    tileSize: new google.maps.Size(tileWidth, tileHeight),
    getTileUrl: (function(_this) {
      return function(tile, zoom) {
        var lr, projection, ul, zpow;
        projection = googleMap.getProjection();
        zpow = Math.pow(2, zoom);
        ul = projection.fromPointToLatLng(new google.maps.Point(tile.x * tileWidth / zpow, (tile.y + 1) * tileHeight / zpow));
        lr = projection.fromPointToLatLng(new google.maps.Point((tile.x + 1) * tileWidth / zpow, tile.y * tileHeight / zpow));
        return baseUrl + "&BBOX=" + [ul.lng(), ul.lat(), lr.lng(), lr.lat()].join(',');
      };
    })(this)
  });

  gooleMap.overlayMapTypes.push(rasterOverlay);

  return rasterOverlay;
};