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 千瓦時 (即 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) 定義了方位素，因此為了維持一致性，我們會將該範圍定義為北 (北方)。
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

這個配置在一年內攝取的陽光量 (以 DC 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

這個版面配置在一年內 (以 DC kWh 表示) 所捕捉到的陽光 (假設有上述面板)。
roofSegmentSummaries[]

object (RoofSegmentSummary)

在此版面配置中至少有一個面板的屋頂路段製作資訊。roofSegmentSummaries[i] 說明第 i 棟屋頂的路段，包括其大小、預期生產和方向。

RoofSegmentSummary

建築物的屋頂區塊相關資訊，上面會放幾個面板。

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

integer

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

number

假設這部分版面配置在一年內 (以 DC kWh 表示) 拍攝的陽光 (假設有上述面板)。
pitchDegrees

number

屋頂平面的相對於理論地面平面圖。0 = 與地面平行，90 = 與地面垂直。
azimuthDegrees

number

指南針指向屋頂路段所指的方向。0 = 北，90 = 東；180 = 南部。「扁平」屋頂路段 (pitchDegrees 非常接近 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

金額的 nano (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

Google 覺得太陽能板在第一年會生產多少空調
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)

根據假設的折扣率，目前累計可省下的費用是多少？
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)

在整個生命週期內省下的費用金額。