Membuat permintaan insight build

Developer Wilayah Ekonomi Eropa (EEA)

Endpoint buildingInsights memberikan insight tentang lokasi, dimensi, dan potensi tenaga surya suatu bangunan. Secara khusus, Anda dapat memperoleh informasi tentang:

  • Potensi tenaga surya, termasuk ukuran panel surya, jumlah sinar matahari tahunan, faktor kompensasi karbon, dan lainnya
  • Posisi, orientasi, dan produksi energi panel surya
  • Estimasi tagihan energi bulanan dari tata letak panel surya yang optimal serta biaya dan manfaat terkait

Untuk mempelajari lebih lanjut cara Solar API menentukan potensi tenaga surya dan sinar matahari, lihat Konsep Solar API.

APIs Explorer memungkinkan Anda membuat permintaan langsung sehingga Anda dapat memahami API dan opsi API:

Tentang permintaan insight bangunan

Untuk meminta insight bangunan, kirim permintaan GET HTTP ke:

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

Sertakan parameter URL permintaan Anda yang menentukan koordinat lintang dan bujur lokasi serta tingkat kualitas minimum yang diperlukan yang diizinkan dalam hasil.

Tentang membuat respons insight

Solar API menampilkan informasi tentang lokasi, dimensi, dan potensi tenaga surya bangunan dalam isi respons.

Kualitas gambar

Dalam beberapa kasus, kualitas gambar yang diminta di lokasi tertentu mungkin berbeda dengan kualitas gambar yang tersedia. Dalam skenario tersebut, perilaku berikut akan terjadi:

Skenario Perilaku respons
Lokasi tidak memiliki gambar yang memenuhi
requiredQuality.		 Solar API menampilkan error NOT_FOUND dengan kode status 404.
Permintaan menentukan requiredQuality tertentu, tetapi hanya data dengan tingkat kualitas gambar yang lebih tinggi yang tersedia. Solar API menampilkan data berkualitas tertinggi yang tersedia di lokasi.

Contoh permintaan Building Insights

Contoh berikut meminta informasi analisis bangunan untuk lokasi di koordinat lintang = 37.4450 dan bujur = -122.1390:

Kunci API

Untuk membuat permintaan menggunakan kunci API, sertakan kunci API Anda sebagai parameter input:

curl -X GET "https://solar.googleapis.com/v1/buildingInsights:findClosest?location.latitude=37.4450&location.longitude=-122.1390&requiredQuality=HIGH&key=YOUR_API_KEY"

Anda juga dapat membuat permintaan HTTP dengan menempelkan URL dalam permintaan cURL ke kolom URL browser.

Token OAuth

Catatan: Format ini hanya untuk lingkungan pengujian. Untuk mengetahui informasi selengkapnya, lihat Menggunakan OAuth.

Untuk membuat permintaan menggunakan OAuth, teruskan nama project penagihan dan token OAuth Anda:

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

Untuk membuat permintaan menggunakan TypeScript, sertakan kunci API atau token OAuth Anda dalam permintaan. Contoh berikut menggunakan kunci 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;
    },
  );
}

Definisi jenis data

Jenis data berikut didukung:

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;
  };
}

Permintaan tersebut menghasilkan respons JSON dalam bentuk:

{
  "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
  }
}

Memilih segmen atap untuk penempatan panel

Dalam beberapa kasus, Anda dapat memilih untuk memilih segmen atap tertentu untuk penempatan panel surya. roofSegmentStats memberikan informasi tentang ukuran, orientasi, dan kuantil paparan sinar matahari dari segmen atap tertentu:

"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
      },
      /.../
    ],

Berdasarkan karakteristik ini, Anda dapat memilih untuk hanya memilih panel yang ditempatkan di segmen atap tertentu. Setiap panel yang ditampilkan melalui endpoint buildingInsights menyertakan nilai segmentIndex yang menunjukkan segmen atap tempat panel ditempatkan:

{
        "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
          }
        ]
      },

Untuk memilih panel di segmen atap dengan karakteristik tertentu, Anda dapat memfilter menurut segmentIndex. Misalnya, jika Anda ingin menempatkan panel di bagian atap yang menghadap ke selatan, identifikasi segmen atap yang memiliki nilai azimuthDegrees antara 90 dan 270, lalu gunakan segmentIndex yang sesuai untuk memfilter daftar panel lengkap untuk segmen atap tersebut.

Meminta data array yang terdeteksi

Solar API mendeteksi instalasi panel surya atap yang ada menggunakan citra satelit. Untuk mengetahui informasi tentang wilayah yang didukung, lihat peta cakupan.

Untuk meminta data array yang terdeteksi, tetapkan parameter additionalInsights ke DETECTED_ARRAYS dalam isi permintaan Anda:

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"

Isi respons mencakup informasi array yang terdeteksi berikut:

  • Apakah instalasi panel surya terdeteksi di atap bangunan (detectionStatus).
  • Tanggal pengambilan citra satelit terbaru yang digunakan untuk deteksi (latestCaptureDate), jika tersedia.
  • Daftar sistem panel surya yang terdeteksi (arrays). Setiap sistem mewakili satu area panel surya yang berdekatan dan mencakup:
    • polygonGeojson: Representasi GeoJSON dari area atap tempat panel surya terdeteksi. Data GeoJSON dalam format RFC 7946 dan mewakili Polygon untuk satu area yang berdekatan. Poligon yang berisi lubang diwakili oleh beberapa loop.

Daftar arrays hanya diisi jika detectionStatus adalah DETECTION_STATUS_ARRAYS_DETECTED.

Contoh berikut menunjukkan respons untuk bangunan dengan panel yang terdeteksi (respons dipotong):

{
  "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
    }
  }
}

Cobalah!

APIs Explorer memungkinkan Anda membuat contoh permintaan sehingga Anda dapat memahami API dan opsi API.

  1. Pilih ikon API api di sisi kanan halaman.

  2. Edit parameter permintaan jika perlu.

  3. Pilih tombol Execute. Dalam dialog, pilih akun yang ingin Anda gunakan untuk membuat permintaan.

  4. Di panel APIs Explorer, pilih ikon layar penuh fullscreen untuk meluaskan jendela APIs Explorer.

Berikutnya
Telusuri gedung