L'endpoint buildingInsights fornisce informazioni su posizione, dimensioni e potenziale solare di un edificio. In particolare, puoi ricevere informazioni su:
- Potenziale solare, tra cui dimensioni dei pannelli solari, quantità annuale di luce solare, fattori di compensazione delle emissioni di carbonio e altro ancora
- Posizione, orientamento e produzione di energia dei pannelli solari
- Bolletta energetica mensile stimata per il layout solare ottimale e i relativi costi e vantaggi
Per scoprire di più su come l'API Solar definisce il potenziale solare e l'esposizione al sole, consulta Concetti dell'API Solar.
Explorer API ti consente di effettuare richieste in tempo reale per acquisire familiarità con l'API e le relative opzioni:
Informazioni sulle richieste di Building Insights
Per richiedere insight sugli edifici, invia una richiesta GET HTTP a:
https://solar.googleapis.com/v1/buildingInsights:findClosest?key=YOUR_API_KEY
Includi i parametri dell'URL della richiesta che specificano le coordinate di latitudine e longitudine della località e il livello di qualità minimo richiesto consentito nei risultati.
Informazioni sulle risposte di Building Insights
L'API Solar restituisce informazioni sulla posizione, sulle dimensioni e sul potenziale solare di un edificio nel corpo della risposta.
Qualità delle immagini
In alcuni casi, la qualità delle immagini richiesta in una località specifica potrebbe essere diversa da quella disponibile. In questi scenari, il comportamento previsto è il seguente:
| Scenario | Comportamento della risposta |
|---|---|
Una località non dispone di immagini che soddisfano i requisiti di requiredQuality. |
L'API Solar restituisce un errore NOT_FOUND con un codice di stato 404. |
Una richiesta specifica un determinato requiredQuality, ma sono disponibili solo dati di un livello di qualità delle immagini superiore. |
L'API Solar restituisce i dati di qualità più elevata disponibili per la località. |
Esempio di richiesta di Building Insights
L'esempio seguente richiede informazioni sugli insight sugli edifici per la località con le coordinate di latitudine = 37.4450 e longitudine = -122.1390:
Chiave API
Per effettuare una richiesta utilizzando una chiave API, includi la chiave API come parametro di input:
curl -X GET "https://solar.googleapis.com/v1/buildingInsights:findClosest?location.latitude=37.4450 &location.longitude=-122.1390 &requiredQuality=HIGH &key=YOUR_API_KEY"
Puoi anche effettuare richieste HTTP incollando l'URL della richiesta cURL nella barra degli indirizzi del browser.
Token OAuth
Nota: questo formato è destinato esclusivamente a un ambiente di test. Per saperne di più, consulta Utilizza OAuth.
Per effettuare una richiesta utilizzando OAuth, passa il nome del progetto di fatturazione e il token OAuth:
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
Per effettuare una richiesta utilizzando TypeScript, includi la chiave API o il token OAuth nella richiesta. L'esempio seguente utilizza una chiave API:
/** * 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; }, ); }
Definizioni dei tipi di dati
Sono supportati i seguenti tipi di dati:
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; }; }
Questa richiesta genera una risposta JSON nel seguente formato:
{ "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 } }
Seleziona le falde del tetto per il posizionamento dei pannelli
In alcuni casi, puoi scegliere di selezionare segmenti di tetto specifici per il posizionamento dei pannelli solari. roofSegmentStats fornisce informazioni sulle dimensioni,
sull'orientamento e sui quantili di soleggiamento di un determinato segmento del tetto:
"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 }, /.../ ],
In base a queste caratteristiche, puoi scegliere di selezionare solo i pannelli
posizionati su un segmento specifico del tetto. Ogni pannello restituito tramite l'endpoint buildingInsights include un valore segmentIndex che indica su quale segmento del tetto è posizionato il pannello:
{ "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 } ] },
Per selezionare i pannelli su segmenti del tetto con caratteristiche specifiche, puoi
filtrare in base a segmentIndex. Ad esempio, se vuoi posizionare i pannelli sulla parte del tetto esposta a sud, identifica i segmenti del tetto con valori azimuthDegrees compresi tra 90 e 270, quindi utilizza il valore segmentIndex corrispondente per filtrare l'elenco completo dei pannelli per questi segmenti del tetto.
Richiedi i dati degli array rilevati
L'API Solar rileva gli impianti solari esistenti sui tetti utilizzando le immagini satellitari. Per informazioni sulle regioni supportate, consulta la mappa di copertura.
Per richiedere i dati degli array rilevati, imposta il parametro additionalInsights su DETECTED_ARRAYS nel corpo della richiesta:
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"
Il corpo della risposta include le seguenti informazioni sugli array rilevati:
- Indica se sono stati rilevati impianti solari sul tetto dell'edificio
(
detectionStatus). - La data dell'ultima acquisizione di immagini satellitari utilizzata per i rilevamenti (
latestCaptureDate), se disponibile. - Un elenco degli impianti solari rilevati (
arrays). Ogni impianto rappresenta una singola area contigua di pannelli solari e include:polygonGeojson: una rappresentazione GeoJSON dell'area del tetto in cui sono stati rilevati i pannelli solari. I dati GeoJSON sono in formato RFC 7946 e rappresentano unPolygonper una singola area contigua. Un poligono che contiene fori è rappresentato da diversi loop.
L'elenco arrays viene compilato solo quando detectionStatus è
DETECTION_STATUS_ARRAYS_DETECTED.
L'esempio seguente mostra una risposta per un edificio con array rilevati (la risposta è troncata):
{ "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 } } }
Prova
Explorer API ti consente di effettuare richieste di esempio per acquisire familiarità con l'API e le relative opzioni.
Seleziona l'icona dell'API api sul lato destro della pagina.
Se vuoi, modifica i parametri della richiesta.
Seleziona il pulsante Esegui. Nella finestra di dialogo, scegli l'account che vuoi utilizzare per effettuare la richiesta.
Nel riquadro Explorer API, seleziona l'icona Schermo intero fullscreen per espandere la finestra di Explorer API.