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

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

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

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

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

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

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

لطلب إحصاءات المبنى، أرسِل طلب استرداد بيانات باستخدام GET HTTP إلى:

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:

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

لإرسال طلب إلى عنوان 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 في شريط عناوين المتصفح. يمنحك تمرير مفتاح واجهة برمجة التطبيقات إمكانات أفضل للاستخدام والإحصاءات، فضلاً عن تحكّم أفضل في الوصول إلى بيانات الردود.

الرمز المميز لبروتوكول 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),
    // 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;
    },
  );
}
solar.ts

تعريفات أنواع البيانات

تتوفّر أنواع البيانات التالية:

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;
  };
}
solar.ts

يؤدي هذا الطلب إلى إنشاء ردّ بتنسيق 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 المقابل لفلترة قائمة الألواح الكاملة لأجزاء السطح هذه.

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

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

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

  2. عدِّل مَعلمات الطلب اختياريًا.

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

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

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