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)

(選用步驟) 指定要啟用的正式發布前實驗。根據《Google Maps Platform 服務專屬條款》，使用這個欄位的要求會歸類為正式發布前產品。詳情請參閱推出階段說明。
additionalInsights[]

enum (AdditionalInsights)

(選用步驟) 要納入回應的 additionalInsights 清單。

要求主體

要求主體必須為空白。

回應主體

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),
  "detectedArrays": {
    object (DetectedArrays)
  }
}
欄位
name

string

建築物的資源名稱，格式為 buildings/{place_id}。
center

object (LatLng)

靠近建築物中心的位置。
boundingBox

object (LatLngBox)

建築物的定界框。
imageryDate

object (Date)

取得基礎圖像的日期。這是約略值。
imageryProcessedDate

object (Date)

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

string

這棟建築物所在的郵遞區號 (例如美國郵遞區號)。
administrativeArea

string

建築物所在的第一行政區 (例如美國的州)。舉例來說，美國的縮寫可能是「MA」或「CA」。
statisticalArea

string

這棟建築物所在的統計區域 (例如美國人口普查區)。
regionCode

string

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

object (SolarPotential)

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

enum (ImageryQuality)

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

object (DetectedArrays)

在建築物上偵測到的太陽能板陣列。只有在要求的 FindClosestBuildingInsightsRequest.additional_insights 包含 DETECTED_ARRAYS 時，系統才會填入這個欄位。

授權範圍

需要下列 OAuth 範圍：

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

AdditionalInsights

BuildingInsights 可傳回其他建築物資訊，例如屋頂幾何圖形和太陽能面板陣列。

列舉
ADDITIONAL_INSIGHTS_UNSPECIFIED 預設值。系統會傳回預設的 BuildingInsights。
DETECTED_ARRAYS

決定回應是否包含偵測到的陣列。

如果指定，系統會在回應中填入 detectedArrays 欄位。

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 (kW 是指標準測試條件下的 kW 容量)。
carbonOffsetFactorKgPerMwh

number

每 MWh 電網電力產生的二氧化碳當量。這項指標用於衡量太陽能電力取代電網電力後的碳排放強度。
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

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

假設使用上述太陽能板，這個配置一年可收集多少陽光能量 (單位為 DC kWh)。
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 定義的三碼貨幣代碼。
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

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

終身期間節省 (或未節省) 的金額。

DetectedArrays

建築物上偵測到的太陽能陣列相關資訊。

JSON 表示法 
{
  "detectionStatus": enum (DetectionStatus),
  "arrays": [
    {
      object (SolarArray)
    }
  ],
  "latestCaptureDate": {
    object (Date)
  }
}
欄位
detectionStatus

enum (DetectionStatus)

指出這棟建築物的太陽能陣列偵測狀態。
arrays[]

object (SolarArray)

建築物上偵測到的太陽能板陣列清單。
latestCaptureDate

object (Date)

擷取最新太陽能陣列資料的日期。

DetectionStatus

指出這棟建築物的太陽能陣列偵測狀態。

列舉
DETECTION_STATUS_UNSPECIFIED 未指定狀態。
DETECTION_STATUS_DATA_UNAVAILABLE 無法提供這棟建築物的太陽能陣列偵測資料。
DETECTION_STATUS_ARRAYS_DETECTED 系統偵測到這棟建築物至少有一個太陽能陣列。
DETECTION_STATUS_NO_ARRAYS_DETECTED 未偵測到這棟建築物有太陽能陣列。

SolarArray

偵測到的單一太陽能陣列詳細資料。

JSON 表示法 
{
  "polygonGeojson": {
    object
  }
}
欄位
polygonGeojson

object (Struct format)

偵測到太陽能面板的建築物區域，以 GeoJSON 格式表示。

GeoJSON 資料必須採用 RFC 7946 格式，並以多邊形代表單一連續區域。

如果多邊形包含孔洞，則會以多個迴圈表示。

範例：

{ "type": "Polygon", "coordinates": [ [ [-1, -1], [-1, 0], [0, 0], [-1, -1] ] ] }