نقطه پایانی buildingInsights بینشهایی در مورد مکان، ابعاد و پتانسیل خورشیدی یک ساختمان ارائه میدهد. به طور خاص، میتوانید اطلاعاتی در مورد موارد زیر دریافت کنید:
- پتانسیل خورشیدی، شامل اندازه پنل خورشیدی، میزان تابش سالانه آفتاب، ضرایب جبران کربن و موارد دیگر
- موقعیت، جهتگیری و تولید انرژی پنل خورشیدی
- هزینه انرژی ماهانه تخمینی از طرح بهینه خورشیدی و هزینهها و مزایای مرتبط
برای کسب اطلاعات بیشتر در مورد چگونگی تعریف پتانسیل خورشیدی و میزان آفتابگیری توسط Solar API، به مفاهیم Solar API مراجعه کنید.
مرورگر APIها به شما امکان میدهد درخواستهای زنده ارسال کنید تا بتوانید با API و گزینههای API آشنا شوید:
درباره درخواستهای ایجاد بینش
برای درخواست ایجاد بینش، یک درخواست HTTP GET به آدرس زیر ارسال کنید:
https://solar.googleapis.com/v1/buildingInsights:findClosest?key=YOUR_API_KEY
پارامترهای URL درخواست خود را که مختصات عرض و طول جغرافیایی مکان و حداقل سطح کیفیت مورد نیاز مجاز در نتایج را مشخص میکنند، وارد کنید.
درباره ایجاد بینش، پاسخها
رابط برنامهنویسی کاربردی Solar اطلاعاتی در مورد مکان، ابعاد و پتانسیل خورشیدی یک ساختمان را در بدنه پاسخ برمیگرداند.
کیفیت تصویر
در برخی موارد، کیفیت تصویر درخواستی در یک مکان خاص ممکن است با کیفیت تصویر موجود متفاوت باشد. در چنین سناریوهایی، رفتار زیر مورد انتظار است:
| سناریو | رفتار پاسخ |
|---|---|
یک مکان تصویری مطابق با معیارهای زیر ندارد:requiredQuality | API خورشیدی خطای NOT_FOUND را با کد وضعیت ۴۰۴ برمیگرداند. |
یک درخواست، یک requiredQuality خاص را مشخص میکند، اما فقط دادههایی با سطح کیفیت تصویر بالاتر در دسترس هستند. | API خورشیدی، باکیفیتترین دادههای موجود در محل را برمیگرداند. |
مثال درخواست بینشهای ساختمانی
مثال زیر اطلاعات بینش ساختمان را برای موقعیت مکانی در مختصات عرض جغرافیایی = 37.4450 و طول جغرافیایی = -122.1390 درخواست میکند:
کلید API
برای ارسال درخواست به URL در پاسخ، کلید API خود را به 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"
همچنین میتوانید با قرار دادن URL موجود در درخواست cURL در نوار آدرس مرورگر خود، درخواستهای HTTP ایجاد کنید. ارسال کلید API، قابلیتهای استفاده و تجزیه و تحلیل بهتر و کنترل دسترسی بهتری به دادههای پاسخ را برای شما فراهم میکند.
توکن OAuth
توجه: این قالب فقط برای محیط آزمایشی است. برای اطلاعات بیشتر، به بخش «استفاده از OAuth» مراجعه کنید.
برای ارسال درخواست به URL در پاسخ، نام پروژه صورتحساب و توکن 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"
تایپ اسکریپت
برای ارسال درخواست به URL در پاسخ، کلید API یا توکن OAuth خود را در درخواست قرار دهید. مثال زیر از کلید 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; }, ); }
تعاریف نوع داده
انواع داده زیر پشتیبانی میشوند:
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 مربوطه برای فیلتر کردن لیست کامل پنل برای آن بخشهای سقف استفاده کنید.
امتحانش کن!
مرورگر APIها به شما امکان میدهد درخواستهای نمونه ایجاد کنید تا با API و گزینههای API آشنا شوید.
آیکون API یعنی api را در سمت راست صفحه انتخاب کنید.
در صورت تمایل، پارامترهای درخواست را ویرایش کنید.
دکمه اجرا را انتخاب کنید. در کادر محاورهای، حسابی را که میخواهید برای ارسال درخواست استفاده کنید، انتخاب کنید.
در پنل APIs Explorer، آیکون تمام صفحه را در حالت تمام صفحه انتخاب کنید تا پنجره APIs Explorer باز شود.