נקודת הקצה buildingInsights מספקת תובנות לגבי המיקום, המידות והפוטנציאל הסולארי של מבנה. באופן ספציפי, אתם יכולים לקבל מידע על:
- פוטנציאל סולארי, כולל גודל הפאנלים הסולאריים, כמות השמש השנתית, גורמים של קיזוז פחמן ועוד
- המיקום, הכיוון והפקת האנרגיה של הפאנל הסולארי
- חשבון אנרגיה חודשי משוער של פריסה סולארית אופטימלית והעלויות וההטבות הנלוות
למידע נוסף על האופן שבו Solar API מגדיר פוטנציאל סולארי ואור שמש, קראו את המאמר מושגי API של Solar.
API Explorer מאפשר לשלוח בקשות בזמן אמת כדי להכיר את ה-API ואת אפשרויות ה-API:
מידע על בקשות לקבלת תובנות
כדי לבקש תובנות לגבי בניינים, יש לשלוח בקשת HTTP GET אל:
https://solar.googleapis.com/v1/buildingInsights:findClosest?key=YOUR_API_KEY
עליכם לכלול פרמטרים של כתובת ה-URL של הבקשה שמציינים את הקואורדינטות של קווי האורך והרוחב של המיקום, ואת רמת האיכות המינימלית הנדרשת בתוצאות.
דוגמה לבקשת תובנות בניין
בדוגמה הבאה מוצגת בקשה לקבלת מידע על תובנות לגבי המיקום בקואורדינטות של קו רוחב = 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"
אפשר גם לשלוח בקשות HTTP על ידי הדבקת כתובת ה-URL שבבקשת cURL אל סרגל הכתובות של הדפדפן. כשמעבירים את מפתח ה-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"
TypeScript
כדי לשלוח בקשה לכתובת ה-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),
};
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
}
}
רוצה לנסות?
תוכלו לשלוח בקשות לדוגמה כדי להכיר את ה-API ואת האפשרויות של API.
לוחצים על סמל ה-API
בצד ימין של הדף.אפשר לערוך את הפרמטרים של הבקשה.
לוחצים על הלחצן ביצוע. בתיבת הדו-שיח הקופצת, בוחרים את החשבון שבו רוצים להשתמש כדי לשלוח את הבקשה.
בחלונית של API Explorer לוחצים על סמל ההרחבה
כדי להרחיב את החלון של API Explorer.