Method: buildingInsights.findClosest

找出與查詢點最近的建築物。如果在查詢點附近 50 公尺內沒有任何建築物，系統會傳回代碼為 NOT_FOUND 的錯誤。

HTTP 要求

GET https://solar.googleapis.com/v1/buildingInsights:findClosest

這個網址使用 gRPC 轉碼語法。

查詢參數

參數
location

object (LatLng)

必要欄位。API 用來尋找最近已知建築物的經緯度。
requiredQuality

enum (ImageryQuality)

選用設定。結果中允許的最低品質等級。系統不會傳回品質低於此值的結果。如未指定，則系統會只限制高品質。

要求主體

要求主體必須為空白。

回應主體

Solar.FindClosestBuildingInsights 的回應訊息。建築物的位置、尺寸和太陽能發電潛力相關資訊。

如果成功，回應主體會含有以下結構的資料：

JSON 表示法 
{
  "name": string,
  "center": {
    object (LatLng)
  },
  "boundingBox": {
    object (LatLngBox)
  },
  "imageryDate": {
    object (Date)
  },
  "imageryProcessedDate": {
    object (Date)
  },
  "postalCode": string,
  "administrativeArea": string,
  "statisticalArea": string,
  "regionCode": string,
  "solarPotential": {
    object (SolarPotential)
  },
  "imageryQuality": enum (ImageryQuality)
}
欄位
name

string

大樓的資源名稱，格式為 buildings/{place_id}。
center

object (LatLng)

位於建築物中心附近的點。
boundingBox

object (LatLngBox)

建築物的定界框。
imageryDate

object (Date)

取得底層圖像的日期。這是大約值。
imageryProcessedDate

object (Date)

這張圖像的處理作業完成時間。
postalCode

string

郵遞區號 (例如：郵遞區號) 的郵遞區號。
administrativeArea

string

包含這棟建築物的行政區 1 (例如美國的州)。例如在美國，縮寫可能為「MA」或「CA」。
statisticalArea

string

統計區 (例如美國人口普查區) 的建築物。
regionCode

string

這棟建築物所在國家/地區的區碼。
solarPotential

object (SolarPotential)

建築物的太陽能發電潛力。
imageryQuality

enum (ImageryQuality)

用於計算這棟建築物資料的影像品質。

授權範圍

需要下列 OAuth 範圍：

  • https://www.googleapis.com/auth/cloud-platform

LatLngBox

經緯度座標中的邊界框。

JSON 表示法 
{
  "sw": {
    object (LatLng)
  },
  "ne": {
    object (LatLng)
  }
}
欄位
sw

object (LatLng)

盒子的西南角。
ne

object (LatLng)

方塊的東北角。

SolarPotential

建築物太陽能發電潛力的相關資訊。其中的許多欄位是以「面板」的形式定義。欄位 panelCapacityWatts、panelHeightMeters 和 panelWidthMeters 會說明在這些計算中使用的面板模型參數。

JSON 表示法 
{
  "maxArrayPanelsCount": integer,
  "panelCapacityWatts": number,
  "panelHeightMeters": number,
  "panelWidthMeters": number,
  "panelLifetimeYears": integer,
  "maxArrayAreaMeters2": number,
  "maxSunshineHoursPerYear": number,
  "carbonOffsetFactorKgPerMwh": number,
  "wholeRoofStats": {
    object (SizeAndSunshineStats)
  },
  "buildingStats": {
    object (SizeAndSunshineStats)
  },
  "roofSegmentStats": [
    {
      object (RoofSegmentSizeAndSunshineStats)
    }
  ],
  "solarPanels": [
    {
      object (SolarPanel)
    }
  ],
  "solarPanelConfigs": [
    {
      object (SolarPanelConfig)
    }
  ],
  "financialAnalyses": [
    {
      object (FinancialAnalysis)
    }
  ]
}
欄位
maxArrayPanelsCount

integer

陣列大小上限，也就是可放置在屋頂的太陽能板數量上限。
panelCapacityWatts

number

計算中使用的面板容量 (以瓦為單位)。
panelHeightMeters

number

