Le point de terminaison buildingInsights fournit des insights sur l'emplacement, les dimensions et le potentiel solaire d'un bâtiment. Vous pouvez notamment obtenir des informations sur les éléments suivants :
- Le potentiel solaire, y compris la taille des panneaux solaires, la quantité annuelle d'ensoleillement, les facteurs de compensation carbone, etc.
- La position, l'orientation et la production d'énergie des panneaux solaires
- L'estimation de la facture d'énergie mensuelle de la configuration solaire optimale, ainsi que les coûts et avantages associés
Pour en savoir plus sur la façon dont l'API Solar définit le potentiel solaire et l'ensoleillement, consultez Concepts de l'API Solar.
L'APIs Explorer vous permet d'effectuer des requêtes en direct pour vous familiariser avec l'API et ses options :
À propos des requêtes d'insights sur les bâtiments
Pour demander des insights sur les bâtiments, envoyez une requête HTTP GET à l'adresse suivante :
https://solar.googleapis.com/v1/buildingInsights:findClosest?key=YOUR_API_KEY
Incluez les paramètres de l'URL de votre requête qui spécifient les coordonnées de latitude et de longitude de l'établissement, ainsi que le niveau de qualité minimal requis autorisé dans les résultats.
À propos des réponses d'insights sur les bâtiments
L'API Solar renvoie des informations sur l'emplacement, les dimensions et le potentiel solaire d'un bâtiment dans le corps de la réponse.
Qualité des images
Dans certains cas, la qualité des images demandée dans un établissement spécifique peut différer de la qualité des images disponibles. Dans ce cas, le comportement suivant est attendu :
| Scénario | Comportement de la réponse |
|---|---|
Un établissement ne dispose pas d'images répondant à requiredQuality. |
L'API Solar renvoie une erreur NOT_FOUND avec un code d'état 404. |
Une requête spécifie une certaine requiredQuality, mais seules des données d'un niveau de qualité d'image supérieur sont disponibles. |
L'API Solar renvoie les données de la plus haute qualité disponibles dans l'établissement. |
Exemple de requête d'insights sur les bâtiments
L'exemple suivant demande des informations sur les insights sur les bâtiments pour l'établissement situé aux coordonnées latitude = 37.4450 et longitude = -122.1390 :
Clé API
Pour envoyer une requête à l'URL de la réponse, ajoutez votre clé API à l'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"
Vous pouvez également effectuer des requêtes HTTP en collant l'URL de la requête cURL dans la barre d'URL de votre navigateur. Transmettre la clé API vous offre de meilleures capacités d'utilisation et d'analyse, ainsi qu'un meilleur contrôle d'accès aux données de réponse.
Jeton OAuth
Remarque : Ce format est destiné à un environnement de test uniquement. Pour en savoir plus, consultez Utiliser OAuth.
Pour envoyer une requête à l'URL de la réponse, transmettez le nom de votre projet de facturation et votre jeton 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
Pour envoyer une requête à l'URL de la réponse, incluez votre clé API ou votre jeton OAuth dans la requête. L'exemple suivant utilise une clé 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; }, ); }
Définitions des types de données
Les types de données suivants sont compatibles :
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; }; }
Cette requête génère une réponse JSON au format suivant :
{ "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 } }
Sélectionner des segments de toit pour l'installation de panneaux
Dans certains cas, vous pouvez choisir de sélectionner des segments de toit spécifiques pour l'installation de panneaux solaires. roofSegmentStats fournit des informations sur la taille, l'orientation et les quantiles d'ensoleillement d'un segment de toit donné :
"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 }, /.../ ],
En fonction de ces caractéristiques, vous pouvez choisir de ne sélectionner que les panneaux placés sur un segment de toit spécifique. Chaque panneau renvoyé via le point de terminaison buildingInsights inclut une valeur segmentIndex indiquant le segment de toit sur lequel le panneau est placé :
{ "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 } ] },
Pour sélectionner des panneaux sur des segments de toit présentant des caractéristiques spécifiques, vous pouvez filtrer par segmentIndex. Par exemple, si vous souhaitez placer des panneaux sur la partie du toit orientée au sud, identifiez les segments de toit dont les valeurs azimuthDegrees sont comprises entre 90 et 270, puis utilisez le segmentIndex correspondant pour filtrer la liste complète des panneaux pour ces segments de toit.
Essayer
L'APIs Explorer vous permet d'effectuer des requêtes d'exemple pour vous familiariser avec l'API et ses options.
Sélectionnez l'icône d'API api à droite de la page.
Vous pouvez également modifier les paramètres de la requête.
Sélectionnez le bouton Exécuter. Dans la boîte de dialogue, choisissez le compte que vous souhaitez utiliser pour effectuer la requête.
Dans le panneau APIs Explorer, sélectionnez l'icône plein écran fullscreen pour agrandir la fenêtre APIs Explorer.