שליחת בקשה לקבלת תובנות לגבי בניין

מפתחים באזור הכלכלי האירופי (EEA)

נקודת הקצה buildingInsights מספקת תובנות לגבי המיקום, הממדים והפוטנציאל הסולארי של מבנה. בפרט, אתם יכולים לקבל מידע על:

  • פוטנציאל ליצירת אנרגיה סולארית, כולל גודל הלוח הסולארי, כמות שעות השמש השנתית, גורמים לקיזוז פחמן ועוד
  • המיקום, הכיוון והפקת האנרגיה של הלוח הסולארי
  • חשבון החשמל החודשי המשוער של פריסת לוחות סולאריים אופטימלית, והעלויות והיתרונות שקשורים אליה

במאמר מושגים ב-Solar API מוסבר איך Solar API מגדיר את פוטנציאל האנרגיה הסולארית ואת רמת החשיפה לשמש.

בעזרת APIs Explorer אתם יכולים לשלוח בקשות בזמן אמת כדי להכיר את ה-API ואת האפשרויות שלו:

מידע על בקשות לתובנות לגבי מבנים

כדי לבקש תובנות לגבי מבנים, שולחים בקשת HTTP GET אל:

https://solar.googleapis.com/v1/buildingInsights:findClosest?key=YOUR_API_KEY

כוללים את הפרמטרים של כתובת ה-URL של הבקשה שמציינים את קואורדינטות קו הרוחב וקו האורך של המיקום, ואת רמת האיכות המינימלית הנדרשת שמותרת בתוצאות.

מידע על התשובות של התובנות לגבי מבנים

‫Solar API מחזיר מידע על המיקום, הממדים והפוטנציאל הסולארי של מבנה בגוף התגובה.

איכות התמונות

במקרים מסוימים, איכות התמונות שביקשתם במיקום ספציפי עשויה להיות שונה מאיכות התמונות שזמינה. במקרים כאלה, ההתנהגות הצפויה היא:

תרחיש התנהגות התגובה
במיקום אין תמונות שעומדות בדרישות של
requiredQuality.		 ‫Solar API מחזיר שגיאת NOT_FOUND עם קוד סטטוס 404.
בבקשה צוינה רמת requiredQuality מסוימת, אבל זמינים רק נתונים ברמת איכות גבוהה יותר של התמונות. ‫Solar API מחזיר את הנתונים באיכות הכי גבוהה שזמינה במיקום.

דוגמה לבקשה של תובנות לגבי מבנים

בדוגמה הבאה נשלחת בקשה לקבלת מידע על תובנות לגבי מבנים במיקום עם הקואורדינטות קו רוחב = 37.4450 וקו אורך = ‎-122.1390:

מפתח API

כדי לשלוח בקשה באמצעות מפתח 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"

אפשר גם לשלוח בקשות HTTP על ידי הדבקת כתובת ה-URL בבקשת ה-cURL בסרגל הכתובות של הדפדפן.

טוקן 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. בדוגמה הבאה נעשה שימוש במפתח 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 בין 90 ל-270, ואז משתמשים בערך 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
    }
  }
}

רוצה לנסות?

ב-APIs Explorer אתם יכולים לשלוח בקשות לדוגמה כדי להכיר את ה-API ואת האפשרויות שהוא מציע.

  1. לוחצים על סמל ה-API‏ api בצד שמאל של הדף.

  2. אפשר לערוך את הפרמטרים של הבקשה.

  3. לוחצים על הכפתור Execute. בתיבת הדו-שיח, בוחרים את החשבון שבו רוצים להשתמש כדי לשלוח את הבקשה.

  4. בחלונית APIs Explorer, לוחצים על סמל המסך המלא fullscreen כדי להרחיב את החלון של APIs Explorer.

הבא
חיפוש מבנים