Method: buildingInsights.findClosest

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

HTTP 要求

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

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

查詢參數

參數
location

object (LatLng)

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

enum (ImageryQuality)

(選用步驟) 結果中允許的最低品質等級。系統不會傳回畫質低於此值的結果。如未指定，則相當於只限制為「高」品質。
exactQualityRequired

boolean

(選用步驟) 是否要求圖像品質完全符合規定。如果設為 false，系統會將 requiredQuality 欄位解讀為最低必要品質，因此當 requiredQuality 設為 MEDIUM 時，可能會傳回 HIGH 品質的圖像。如果設為 true，系統會將 requiredQuality 解讀為確切的必要品質，且只會在 requiredQuality 設為 MEDIUM 時傳回 MEDIUM 品質的圖像。
experiments[]

enum (Experiment)

(選用步驟) 指定要啟用的正式發布前功能。

要求主體

要求主體必須為空白。

回應主體

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)

整棟建築物的大小和日照量分位數，包括未指派給任何屋頂區段的屋頂部分。由於這些零件的方向並未明確標示，因此屋頂面積估算結果不可靠，但地面面積估算結果可靠。或許可以透過以下方式，取得更可靠的整棟建築物屋頂面積：將 wholeRoofStats 的屋頂面積，依 buildingStats 和 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

屋頂或屋頂區段的面積，以平方公尺為單位。這是屋頂面積 (已考量傾斜度)，而非地面足跡面積。
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

這個配置一年可擷取的太陽能電力 (以直流電 kWh 為單位)。
segmentIndex

integer

RoofSegmentSizeAndSunshineStats 中的 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 個屋頂區段，包括大小、預期產量和方位。

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 定義的貨幣代碼，由 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

我們預估太陽能板在第一年可產生的交流電 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)

假設折扣率為 10%，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)

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