計算中使用的面板高度 (以公尺為單位，直向模式)。
panelWidthMeters

number

計算中使用的面板寬度，以公尺為單位，以直向方向計算。
panelLifetimeYears

integer

太陽能板的預期壽命 (以年為單位)。這會用於財務計算。
maxArrayAreaMeters2

number

陣列的大小 (以平方公尺為單位)。
maxSunshineHoursPerYear

number

屋頂任何一點每年可接收到的最大日照時數。日照小時是指每年所接收的總日照量 (能量)。1 小時日照 = 1 千瓦時/千瓦 (其中千瓦是指標準測試條件下的容量)。
carbonOffsetFactorKgPerMwh

number

每 1,000 度電的電網電力產生的二氧化碳當量。這項指標可衡量太陽能取代電網電力後的碳強度。
wholeRoofStats

object (SizeAndSunshineStats)

指派給某個屋頂區段的屋頂部分的總面積和日照百分位數。雖然名稱如此，但可能不包含整棟建築物。詳情請參閱《buildingStats》。
buildingStats

object (SizeAndSunshineStats)

整棟建築物的大小和日照百分位數，包括未指派至某個屋頂區段的屋頂部分。由於這些部分的方向無法明確界定，因此屋頂面積的估計值不可靠，但地面面積的估計值可靠。您可以根據 buildingStats 和 wholeRoofStats 的底部面積比率，將屋頂面積從 wholeRoofStats 縮放，以便取得更可靠的整棟建築物屋頂面積。
roofSegmentStats[]

object (RoofSegmentSizeAndSunshineStats)

每個屋頂區塊的大小和日照百分位數。
solarPanels[]

object (SolarPanel)

每個 SolarPanel 都會描述單一太陽能板。這些內容會按照面板版面配置演算法放置的順序列出。這通常 (但不一定) 是依每年能源產量由高至低排序。
solarPanelConfigs[]

object (SolarPanelConfig)

每個 SolarPanelConfig 都會說明屋頂上太陽能板的不同排列方式。這些選項的順序是依面板數量遞增。SolarPanelConfig 的 panelsCount=N 會根據 solarPanels 清單中前 N 個面板。只有在屋頂可容納至少 4 個太陽能板時，這個欄位才會填入資料。
financialAnalyses[]

object (FinancialAnalysis)

FinancialAnalysis 會根據特定月費和特定電力供應商，計算使用太陽能可節省多少費用。並依月度帳單金額由低至高排序。如果 Solar API 在某個區域內沒有足夠的資訊可執行財務計算，則該區域的建築物會在這個欄位中顯示空白。

SizeAndSunshineStats

屋頂或屋頂的一部分的大小和日照百分位數。

JSON 表示法 
{
  "areaMeters2": number,
  "sunshineQuantiles": [
    number
  ],
  "groundAreaMeters2": number
}
欄位
areaMeters2

number

屋頂或屋頂區段的面積，以 m^2 為單位。這是屋頂面積 (考量傾斜度)，而非地面占地面積。
sunshineQuantiles[]

number

整個區域內點狀陽光強度的百分位數。如果此處有 N 個值，則代表 (N-1) 個區間。舉例來說，如果有 5 個值，則會是四分位數 (最小值、25%、50%、75%、最大值)。值以每年 kWh/kW 為單位，例如 maxSunshineHoursPerYear。
groundAreaMeters2

number

涼屋頂或涼屋頂區塊涵蓋的面積，以平方公尺為單位。

RoofSegmentSizeAndSunshineStats

屋頂區塊的大小和日照百分位數資訊。

JSON 表示法 
{
  "stats": {
    object (SizeAndSunshineStats)
  },
  "center": {
    object (LatLng)
  },
  "boundingBox": {
    object (LatLngBox)
  },
  "pitchDegrees": number,
  "azimuthDegrees": number,
  "planeHeightAtCenterMeters": number
}
欄位
stats

object (SizeAndSunshineStats)

屋頂區塊的總面積和日照百分位數。
center

object (LatLng)

屋頂區段中心附近的點。
boundingBox

object (LatLngBox)

