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

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

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

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

لمزيد من المعلومات حول كيفية تحديد Solar API للطاقة الشمسية المحتملة ومستوى سطوع الشمس، يُرجى الاطّلاع على مفاهيم Solar 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:

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

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

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.

لإرسال طلب باستخدام 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)
  • تاريخ التقاط أحدث صور القمر الصناعي المستخدَمة في عمليات الرصد (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
    }
  }
}

جرِّبها الآن.

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

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

  2. يمكنك تعديل مَعلمات الطلب إذا أردت.

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

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

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