Make a building insights request

  • The Building Insights API provides data on a building's solar potential, panel placement, and estimated energy production based on location coordinates.

  • Request building insights by sending an HTTP GET request with location coordinates and desired quality level.

  • The API response includes details like building location, solar panel configurations, potential energy savings, and financial analyses.

  • You can explore the API and test requests using the API Explorer.

  • Returned data leverages Google's building information and may differ from the Geocoding API's results.

European Economic Area (EEA) developers If your billing address is in the European Economic Area, effective on 8 July 2025, the Google Maps Platform EEA Terms of Service will apply to your use of the Services.Learn more. In addition, certain content from the Solar API will no longer be returned.Learn more.

ThebuildingInsights endpoint provides insights aboutthe location, dimensions, and solar potential of a building. In particular, youcan get information about:

  • Solar potential, including solar panel size, annual amount of sunshine, carbonoffset factors, and more
  • Solar panel position, orientation, and energy production
  • Estimated monthly energy bill of optimal solar layout and associated costs andbenefits

To learn more about how the Solar API defines solar potential andsunniness, seeSolar API Concepts.

Note: Results may vary between the outputs of the Solar API and theGeocoding API. The Solar API uses Google's proprietary buildinginformation to calculate insights about map features classified as a "building,"while the Geocoding API surfaces specific information about addresses around alocation.

The APIs Explorer lets you make live requests so that you can get familiar withthe API and the API options:

About building insights requests

To request building insights, send an HTTP GET request to:

https://solar.googleapis.com/v1/buildingInsights:findClosest?key=YOUR_API_KEY

Include your request URLparameters that specify the latitude andlongitude coordinates of the location and the minimum required quality levelallowed in the results.

Example building insights request

The following example requests building insights information for the location atthe coordinates of latitude = 37.4450 and longitude = -122.1390:

API key

To make a request to the URL in the response, append your API key to the URL:

curl -X GET "https://solar.googleapis.com/v1/buildingInsights:findClosest?location.latitude=37.4450&location.longitude=-122.1390&requiredQuality=HIGH&key=YOUR_API_KEY"

You can also make HTTP requests by pasting the URL in the cURL request into your browser's URL bar. Passing the API key provides you with better usage and analytics capabilities and better access control to the response data.

OAuth token

Note: This format is for a testing environment only. For more information, seeUse OAuth.

To make a request to the URL in the response, pass in your billing project name and your OAuth token:

curl -H "Authorization: Bearer $(gcloud auth print-access-token)" \  -H "X-Goog-User-Project:PROJECT_NUMBER_OR_ID" \  "https://solar.googleapis.com/v1/buildingInsights:findClosest?location.latitude=37.4450&location.longitude=-122.1390"

TypeScript

To make a request to the URL in the response, include either your API key or OAuth token in the request. Here's an example that uses an API key:

/** * Fetches the building insights information from the Solar API. *   https://developers.google.com/maps/documentation/solar/building-insights * * @param  {LatLng} location      Point of interest as latitude longitude. * @param  {string} apiKey        Google Cloud API key. * @return {Promise<DataLayersResponse>}  Building Insights response. */exportasyncfunctionfindClosestBuilding(location:google.maps.LatLng,apiKey:string,):Promise<BuildingInsightsResponse>{constargs={'location.latitude':location.lat().toFixed(5),'location.longitude':location.lng().toFixed(5),// The Solar API always returns the highest quality imagery available.required_quality:'BASE',};console.log('GET buildingInsights\n',args);constparams=newURLSearchParams({...args,key:apiKey});// https://developers.google.com/maps/documentation/solar/reference/rest/v1/buildingInsights/findClosestreturnfetch(`https://solar.googleapis.com/v1/buildingInsights:findClosest?${params}`).then(async(response)=>{constcontent=awaitresponse.json();if(response.status!=200){console.error('findClosestBuilding\n',content);throwcontent;}console.log('buildingInsightsResponse',content);returncontent;},);}
Note: Read theguide on using TypeScript and Google Maps.

Data type definitions

The following data types are supported:

exportinterfaceDataLayersResponse{imageryDate:Date;imageryProcessedDate:Date;dsmUrl:string;rgbUrl:string;maskUrl:string;annualFluxUrl:string;monthlyFluxUrl:string;hourlyShadeUrls:string[];imageryQuality:'HIGH'|'MEDIUM'|'BASE';}exportinterfaceBounds{north:number;south:number;east:number;west:number;}// https://developers.google.com/maps/documentation/solar/reference/rest/v1/buildingInsights/findClosestexportinterfaceBuildingInsightsResponse{name:string;center:LatLng;boundingBox:LatLngBox;imageryDate:Date;imageryProcessedDate:Date;postalCode:string;administrativeArea:string;statisticalArea:string;regionCode:string;solarPotential:SolarPotential;imageryQuality:'HIGH'|'MEDIUM'|'BASE';}exportinterfaceSolarPotential{maxArrayPanelsCount:number;panelCapacityWatts:number;panelHeightMeters:number;panelWidthMeters:number;panelLifetimeYears:number;maxArrayAreaMeters2:number;maxSunshineHoursPerYear:number;carbonOffsetFactorKgPerMwh:number;wholeRoofStats:SizeAndSunshineStats;buildingStats:SizeAndSunshineStats;roofSegmentStats:RoofSegmentSizeAndSunshineStats[];solarPanels:SolarPanel[];solarPanelConfigs:SolarPanelConfig[];financialAnalyses:object;}exportinterfaceSizeAndSunshineStats{areaMeters2:number;sunshineQuantiles:number[];groundAreaMeters2:number;}exportinterfaceRoofSegmentSizeAndSunshineStats{pitchDegrees:number;azimuthDegrees:number;stats:SizeAndSunshineStats;center:LatLng;boundingBox:LatLngBox;planeHeightAtCenterMeters:number;}exportinterfaceSolarPanel{center:LatLng;orientation:'LANDSCAPE'|'PORTRAIT';segmentIndex:number;yearlyEnergyDcKwh:number;}exportinterfaceSolarPanelConfig{panelsCount:number;yearlyEnergyDcKwh:number;roofSegmentSummaries:RoofSegmentSummary[];}exportinterfaceRoofSegmentSummary{pitchDegrees:number;azimuthDegrees:number;panelsCount:number;yearlyEnergyDcKwh:number;segmentIndex:number;}exportinterfaceLatLng{latitude:number;longitude:number;}exportinterfaceLatLngBox{sw:LatLng;ne:LatLng;}exportinterfaceDate{year:number;month:number;day:number;}exportinterfaceRequestError{error:{code:number;message:string;status:string;};}
Note: Read theguide on using TypeScript and Google Maps.

Example response object

That request produces aJSON response in the form:

{"name":"buildings/ChIJh0CMPQW7j4ARLrRiVvmg6Vs","center":{"latitude":37.4449439,"longitude":-122.13914659999998},"imageryDate":{"year":2022,"month":8,"day":14},"postalCode":"94303","administrativeArea":"CA","statisticalArea":"06085511100","regionCode":"US","solarPotential":{"maxArrayPanelsCount":1163,"maxArrayAreaMeters2":1903.5983,"maxSunshineHoursPerYear":1802,"carbonOffsetFactorKgPerMwh":428.9201,"wholeRoofStats":{"areaMeters2":2399.3958,"sunshineQuantiles":[351,1396,1474,1527,1555,1596,1621,1640,1664,1759,1864],"groundAreaMeters2":2279.71},"roofSegmentStats":[{"pitchDegrees":11.350553,"azimuthDegrees":269.6291,"stats":{"areaMeters2":452.00052,"sunshineQuantiles":[408,1475,1546,1575,1595,1606,1616,1626,1635,1643,1761],"groundAreaMeters2":443.16},"center":{"latitude":37.444972799999995,"longitude":-122.13936369999999},"boundingBox":{"sw":{"latitude":37.444732099999996,"longitude":-122.1394224},"ne":{"latitude":37.4451909,"longitude":-122.13929279999999}},"planeHeightAtCenterMeters":10.7835045},/.../],"solarPanelConfigs":[{"panelsCount":4,"yearlyEnergyDcKwh":1819.8662,"roofSegmentSummaries":[{"pitchDegrees":12.273684,"azimuthDegrees":179.12555,"panelsCount":4,"yearlyEnergyDcKwh":1819.8663,"segmentIndex":1}]},/.../]"financialAnalyses":[{"monthlyBill":{"currencyCode":"USD","units":"20"},"panelConfigIndex":-1},{"monthlyBill":{"currencyCode":"USD","units":"25"},"panelConfigIndex":-1},{"monthlyBill":{"currencyCode":"USD","units":"30"},"panelConfigIndex":-1},{"monthlyBill":{"currencyCode":"USD","units":"35"},"panelConfigIndex":0,"financialDetails":{"initialAcKwhPerYear":1546.8864,"remainingLifetimeUtilityBill":{"currencyCode":"USD","units":"2563"},"federalIncentive":{"currencyCode":"USD","units":"1483"},"stateIncentive":{"currencyCode":"USD"},"utilityIncentive":{"currencyCode":"USD"},"lifetimeSrecTotal":{"currencyCode":"USD"},"costOfElectricityWithoutSolar":{"currencyCode":"USD","units":"10362"},"netMeteringAllowed":true,"solarPercentage":86.7469,"percentageExportedToGrid":52.136684},"leasingSavings":{"leasesAllowed":true,"leasesSupported":true,"annualLeasingCost":{"currencyCode":"USD","units":"335","nanos":85540771},"savings":{"savingsYear1":{"currencyCode":"USD","units":"-10"},"savingsYear20":{"currencyCode":"USD","units":"1098"},"presentValueOfSavingsYear20":{"currencyCode":"USD","units":"568","nanos":380859375},"financiallyViable":true,"savingsLifetime":{"currencyCode":"USD","units":"1098"},"presentValueOfSavingsLifetime":{"currencyCode":"USD","units":"568","nanos":380859375}}},"cashPurchaseSavings":{"outOfPocketCost":{"currencyCode":"USD","units":"5704"},"upfrontCost":{"currencyCode":"USD","units":"4221"},"rebateValue":{"currencyCode":"USD","units":"1483","nanos":40039063},"paybackYears":11.5,"savings":{"savingsYear1":{"currencyCode":"USD","units":"325"},"savingsYear20":{"currencyCode":"USD","units":"7799"},"presentValueOfSavingsYear20":{"currencyCode":"USD","units":"1083","nanos":500244141},"financiallyViable":true,"savingsLifetime":{"currencyCode":"USD","units":"7799"},"presentValueOfSavingsLifetime":{"currencyCode":"USD","units":"1083","nanos":500244141}}},"financedPurchaseSavings":{"annualLoanPayment":{"currencyCode":"USD","units":"335","nanos":85540771},"rebateValue":{"currencyCode":"USD"},"loanInterestRate":0.05,"savings":{"savingsYear1":{"currencyCode":"USD","units":"-10"},"savingsYear20":{"currencyCode":"USD","units":"1098"},"presentValueOfSavingsYear20":{"currencyCode":"USD","units":"568","nanos":380859375},"financiallyViable":true,"savingsLifetime":{"currencyCode":"USD","units":"1098"},"presentValueOfSavingsLifetime":{"currencyCode":"USD","units":"568","nanos":380859375}}}},],/.../"panelCapacityWatts":400,"panelHeightMeters":1.879,"panelWidthMeters":1.045,"panelLifetimeYears":20,"buildingStats":{"areaMeters2":2533.1233,"sunshineQuantiles":[348,1376,1460,1519,1550,1590,1618,1638,1662,1756,1864],"groundAreaMeters2":2356.03},"solarPanels":[{"center":{"latitude":37.4449659,"longitude":-122.139089},"orientation":"LANDSCAPE","yearlyEnergyDcKwh":455.40714,"segmentIndex":1},/.../]"imageryQuality":"HIGH","imageryProcessedDate":{"year":2023,"month":8,"day":4}}
Note:buildingInsightsalways returns information for only one building. If twobuildings are exactly the same distance from the requested location, theSolar API arbitrarily identifies a building and returns that building'sinformation. To determine which building was returned, examine the bounding boxof the roof.

Select roof segments for panel placement

In some cases, you may choose to select particular roof segments for solarpanel placement.roofSegmentStats provides information about the size,orientation, and sunniness quantiles of a given roof segment:

"roofSegmentStats":[{"pitchDegrees":11.350553,"azimuthDegrees":269.6291,"stats":{"areaMeters2":452.00052,"sunshineQuantiles":[409.601,1482.1255,1553.5117,1582.7875,1602.3456,1613.7804,1623.6434,1634.0812,1642.697,1651.0267,1771.4792],"groundAreaMeters2":443.16},"center":{"latitude":37.4449728,"longitude":-122.1393637},"boundingBox":{"sw":{"latitude":37.4447321,"longitude":-122.1394224},"ne":{"latitude":37.4451909,"longitude":-122.1392928}},"planeHeightAtCenterMeters":10.7835045},{"pitchDegrees":12.273684,"azimuthDegrees":179.12555,"stats":{"areaMeters2":309.87268,"sunshineQuantiles":[650.5504,1701.709,1745.0032,1768.4081,1779.1625,1787.4258,1794.9333,1801.3938,1806.7461,1814.0724,1845.8717],"groundAreaMeters2":302.79},"center":{"latitude":37.4449286,"longitude":-122.1389889},"boundingBox":{"sw":{"latitude":37.4448617,"longitude":-122.1392095},"ne":{"latitude":37.444982,"longitude":-122.1387809}},"planeHeightAtCenterMeters":10.67585},/.../],

Based on these characteristics, you can choose to select only the panelsplaced on a specific roof segment. Every panel returned through thebuildingInsights endpoint includes asegmentIndex value indicating whichroof segment the panel is placed on:

{"panelsCount":142,"yearlyEnergyDcKwh":101170.17,"roofSegmentSummaries":[{"pitchDegrees":12.273684,"azimuthDegrees":179.12555,"panelsCount":122,"yearlyEnergyDcKwh":87260.48,"segmentIndex":1},{"pitchDegrees":11.245564,"azimuthDegrees":179.204,"panelsCount":18,"yearlyEnergyDcKwh":12544.052,"segmentIndex":3},{"pitchDegrees":2.5699794,"azimuthDegrees":86.05642,"panelsCount":1,"yearlyEnergyDcKwh":681.69183,"segmentIndex":10},{"pitchDegrees":0.10844088,"azimuthDegrees":0,"panelsCount":1,"yearlyEnergyDcKwh":683.9312,"segmentIndex":14}]},

To select panels on roof segments with specific characteristics, you canfilter bysegmentIndex. For example, if you want to place panels on thesouth-facing part of the roof, identify which roof segments haveazimuthDegrees values between 90 and 270, then use the correspondingsegmentIndex to filter the full panel list for those roof segments.

Try it!

The APIs Explorer lets you make sample requests sothat you can get familiar with the API and the API options.

  1. Select the API iconapi on the right side of the page.

  2. Optionally edit the request parameters.

  3. Select theExecute button. In the dialog, choose the account that you want to use to make the request.

  4. In the APIs Explorer panel, select the fullscreen iconfullscreen to expand the APIs Explorer window.

Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2025-11-21 UTC.