Der Endpunkt „buildingInsights“ liefert Statistiken zu Standort, Abmessungen und Solarpotenzial eines Gebäudes. Insbesondere können Sie Informationen zu folgenden Themen abrufen:
- Solarpotenzial, einschließlich Größe der Solaranlage, jährliche Sonnenscheindauer, Faktoren für den CO2-Ausgleich und mehr
- Position, Ausrichtung und Energieerzeugung der Solaranlage
- Geschätzte monatliche Stromrechnung für die optimale Solaranlage sowie die damit verbundenen Kosten und Vorteile
Weitere Informationen dazu, wie das Solarpotenzial und die Sonnenscheindauer in der Solar API definiert werden, finden Sie unter Konzepte der Solar API.
Mit dem APIs Explorer können Sie Live-Anfragen stellen, um sich mit der API und den API-Optionen vertraut zu machen:
Anfragen zu Gebäudestatistiken
Wenn Sie Gebäudestatistiken anfordern möchten, senden Sie eine HTTP/GET-Anfrage an:
https://solar.googleapis.com/v1/buildingInsights:findClosest?key=YOUR_API_KEY
Fügen Sie die URL-Parameter Ihrer Anfrage hinzu, die die Breiten- und Längengradkoordinaten des Standorts und die mindestens erforderliche Qualitätsstufe angeben, die in den Ergebnissen zulässig ist.
Antworten zu Gebäudestatistiken
Qualität der Bilder
In einigen Fällen kann die angeforderte Bildqualität an einem bestimmten Standort von der verfügbaren Bildqualität abweichen. In solchen Fällen ist das folgende Verhalten zu erwarten:
| Szenario | Antwortverhalten |
|---|---|
Für einen Standort sind keine Bilder verfügbar, die requiredQuality erfüllen. |
Die Solar API gibt einen NOT_FOUND-Fehler mit dem Statuscode 404 zurück. |
In einer Anfrage wird eine bestimmte requiredQuality angegeben, aber es sind nur Daten mit einer höheren Bildqualitätsstufe verfügbar. |
Die Solar API gibt die Daten mit der höchsten verfügbaren Qualität am Standort zurück. |
Beispiel für eine Anfrage zu Gebäudestatistiken
Im folgenden Beispiel werden Gebäudestatistiken für den Standort mit den Koordinaten Breitengrad = 37,4450 und Längengrad = -122,1390 angefordert:
API-Schlüssel
Wenn Sie eine Anfrage an die URL in der Antwort senden möchten, fügen Sie Ihren API-Schlüssel an die URL an:
curl -X GET "https://solar.googleapis.com/v1/buildingInsights:findClosest?location.latitude=37.4450 &location.longitude=-122.1390 &requiredQuality=HIGH &key=YOUR_API_KEY"
Sie können auch HTTP-Anfragen stellen, indem Sie die URL in der cURL-Anfrage in die URL-Leiste Ihres Browsers einfügen. Wenn Sie den API-Schlüssel übergeben, erhalten Sie bessere Nutzungs- und Analysemöglichkeiten sowie eine bessere Zugriffssteuerung auf die Antwortdaten.
OAuth-Token
Hinweis:Dieses Format ist nur für eine Testumgebung vorgesehen. Weitere Informationen finden Sie unter OAuth verwenden.
Wenn Sie eine Anfrage an die URL in der Antwort senden möchten, geben Sie den Namen Ihres Abrechnungsprojekts und Ihr OAuth-Token an:
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
Wenn Sie eine Anfrage an die URL in der Antwort senden möchten, fügen Sie entweder Ihren API-Schlüssel oder Ihr OAuth-Token in die Anfrage ein. Im folgenden Beispiel wird ein API-Schlüssel verwendet:
/** * 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; }, ); }
Datentypdefinitionen
Die folgenden Datentypen werden unterstützt:
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; }; }
Diese Anfrage erzeugt eine JSON-Antwort im folgenden Format:
{ "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 } }
Dachsegmente für die Platzierung von Solaranlagen auswählen
In einigen Fällen können Sie bestimmte Dachsegmente für die Platzierung von Solaranlagen auswählen. roofSegmentStats enthält Informationen zu Größe, Ausrichtung und Sonnenscheinquantilen eines bestimmten Dachsegments:
"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 }, /.../ ],
Anhand dieser Merkmale können Sie nur die Solaranlagen auswählen, die auf einem bestimmten Dachsegment platziert sind. Jede Solaranlage, die über den Endpunkt buildingInsights zurückgegeben wird, enthält einen segmentIndex-Wert, der angibt, auf welchem Dachsegment die Solaranlage platziert ist:
{ "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 } ] },
Wenn Sie Solaranlagen auf Dachsegmenten mit bestimmten Merkmalen auswählen möchten, können Sie nach segmentIndex filtern. Wenn Sie beispielsweise Solaranlagen auf der Südseite des Daches platzieren möchten, ermitteln Sie, welche Dachsegmente azimuthDegrees-Werte zwischen 90 und 270 haben. Verwenden Sie dann den entsprechenden segmentIndex, um die vollständige Liste der Solaranlagen nach diesen Dachsegmenten zu filtern.
Testen!
Mit dem APIs Explorer können Sie Beispielanfragen stellen, um sich mit der API und den API-Optionen vertraut zu machen.
Wählen Sie rechts auf der Seite das API-Symbol api aus.
Optional können Sie die Anfrageparameter bearbeiten.
Wählen Sie die Schaltfläche Ausführen aus. Wählen Sie im Dialogfeld das Konto aus, mit dem Sie die Anfrage stellen möchten.
Wählen Sie im APIs Explorer-Bereich das Symbol für den Vollbildmodus fullscreen aus, um das APIs Explorer-Fenster zu maximieren.