تقديم طلب إحصاءات المباني

مطوّرو البرامج في المنطقة الاقتصادية الأوروبية (EEA)

توفر نقطة النهاية buildingInsights إحصاءات حول موقع مبنى وأبعاده وإمكانية توليد الطاقة الشمسية. على وجه الخصوص، يمكنك الحصول على معلومات حول:

  • إمكانية توليد الطاقة الشمسية، بما في ذلك حجم الألواح الشمسية والكمية السنوية لأشعة الشمس وعوامل تعويض انبعاثات الكربون والمزيد
  • موضع الألواح الشمسية واتجاهها وإنتاجها للطاقة
  • فاتورة الطاقة الشهرية المقدَّرة للتصميم الأمثل للألواح الشمسية والتكاليف والمزايا المرتبطة بها

لمزيد من المعلومات حول طريقة تحديد Solar API لإمكانية توليد الطاقة الشمسية وكمية أشعة الشمس، يُرجى الاطّلاع على مفاهيم Solar API.

يتيح لك مستكشف واجهات برمجة التطبيقات إرسال طلبات بيانات مباشرة لتتعرّف على واجهة برمجة التطبيقات وخياراتها:

لمحة عن طلبات الإحصاءات حول المباني

لطلب إحصاءات حول المباني، أرسِل طلب استرداد بيانات باستخدام 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:

مفتاح واجهة برمجة التطبيقات

لإرسال طلب باستخدام مفتاح واجهة برمجة التطبيقات، أدرِج مفتاح واجهة برمجة التطبيقات كمعلَمة إدخال:

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 في شريط عنوان URL في متصفّحك.

رمز 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، أدرِج إما مفتاح واجهة برمجة التطبيقات أو رمز 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 بين 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) وتاريخ التقاط صور المصفوفات التي تم رصدها، إذا كان متاحًا:

{
  "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",
    "latestCaptureDate": {
      "year": 2025,
      "month": 5,
      "day": 14
    }
  }
}

جرِّبه الآن

يتيح لك مستكشف واجهات برمجة التطبيقات إرسال طلبات بيانات نموذجية لتتعرّف على واجهة برمجة التطبيقات وخياراتها.

  1. انقر على رمز واجهة برمجة التطبيقات api على الجانب الأيسر من الصفحة.

  2. يمكنك تعديل مَعلمات الطلب اختياريًا.

  3. انقر على الزر تنفيذ. في مربّع الحوار، اختَر الحساب الذي تريد استخدامه لإرسال الطلب.

  4. في لوحة مستكشف واجهات برمجة التطبيقات، انقر على رمز ملء الشاشة fullscreen لتوسيع نافذة مستكشف واجهات برمجة التطبيقات.

التالي
البحث عن المباني