توفر نقطة نهاية buildingInsights إحصاءات حول الموقع الجغرافي والأبعاد وإمكانات توليد الطاقة الشمسية لمبنى. وعلى وجه الخصوص، يمكنك الحصول على معلومات حول:
- إمكانات توليد الطاقة الشمسية، بما في ذلك حجم الألواح الشمسية والكمية السنوية لأشعة الشمس وعوامل تعويض الكربون وغير ذلك
- موضع الألواح الشمسية واتجاهها وإنتاجها
- فاتورة الطاقة الشهرية المقدّرة للتخطيط الأمثل لتوليد الطاقة الشمسية والتكاليف والمزايا المرتبطة بها
لمعرفة المزيد حول كيفية تحديد Solar API لإمكانات توليد الطاقة الشمسية ودرجة شدة الضوء، يمكنك الاطّلاع على Solar API Concepts.
يتيح لك "مستكشف واجهة برمجة التطبيقات" إجراء طلبات مباشرة لتتمكن من التعرّف على خيارات واجهة برمجة التطبيقات وواجهة برمجة التطبيقات:
لمحة عن إنشاء طلبات الإحصاءات
لطلب الحصول على إحصاءات، يمكنك إرسال طلب HTTP GET إلى:
https://solar.googleapis.com/v1/buildingInsights:findClosest?key=YOUR_API_KEY
أدرِج معلَمات عنوان URL للطلب التي تحدّد إحداثيات خطي الطول والعرض للموقع الجغرافي والحد الأدنى لمستوى الجودة المطلوب المسموح به في النتائج.
مثال على طلب إحصاءات المبنى
يطلب المثال التالي إنشاء معلومات رؤى للموقع على إحداثيات خط العرض = 37.4450 وخط الطول = -122.1390:
مفتاح واجهة برمجة التطبيقات
لتقديم طلب إلى عنوان URL في الردّ، عليك إلحاق مفتاح واجهة برمجة التطبيقات بعنوان 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"
يمكنك أيضًا إجراء طلبات HTTP من خلال لصق عنوان URL في طلب cURL في شريط عناوين URL في المتصفّح. ويتيح لك تمرير مفتاح واجهة برمجة التطبيقات إمكانات أفضل لاستخدام الإحصاءات والتحكُّم بشكل أفضل في الوصول إلى بيانات الردود.
رمز 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"
TypeScript
لتقديم طلب إلى عنوان URL في الردّ، عليك تضمين مفتاح واجهة برمجة التطبيقات أو رمز 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),
};
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' | 'LOW';
}
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' | 'LOW';
}
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
}
}
تجربة
يتيح لك "مستكشف واجهة برمجة التطبيقات" تقديم طلبات نموذجية حتى تتمكّن من التعرّف على خيارات واجهة برمجة التطبيقات وواجهة برمجة التطبيقات
انقر على رمز واجهة برمجة التطبيقات
على الجانب الأيسر من الصفحةيمكنك تعديل معلمات الطلب اختياريًا.
انقر على الزر تنفيذ. في مربع الحوار المنبثق، اختر الحساب الذي تريد استخدامه لتقديم الطلب.
في لوحة "مستكشف واجهة برمجة التطبيقات"، انقر على رمز التوسيع،
، لتوسيع نافذة "مستكشف واجهة برمجة التطبيقات".