نقطه پایانی buildingInsights اطلاعات آماری درباره مکان، ابعاد، و پتانسیل خورشیدی ساختمان ارائه می‌دهد. به‌طور خاص، می‌توانید اطلاعاتی درباره موارد زیر دریافت کنید:
- پتانسیل خورشیدی، ازجمله اندازه پانل خورشیدی، مقدار سالانه تابش آفتاب، عوامل تعدیل کربن، و غیره
- موقعیت، جهت، و تولید انرژی صفحه خورشیدی
- قبض انرژی ماهانه تخمینی برای چیدمان خورشیدی بهینه و هزینه‌ها و مزایای مرتبط
برای کسب اطلاعات بیشتر درباره نحوه تعریف پتانسیل خورشیدی و آفتابی بودن توسط Solar API، به مفاهیم Solar API مراجعه کنید.
APIs Explorer به شما امکان می‌دهد درخواست‌های زنده ایجاد کنید تا بتوانید با API و گزینه‌های API آشنا شوید:
درباره درخواست‌های اطلاعات آماری ساختمان
برای درخواست اطلاعات آماری ساختمان، درخواست HTTP GET را به این نشانی ارسال کنید:
https://solar.googleapis.com/v1/buildingInsights:findClosest?key=YOUR_API_KEY
پارامترهای نشانی وب درخواستتان را که مختصات عرض جغرافیایی و طول جغرافیایی مکان و حداقل سطح کیفیت لازم مجاز در نتایج را مشخص می‌کند اضافه کنید.
درباره پاسخ‌های اطلاعات آماری ساختمان
Solar API اطلاعات مربوط به مکان، ابعاد، و پتانسیل خورشیدی ساختمان را در بدنه پاسخ برمی‌گرداند.
کیفیت تصاویر
در برخی موارد، کیفیت تصاویر درخواستی در مکانی خاص ممکن است با کیفیت تصاویر دردسترس متفاوت باشد. در چنین سناریوهایی، رفتار زیر موردانتظار است:
| سناریو | رفتار پاسخ |
|---|---|
مکانی تصاویری ندارد که با requiredQuality مطابقت داشته باشد. |
Solar API خطای NOT_FOUND را با رمز وضعیت ۴۰۴ برمی‌گرداند. |
درخواستی requiredQuality خاصی را مشخص می‌کند، اما فقط داده‌های سطح کیفیت تصویر بالاتر دردسترس است. |
Solar API بالاترین کیفیت داده‌های موجود در مکان را برمی‌گرداند. |
نمونه درخواست اطلاعات آماری ساختمان
مثال زیر اطلاعات آماری ساختمان را برای مکانی با مختصات عرض جغرافیایی = ۳۷٫۴۴۵۰ و طول جغرافیایی = -۱۲۲٫۱۳۹۰ درخواست می‌کند:
کلید میانای API
برای درخواست بااستفاده از کلید میانای برنامه‌سازی کاربردی، کلید میانای برنامه‌سازی کاربردی خود را به‌عنوان پارامتر ورودی اضافه کنید:
curl -X GET "https://solar.googleapis.com/v1/buildingInsights:findClosest?location.latitude=37.4450 &location.longitude=-122.1390 &requiredQuality=HIGH &key=YOUR_API_KEY"
همچنین می‌توانید با جای‌گذاری نشانی وب در درخواست cURL در نوار نشانی وب مرورگرتان، درخواست‌های HTTP ایجاد کنید.
کد OAuth
توجه: این قالب فقط برای محیط آزمایشی است. برای اطلاعات بیشتر، به استفاده از OAuth مراجعه کنید.
برای درخواست بااستفاده از OAuth، نام پروژه صورت‌حساب و کد 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
برای درخواست بااستفاده از TypeScript، کلید API یا کد OAuth خود را در درخواست لحاظ کنید. مثال زیر از کلید میانای برنامه‌سازی کاربردی استفاده می‌کند:
/** * 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; }, ); }
تعریف انواع داده
از انواع داده‌های زیر پشتیبانی می‌شود:
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; }; }
این درخواست یک پاسخ 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 } }
بخش‌های سقف را برای قرار دادن پانل انتخاب کنید
در برخی موارد، می‌توانید بخش‌های خاصی از سقف را برای قرار دادن صفحه خورشیدی انتخاب کنید. roofSegmentStats اطلاعاتی درباره اندازه،
جهت، و چندک‌های آفتاب‌گیر بودن بخش مشخصی از سقف ارائه می‌دهد:
"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 }, /.../ ],
براساس این ویژگی‌ها، می‌توانید فقط پانل‌های قرارگرفته روی بخش خاصی از سقف را انتخاب کنید. هر پانلی که ازطریق نقطه پایانی buildingInsights برگردانده می‌شود، شامل مقدار segmentIndex است که نشان می‌دهد پانل روی کدام بخش سقف قرار گرفته است:
{ "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 } ] },
برای انتخاب پانل‌ها در بخش‌های سقف با ویژگی‌های خاص، می‌توانید
براساس segmentIndex فیلتر کنید. برای مثال، اگر می‌خواهید پانل‌ها را در بخش جنوبی بام قرار دهید، مشخص کنید کدام بخش‌های بام دارای مقادیر azimuthDegrees بین ۹۰ و ۲۷۰ هستند، سپس از segmentIndex مربوطه برای فیلتر کردن فهرست کامل پانل‌ها برای آن بخش‌های بام استفاده کنید.
درخواست داده‌های آرایه‌های شناسایی‌شده
Solar API تأسیسات خورشیدی پشت‌بامی موجود را بااستفاده از تصاویر ماهواره‌ای شناسایی می‌کند. برای اطلاعات درباره مناطق پشتیبانی‌شده، نقشه پوشش را ببینید.
برای درخواست داده‌های آرایه‌های شناسایی‌شده، پارامتر additionalInsights را در بدنه درخواستتان روی DETECTED_ARRAYS تنظیم کنید:
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"
بدنه پاسخ شامل اطلاعات آرایه‌های شناسایی‌شده زیر است:
- اینکه آیا تأسیسات خورشیدی روی سقف ساختمان شناسایی شده است یا نه
(
detectionStatus). - تاریخ جدیدترین تصویر ماهواره‌ای ضبط‌شده که برای تشخیص‌ها استفاده شده است
(
latestCaptureDate)، درصورت دردسترس بودن. - فهرستی از آرایه‌های خورشیدی شناسایی‌شده (
arrays). هر آرایه نشان‌دهنده یک ناحیه پیوسته از صفحه‌های خورشیدی است و شامل موارد زیر می‌شود:polygonGeojson: نمایش GeoJSON از سطح پشت‌بام که پانل‌های خورشیدی در آن شناسایی شده است. داده‌های GeoJSON در قالب RFC 7946 است وPolygonرا برای یک منطقه پیوسته نشان می‌دهد. چندضلعی‌ای که حاوی حفره است با چند حلقه نشان داده می‌شود.
فهرست arrays فقط زمانی درج می‌شود که detectionStatus
DETECTION_STATUS_ARRAYS_DETECTED باشد.
مثال زیر پاسخی را برای ساختمانی با آرایه‌های شناسایی‌شده نشان می‌دهد (پاسخ کوتاه شده است):
{ "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 } } }
امتحان کنید!
با API Explorer می‌توانید درخواست‌های نمونه ایجاد کنید تا با API و گزینه‌های API آشنا شوید.
نماد API api را در سمت چپ صفحه انتخاب کنید.
درصورت تمایل، پارامترهای درخواست را ویرایش کنید.
دکمه اجرا را انتخاب کنید. در کادر گفتگو، حسابی را که می‌خواهید برای ارسال درخواست استفاده شود انتخاب کنید.
در پانل «کاوشگر API»، نماد تمام‌صفحه تمام‌صفحه را انتخاب کنید تا پنجره «کاوشگر API» ازهم باز شود.