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

建築物的資源名稱，格式為 building/<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 kWh (千瓦是指「標準測試條件」下的 kW 容量)。
carbonOffsetFactorKgPerMwh

number

每百萬瓦的電網電力產生的二氧化碳當量。這是指電網電力排放的碳排放強度。
wholeRoofStats

object (SizeAndSunshineStats)

指派給某些屋頂區塊的屋頂部分大小和日照量總和。儘管這個名稱無法涵蓋整棟建築物，但不包括整個建築物。詳情請參閱《buildingStats》。
buildingStats

object (SizeAndSunshineStats)

整個建築物的大小和陽光分位數，包括屋頂部分未分配到特定屋頂區域的部分。由於這些零件的方向沒有明確特徵，因此屋頂面積預估值並不可靠，但地面面積預估值是可靠的。可以藉由將 wholeRoofStats 的屋頂面積縮放 buildingStats 和 wholeRoofStats 地面區域的比例，得到更可靠的整個建築物屋頂區域。
roofSegmentStats[]

object (RoofSegmentSizeAndSunshineStats)

每個屋頂區隔的大小和陽光分位數。
solarPanels[]

object (SolarPanel)

每個 SolarPanel 都描述單一太陽能面板。這些類別會按照面板版面配置演算法放置此項目的順序列出。這通常但並非絕對，都是依照每年能源生產量遞減排序。
solarPanelConfigs[]

object (SolarPanelConfig)

每個 SolarPanelConfig 都說明屋頂的太陽能板排列方式不同。這些面板的數量會隨著面板數量增加而改變。panelsCount=N 的 SolarPanelConfig 以 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%、最大值)。值的單位為每千瓦時/千瓦時 (例如 maxSunshineHoursPerYear)。
groundAreaMeters2

number

屋頂或屋頂區隔所覆蓋的地面平面區域，單位為 m^2。

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

這個版面配置在一年內 (以資料中心 kWh) 擷取的日照能量。
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

這個版面配置在一年內 (以哥倫比亞特區 kWh) 擷取的日照量 (假設上述面板假設)
roofSegmentSummaries[]

object (RoofSegmentSummary)

每屋頂路段的製作相關資訊，且該版面配置至少含有一個固定樣本。roofSegmentSummaries[i] 說明 i-th 屋頂區段，包括其大小、預期產生和方向。

RoofSegmentSummary

建築物屋頂區塊的相關資訊，且該路段有一定數量的面板。

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

integer

這個區隔中的面板總數。
yearlyEnergyDcKwh

number

這部分版面配置在一年內 (以哥倫比亞特幣 kWh) 擷取的日照能量 (假設上述面板假設無誤)。
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 定義的貨幣代碼 (由三個字母表示)。
units

string (int64 format)

金額的整數單位。舉例來說，如果 currencyCode 是 "USD"，則 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)

安裝面板後的 20 年內節省費用。
presentValueOfSavingsYear20

object (Money)

使用假設折扣比率，20 年累積可省下的費用分別是多少？
savingsLifetime

object (Money)

整個面板生命週期節省量。
presentValueOfSavingsLifetime

object (Money)

使用假設折扣比率，累計生命週期省下的費用是多少？
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)

在整個生命週期中節省 (或不儲存) 的金額。