屋頂區塊的邊界框。
pitchDegrees

number

屋頂區段相對於理論地面平面的角度。0 = 平行於地面，90 = 垂直於地面。
azimuthDegrees

number

屋頂區隔指向的指南針方向。0 代表北方、90 代表東方、180 代表南方。對於「平坦」屋頂區段 (pitchDegrees 非常接近 0)，方位角並未明確定義，因此為了保持一致性，我們將其任意定義為 0 (北方)。
planeHeightAtCenterMeters

number

屋頂區段平面高度 (以公尺為單位)，位於 center 指定的點。搭配傾斜度、方位角和中心位置，即可完整定義屋頂區段平面。

SolarPanel

SolarPanel 會說明單一太陽能板的位置、方向和產量。如要瞭解面板的參數，請參閱 SolarPotential 中的 panelHeightMeters、panelWidthMeters 和 panelCapacityWatts 欄位。

JSON 表示法 
{
  "center": {
    object (LatLng)
  },
  "orientation": enum (SolarPanelOrientation),
  "yearlyEnergyDcKwh": number,
  "segmentIndex": integer
}
欄位
center

object (LatLng)

面板的中心。
orientation

enum (SolarPanelOrientation)

面板的方向。
yearlyEnergyDcKwh

number

這項配置在一年內可捕捉多少日照能量 (以直流千瓦時為單位)。
segmentIndex

integer

RoofSegmentSizeAndSunshineStats 的 roofSegmentStats 中索引，對應至放置此面板的屋頂區段。

SolarPanelOrientation

太陽能板的方向。這必須與太陽能板所在的屋頂區段方位角相對應。

列舉
SOLAR_PANEL_ORIENTATION_UNSPECIFIED 面板方向不明。
LANDSCAPE LANDSCAPE 面板的長邊與所放置屋頂區段的方位角方向垂直。
PORTRAIT PORTRAIT 面板的長邊與所放置屋頂區段的方位角方向平行。

SolarPanelConfig

SolarPanelConfig 會說明屋頂上太陽能板的特定位置。

JSON 表示法 
{
  "panelsCount": integer,
  "yearlyEnergyDcKwh": number,
  "roofSegmentSummaries": [
    {
      object (RoofSegmentSummary)
    }
  ]
}
欄位
panelsCount

integer

面板總數。請注意，這會導致 roofSegmentSummaries 中對應欄位的值 (加總) 重複。
yearlyEnergyDcKwh

number

假設太陽能板的配置方式如上所述，這項配置在一年內可捕捉多少日照能源 (以直流千瓦時為單位)。
roofSegmentSummaries[]

object (RoofSegmentSummary)

這個版面配置中，至少有一個面板的每個屋頂區段產量資訊。roofSegmentSummaries[i] 會說明第 i 個屋頂區段，包括其大小、預期產量和方向。

RoofSegmentSummary

建築物屋頂的某個區段資訊，其中放置了一些太陽能板。

JSON 表示法 
{
  "panelsCount": integer,
  "yearlyEnergyDcKwh": number,
  "pitchDegrees": number,
  "azimuthDegrees": number,
  "segmentIndex": integer
}
欄位
panelsCount

integer

這個區隔的面板總數。
yearlyEnergyDcKwh

number

假設太陽能板為上述型號，這部分的配置一年可捕捉多少日照能量 (以直流千瓦時為單位)。
pitchDegrees

number

屋頂區段相對於理論地面平面的角度。0 = 平行於地面，90 = 垂直於地面。
azimuthDegrees

number

屋頂區隔指向的指南針方向。0 代表北方、90 代表東方、180 代表南方。對於「平坦」屋頂區段 (pitchDegrees 非常接近 0)，方位角並未明確定義，因此為了保持一致性，我們將其任意定義為 0 (北方)。
segmentIndex

integer

對應 RoofSegmentSizeAndSunshineStats 在 roofSegmentStats 中的索引。

FinancialAnalysis

分析特定電費金額的最佳太陽能板配置方案，評估成本和效益。

