**European Economic Area (EEA) developers**

> [!NOTE]
> If your billing address is in the European Economic Area, effective on 8 July 2025, the [Google
> Maps Platform EEA Terms of Service](https://cloud.google.com/terms/maps-platform/eea) will apply to your use of the Services. [Learn more](https://developers.google.com/maps/comms/eea/faq.md.txt). In addition, certain content from the Solar API will no longer be returned. [Learn more](https://developers.google.com/maps/comms/eea/solar.md.txt).

[Video](https://www.youtube.com/watch?v=UK2oE3hdZpM)

The [buildingInsights](https://developers.google.com/maps/documentation/solar/reference/rest/v1/buildingInsights.md.txt) endpoint provides insights about
the location, dimensions, and solar potential of a building. In particular, you
can get information about:

- Solar potential, including solar panel size, annual amount of sunshine, carbon offset factors, and more
- Solar panel position, orientation, and energy production
- Estimated monthly energy bill of optimal solar layout and associated costs and benefits

To learn more about how the Solar API defines solar potential and
sunniness, see [Solar API Concepts](https://developers.google.com/maps/documentation/solar/concepts.md.txt).

> [!NOTE]
> **Note:** Results may vary between the outputs of the Solar API and the [Geocoding API](https://developers.google.com/maps/documentation/geocoding). The Solar API uses Google's proprietary building information to calculate insights about map features classified as a "building," while the Geocoding API surfaces specific information about addresses around a location.

The APIs Explorer lets you make live requests so that you can get familiar with
the API and the API options:
[Try it!](https://developers.google.com/maps/documentation/solar/building-insights.md.txt#try_it)

## About building insights requests

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

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

Include your request URL [parameters](https://developers.google.com/maps/documentation/solar/reference/rest/v1/buildingInsights/findClosest.md.txt#query-parameters) that specify the latitude and
longitude coordinates of the location and the minimum required quality level
allowed in the results.

## About building insights responses

The Solar API returns information about the location, dimensions, and
solar potential of a building in the
[response body](https://developers.google.com/maps/documentation/solar/reference/rest/v1/buildingInsights/findClosest.md.txt#response-body).

### Imagery quality

In some cases, requested
[imagery quality](https://developers.google.com/maps/documentation/solar/reference/rest/v1/dataLayers.md.txt#imageryquality)
in a specific location may differ from the imagery quality available. In such
scenarios, the following behavior is expected:

| Scenario | Response behavior |
|---|---|
| A location doesn't have imagery that meets `requiredQuality`. | Solar API returns a `NOT_FOUND` error with a 404 status code. |
| A request specifies a certain `requiredQuality`, but only data of a higher imagery quality level is available. | Solar API returns the highest quality data available at the location. |

> [!NOTE]
> **Note:** `IMAGERY_QUALITY_UNSPECIFIED` is not an expected input in a building insights request.

## Building insights request example

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

### API key

To make a request using an API key, include your API key as an input parameter:

```
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.

### OAuth token

**Note:** This format is for a testing environment only. For more information, see [Use OAuth](https://developers.google.com/maps/documentation/solar/oauth-token).

To make a request using OAuth, 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 using TypeScript, include either your API key or OAuth token in the request. The following example uses an API key:

```typescript
/**
 * 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.
 */
export async function findClosestBuilding(
  location: google.maps.LatLng,
  apiKey: string,
): Promise<BuildingInsightsResponse> {
  const args = {
    '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);
  const params = new URLSearchParams({ ...args, key: apiKey });
  // https://developers.google.com/maps/documentation/solar/reference/rest/v1/buildingInsights/findClosest
  return fetch(`https://solar.googleapis.com/v1/buildingInsights:findClosest?${params}`).then(
    async (response) => {
      const content = await response.json();
      if (response.status != 200) {
        console.error('findClosestBuilding\n', content);
        throw content;
      }
      console.log('buildingInsightsResponse', content);
      return content;
    },
  );
}
```

> [!NOTE]
> **Note:** Read the [guide](https://developers.google.com/maps/documentation/javascript/using-typescript.md.txt) on using TypeScript and Google Maps.

#### Data type definitions

The following data types are supported:

```typescript
export interface DataLayersResponse {
  imageryDate: Date;
  imageryProcessedDate: Date;
  dsmUrl: string;
  rgbUrl: string;
  maskUrl: string;
  annualFluxUrl: string;
  monthlyFluxUrl: string;
  hourlyShadeUrls: string[];
  imageryQuality: 'HIGH' | 'MEDIUM' | 'BASE';
}

export interface Bounds {
  north: number;
  south: number;
  east: number;
  west: number;
}

// https://developers.google.com/maps/documentation/solar/reference/rest/v1/buildingInsights/findClosest
export interface BuildingInsightsResponse {
  name: string;
  center: LatLng;
  boundingBox: LatLngBox;
  imageryDate: Date;
  imageryProcessedDate: Date;
  postalCode: string;
  administrativeArea: string;
  statisticalArea: string;
  regionCode: string;
  solarPotential: SolarPotential;
  imageryQuality: 'HIGH' | 'MEDIUM' | 'BASE';
}

export interface SolarPotential {
  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;
}

export interface SizeAndSunshineStats {
  areaMeters2: number;
  sunshineQuantiles: number[];
  groundAreaMeters2: number;
}

export interface RoofSegmentSizeAndSunshineStats {
  pitchDegrees: number;
  azimuthDegrees: number;
  stats: SizeAndSunshineStats;
  center: LatLng;
  boundingBox: LatLngBox;
  planeHeightAtCenterMeters: number;
}

export interface SolarPanel {
  center: LatLng;
  orientation: 'LANDSCAPE' | 'PORTRAIT';
  segmentIndex: number;
  yearlyEnergyDcKwh: number;
}

export interface SolarPanelConfig {
  panelsCount: number;
  yearlyEnergyDcKwh: number;
  roofSegmentSummaries: RoofSegmentSummary[];
}

export interface RoofSegmentSummary {
  pitchDegrees: number;
  azimuthDegrees: number;
  panelsCount: number;
  yearlyEnergyDcKwh: number;
  segmentIndex: number;
}

export interface LatLng {
  latitude: number;
  longitude: number;
}

export interface LatLngBox {
  sw: LatLng;
  ne: LatLng;
}

export interface Date {
  year: number;
  month: number;
  day: number;
}

export interface RequestError {
  error: {
    code: number;
    message: string;
    status: string;
  };
}
```

> [!NOTE]
> **Note:** Read the [guide](https://developers.google.com/maps/documentation/javascript/using-typescript.md.txt) on using TypeScript and Google Maps.

That request produces a [JSON response](https://developers.google.com/maps/documentation/solar/reference/rest/v1/buildingInsights/findClosest.md.txt#response-body) in the form:

```json
{
  "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]
> **Note:** [buildingInsights](https://developers.google.com/maps/documentation/solar/reference/rest/v1/buildingInsights/findClosest.md.txt) always returns information for only one building. If two buildings are exactly the same distance from the requested location, the Solar API arbitrarily identifies a building and returns that building's information. To determine which building was returned, examine the bounding box of the roof.

## Select roof segments for panel placement

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

```json
"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 panels
placed on a specific roof segment. Every panel returned through the
`buildingInsights` endpoint includes a `segmentIndex` value indicating which
roof segment the panel is placed on:

```json
{
        "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 can
filter by `segmentIndex`. For example, if you want to place panels on the
south-facing part of the roof, identify which roof segments have
`azimuthDegrees` values between 90 and 270, then use the corresponding
`segmentIndex` to filter the full panel list for those roof segments.

## Request detected arrays data

The Solar API detects existing rooftop solar installations using
satellite imagery. For information on supported regions, see the
[coverage map](https://developers.google.com/maps/documentation/solar/coverage.md.txt).

To request detected arrays data, set the `additionalInsights`
parameter to `DETECTED_ARRAYS` in your request body:

```
curl -X GET "https://solar.googleapis.com/v1/buildingInsights:findClosest?location.latitude=49.9263&location.longitude=11.5870&additionalInsights=DETECTED_ARRAYS&required_quality=BASE&key=YOUR_API_KEY"
```

The response body includes the following detected arrays information:

- Whether solar installations were detected on the building's roof ([`detectionStatus`](https://developers.google.com/maps/documentation/solar/reference/rest/v1/buildingInsights/findClosest.md.txt#detectionstatus)).
- The date of the latest satellite imagery capture used for the detections (`latestCaptureDate`), if available.
- A list of the detected solar arrays (`arrays`). Each array represents a single contiguous area of solar panels and includes:
  - `polygonGeojson`: A GeoJSON representation of the roof area where solar panels were detected. The GeoJSON data is in [RFC 7946](https://datatracker.ietf.org/doc/html/rfc7946) format and represents a `Polygon` for a single contiguous area. A polygon that contains holes is represented by several loops.

The `arrays` list is only populated when `detectionStatus` is
`DETECTION_STATUS_ARRAYS_DETECTED`.

The following example shows a response for a building with detected arrays
(the response is truncated):

```json
{
  "name": "buildings/ChIJ7zV8T9a8oUcRapOpazDCQEE",
  "center": {
    "latitude": 49.9262649,
    "longitude": 11.587273999999999
  },
  "imageryQuality": "HIGH",
  "imageryDate": {
    "year": 2016,
    "month": 6,
    "day": 11
  },
  ...
  "detectedArrays": {
    "detectionStatus": "DETECTION_STATUS_ARRAYS_DETECTED",
    "arrays": [
      {
        "polygonGeojson": {
          "type": "Polygon",
          "coordinates": [
            [
              [11.5873992221349, 49.9262569599232],
              [11.5873991692473, 49.9262899326168],
              [11.5873805103546, 49.9262899153611],
              [11.5873807666599, 49.9262569221221],
              [11.5873992221349, 49.9262569599232]
            ]
          ]
        }
      },
      ...
    ],
    "latestCaptureDate": {
      "year": 2025,
      "month": 5,
      "day": 14
    }
  }
}
```

> [!NOTE]
> **Note:** Detected arrays data is derived from different satellite imagery than building insights data, Google Maps, and the RGB imagery returned by the `dataLayers` endpoint. This imagery is orthorectified, meaning it is processed to remove distortions from satellite imagery captures, and is often captured at a different date. As a result, the imagery capture date for building insights data (`imageryDate`) might differ from the imagery capture date for detected arrays data (`latestCaptureDate`), and the panels described by `polygonGeojson` might not line up exactly with, or might not be visible in, Google Maps or the `dataLayers` RGB imagery. This does not affect detection of panel presence or estimates of panel area and dimensions.

## Try it!

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

1. Select the API icon api
   on the right side of the page.

2. Optionally edit the request parameters.

3. Select the **Execute** 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 icon
   fullscreen to expand the APIs Explorer window.