JSON 表示法 
{
  "monthlyBill": {
    object (Money)
  },
  "defaultBill": boolean,
  "averageKwhPerMonth": number,
  "financialDetails": {
    object (FinancialDetails)
  },
  "leasingSavings": {
    object (LeasingSavings)
  },
  "cashPurchaseSavings": {
    object (CashPurchaseSavings)
  },
  "financedPurchaseSavings": {
    object (FinancedPurchaseSavings)
  },
  "panelConfigIndex": integer
}
欄位
monthlyBill

object (Money)

這項分析假設的每月電費。
defaultBill

boolean

是否為所選建築物所在區域的預設帳單大小。BuildingSolarPotential 中應只有一個 FinancialAnalysis 設定了 defaultBill。
averageKwhPerMonth

number

根據帳單金額和當地電費，計算出房屋平均每月用電量。
financialDetails

object (FinancialDetails)

無論使用何種融資方式，都適用的財務資訊。
leasingSavings

object (LeasingSavings)

太陽能板的租賃成本和效益。
cashPurchaseSavings

object (CashPurchaseSavings)

以現金購買太陽能板的成本和效益。
financedPurchaseSavings

object (FinancedPurchaseSavings)

透過融資購買太陽能板的成本和效益。
panelConfigIndex

integer

此帳單大小的最佳太陽能板配置的 solarPanelConfigs 索引。這個值可以是 -1，表示沒有版面配置。在這種情況下，系統會略過剩餘的子訊息。

金額

代表金額與其貨幣類型。

JSON 表示法 
{
  "currencyCode": string,
  "units": string,
  "nanos": integer
}
欄位
currencyCode

string

ISO 4217 定義的貨幣代碼，由 3 個字母組成。
units

string (int64 format)

金額的整數單位。舉例來說，如果 currencyCode 為 "USD"，則 1 個單位為 1 美元。
nanos

integer

金額的十億分之一 (10^-9) 單位數量。這個值必須介於 -999,999,999 和 +999,999,999 (含) 之間。如果 units 為正值，nanos 必須為正值或零；如果 units 為零，則 nanos 可為正值、零或負值；如果 units 為負值，nanos 就必須為負值或零。例如，$-1.75 美元的表記方式為 units=-1 和 nanos=-750,000,000。

FinancialDetails

財務分析的詳細資料。部分詳細資料已儲存在較高層級 (例如自付費用)。總金額是指 SolarPotential 中 panelLifetimeYears 欄位定義的生命週期。注意：購買面板的實際支出費用會顯示在 CashPurchaseSavings 的 outOfPocketCost 欄位中。

JSON 表示法 
{
  "initialAcKwhPerYear": number,
  "remainingLifetimeUtilityBill": {
    object (Money)
  },
  "federalIncentive": {
    object (Money)
  },
  "stateIncentive": {
    object (Money)
  },
  "utilityIncentive": {
    object (Money)
  },
  "lifetimeSrecTotal": {
    object (Money)
  },
  "costOfElectricityWithoutSolar": {
    object (Money)
  },
  "netMeteringAllowed": boolean,
  "solarPercentage": number,
  "percentageExportedToGrid": number
}
欄位
initialAcKwhPerYear

number

我們認為太陽能板在第一年可產生多少 AC kWh。
remainingLifetimeUtilityBill

object (Money)

太陽能板使用期間，非太陽能產生的電費。
federalIncentive

object (Money)

聯邦獎勵金金額；如果使用者購買太陽能板 (不論是否貸款)，就會適用這項資訊。
stateIncentive

object (Money)

可獲得的州政府補助金額；如果使用者購買太陽能板 (不論是否貸款)，就會適用這項資訊。
utilityIncentive

object (Money)

可透過公用事業補助獲得的金額；如果使用者購買太陽能板 (不論是否透過貸款)，就會適用這項資訊。
lifetimeSrecTotal

object (Money)

使用者在太陽能板使用期間可獲得的太陽能再生能源抵免額金額；如果使用者購買太陽能板 (無論是否貸款)，就會適用這項資訊。
costOfElectricityWithoutSolar

object (Money)

如果使用者沒有安裝太陽能板，在整個生命週期內所需支付的電費總額。
netMeteringAllowed

boolean

是否允許淨計量電價。
solarPercentage

number

使用者太陽能供應的電力百分比 (0-100)。第一年有效，但未來幾年可能會有所變動。
percentageExportedToGrid

number

我們假設太陽能發電量中，有多少百分比 (0-100%) 會輸出至電網，以第一季的發電量為依據。如果不允許淨計量，這會影響計算結果。

LeasingSavings

租用特定太陽能板配置的成本和效益，以及特定電力使用量。

JSON 表示法 
{
  "leasesAllowed": boolean,
  "leasesSupported": boolean,
  "annualLeasingCost": {
    object (Money)
  },
  "savings": {
    object (SavingsOverTime)
  }
}
欄位
leasesAllowed

boolean

這個管轄區是否允許租賃 (部分州不允許租賃)。如果這個欄位為 false，則系統可能會忽略此訊息中的值。
leasesSupported

boolean

財務計算引擎是否支援這個管轄區的租賃方案。如果這個欄位為 false，則系統可能會忽略此訊息中的值。這與 leasesAllowed 無關：在某些地區，租賃是允許的，但條件必須是財務模型無法處理的情況。
annualLeasingCost

object (Money)

預估每年租金費用。
savings

object (SavingsOverTime)

在整個生命週期中，節省 (或未節省) 的金額。

SavingsOverTime

不同付款方式之間共用的財務資訊。

JSON 表示法 
{
  "savingsYear1": {
    object (Money)
  },
  "savingsYear20": {
    object (Money)
  },
  "presentValueOfSavingsYear20": {
    object (Money)
  },
  "savingsLifetime": {
    object (Money)
  },
  "presentValueOfSavingsLifetime": {
    object (Money)
  },
  "financiallyViable": boolean
}
欄位
savingsYear1

object (Money)

安裝太陽能板後，第一年可節省的費用。
savingsYear20

object (Money)

安裝太陽能板後，前二十年可節省的費用。
presentValueOfSavingsYear20

object (Money)

假設折現率，20 年累積的儲蓄現值是多少？
savingsLifetime

object (Money)

整個面板的使用壽命期間。
presentValueOfSavingsLifetime

object (Money)

假設折現率為 10%，累計終身儲蓄的現值是多少？
financiallyViable

boolean

指出這個情境是否可行。如果財務可行性不佳 (例如虧損)，則為 false。

CashPurchaseSavings

購買特定太陽能板配置的成本和效益，以及特定電力使用量。

JSON 表示法 
{
  "outOfPocketCost": {
    object (Money)
  },
  "upfrontCost": {
    object (Money)
  },
  "rebateValue": {
    object (Money)
  },
  "savings": {
    object (SavingsOverTime)
  },
  "paybackYears": number
}
欄位
outOfPocketCost

object (Money)

稅前優惠成本：必須自付的金額。與 upfrontCost 形成對比，後者是扣除稅務獎勵後的金額。
upfrontCost

object (Money)

扣除稅務獎勵後的初始成本：這是第一年必須支付的金額。與 outOfPocketCost 相反，後者是稅前獎勵。
rebateValue

object (Money)

所有稅金退款的金額。
savings

object (SavingsOverTime)

在整個生命週期中，節省 (或未節省) 的金額。
paybackYears

number

回本所需的年數。負值表示在生命週期內不會發生回本。

FinancedPurchaseSavings

使用貸款購買特定太陽能板組合 (搭配特定用電量) 的成本和效益。

JSON 表示法 
{
  "annualLoanPayment": {
    object (Money)
  },
  "rebateValue": {
    object (Money)
  },
  "loanInterestRate": number,
  "savings": {
    object (SavingsOverTime)
  }
}
欄位
annualLoanPayment

object (Money)

按年付款。
rebateValue

object (Money)

所有稅務抵免額的價值 (包括聯邦投資稅抵免額 (ITC))。
loanInterestRate

number

這組計算作業中假設的貸款利率。
savings

object (SavingsOverTime)

在整個生命週期中，節省 (或未節省) 的金額。