Package google.maps.solar.v1

索引

• Solar (介面)
• BuildingInsights (訊息)
• CashPurchaseSavings (訊息)
• DataLayerView (列舉)
• DataLayers (訊息)
• FinancedPurchaseSavings (訊息)
• FinancialAnalysis (訊息)
• FinancialDetails (訊息)
• FindClosestBuildingInsightsRequest (訊息)
• GetDataLayersRequest (訊息)
• GetGeoTiffRequest (訊息)
• ImageryQuality (列舉)
• LatLngBox (訊息)
• LeasingSavings (訊息)
• RoofSegmentSizeAndSunshineStats (訊息)
• RoofSegmentSummary (訊息)
• SavingsOverTime (訊息)
• SizeAndSunshineStats (訊息)
• SolarPanel (訊息)
• SolarPanelConfig (訊息)
• SolarPanelOrientation (列舉)
• SolarPotential (訊息)

太陽能

Solar API 的服務定義。

FindClosestBuildingInsights
rpc FindClosestBuildingInsights(FindClosestBuildingInsightsRequest) returns (BuildingInsights) 找出中心點距離查詢點最近的建築物。如果在查詢點附近 50 公尺內沒有任何建築物，系統會傳回代碼為 NOT_FOUND 的錯誤。 授權範圍 需要下列 OAuth 範圍： https://www.googleapis.com/auth/cloud-platform

GetDataLayers
rpc GetDataLayers(GetDataLayersRequest) returns (DataLayers) 取得某個位置周圍區域的太陽能資訊。如果位置不在涵蓋範圍內，則會傳回代碼 NOT_FOUND 的錯誤。 授權範圍 需要下列 OAuth 範圍： https://www.googleapis.com/auth/cloud-platform

GetGeoTiff
rpc GetGeoTiff(GetGeoTiffRequest) returns (HttpBody) 根據 ID 傳回圖片。 授權範圍 需要下列 OAuth 範圍： https://www.googleapis.com/auth/cloud-platform

BuildingInsights

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

欄位
name	string 大樓的資源名稱，格式為 buildings/{place_id}。
center	LatLng 位於建築物中心附近的點。
bounding_box	LatLngBox 建築物的定界框。
imagery_date	Date 取得底層圖像的日期。這是大約值。
imagery_processed_date	Date 這張圖像的處理作業完成時間。
postal_code	string 郵遞區號 (例如：郵遞區號) 的郵遞區號。
administrative_area	string 包含這棟建築物的行政區 1 (例如美國的州)。例如在美國，縮寫可能為「MA」或「CA」。
statistical_area	string 統計區 (例如美國人口普查區) 的建築物。
region_code	string 這棟建築物所在國家/地區的區碼。
solar_potential	SolarPotential 建築物的太陽能發電潛力。
imagery_quality	ImageryQuality 用於計算這棟建築物資料的影像品質。

CashPurchaseSavings

購買特定太陽能板配置 (搭配特定用電量) 的成本和效益。

欄位
out_of_pocket_cost	Money 稅前優惠成本：必須自付的金額。與 upfront_cost 形成對比，後者是扣除稅務獎勵後的金額。
upfront_cost	Money 扣除稅務獎勵後的初始成本：這是第一年必須支付的金額。與 out_of_pocket_cost 相反，後者是稅前獎勵。
rebate_value	Money 所有稅金退款的金額。
savings	SavingsOverTime 在整個生命週期中，節省 (或未節省) 的金額。
payback_years	float 回本所需的年數。負值表示在生命週期內不會發生回本。

DataLayerView

要傳回的太陽能資訊子集。

列舉
DATA_LAYER_VIEW_UNSPECIFIED	等同於 FULL。
DSM_LAYER	只取得 DSM。
IMAGERY_LAYERS	取得 DSM、RGB 和遮罩。
IMAGERY_AND_ANNUAL_FLUX_LAYERS	取得 DSM、RGB、遮罩和年度流量。
IMAGERY_AND_ALL_FLUX_LAYERS	取得 DSM、RGB、遮罩、年度流量和月度流量。
FULL_LAYERS	取得所有資料。

DataLayers

某個地區的太陽能發電潛力相關資訊。實際資料包含在涵蓋要求區域的多個 GeoTIFF 檔案中，此訊息包含這些檔案的網址：DataLayers 訊息中的每個字串都包含一個網址，可用來擷取對應的 GeoTIFF。這些網址在產生後的幾小時內有效。大部分的 GeoTIFF 檔案解析度為 0.1 公尺/像素，但月度通量檔案的解析度為 0.5 公尺/像素，每小時陰影檔案的解析度則為 1 公尺/像素。如果在 GetDataLayersRequest 中指定 pixel_size_meters 值，則 GeoTIFF 檔案中的最低解析度會是該值。

欄位
imagery_date	Date 這個區域的來源圖像 (所有其他資料皆源自此) 拍攝的時間。由於圖片可能在多天內拍攝，因此這項資訊僅供參考。
imagery_processed_date	Date 這張圖像的處理作業完成時間。
dsm_url	string 該區域的 DSM (數位地形模型) 圖片網址。值以 EGM96 地理編碼 (即海平面) 為單位。無效位置 (我們沒有資料的位置) 會儲存為 -9999。
rgb_url	string 該區域 RGB 資料 (航空照相) 圖片的網址。
mask_url	string 建築物遮罩圖片的網址：每個像素一個位元，指出該像素是否屬於屋頂。
annual_flux_url	string 該地區的年度動態地圖 (屋頂年度日照) 網址。值為 kWh/kW/年。這是未遮蔽的流量：系統會為每個位置計算流量，而非僅限於建築物屋頂。無效位置會以 -9999 儲存：涵蓋範圍外的地點會視為無效，而涵蓋範圍內無法計算變化率的部分地點也會視為無效。
monthly_flux_url	string 該地區每月流量地圖 (屋頂日照，按月份細分) 的網址。值為 kWh/kW/年。這個網址所指向的 GeoTIFF 會包含十二個頻帶，依序對應至 1 月至 12 月。
hourly_shade_urls[]	string 十二個小時陰影網址，依序對應至 1 月到 12 月。每個 GeoTIFF 都會包含 24 個頻帶，對應一天的 24 小時。每個像素都是 32 位元整數，對應於該月份 (最多) 31 天的時間點；1 位元代表對應位置在該月份的某一天、某個小時可見太陽。無效的位置會儲存為 -9999 (因為這個值為負值，因此會設為位元 31，且沒有有效值會設為位元 31，因為這會對應到該月的 32 日)。 舉例來說，如要知道某個點 (位於像素位置 (x, y)) 是否在 6 月 22 日下午 4 點看到太陽，請執行下列操作： 擷取清單中的第六個網址 (對應月份為六月)。 查看第 17 個頻道 (對應於下午 4 點)。 讀取 (x, y) 處的 32 位元值。 讀取值的位元 21 (對應於當月的 22 日)。 如果該位元是 1，表示該地點在 6 月 22 日下午 4 點看到太陽。 更正式的說法：假設 month (1-12)、day (1...月數上限；2 月有 28 天) 和 hour (0-23)，則該月/日/時在位置 (x, y) 的陰影/太陽為位元 (hourly_shade[month - 1])(x, y)[hour] & (1 << (day - 1)) 其中 (x, y) 是空間索引，[month - 1] 是指擷取 month - 1 個網址 (從 0 開始索引)，[hour] 是指在管道中建立索引，而最後的非零結果則代表「sunny」。沒有閏日，也沒有夏令時間 (所有日子都是 24 小時；中午一律是「標準時間」中午)。
imagery_quality	ImageryQuality 結果圖像的品質。

FinancedPurchaseSavings

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

欄位
annual_loan_payment	Money 按年付款。
rebate_value	Money 所有稅務抵免額的價值 (包括聯邦投資稅抵免額 (ITC))。
loan_interest_rate	float 這組計算作業中假設的貸款利率。
savings	SavingsOverTime 在整個生命週期中，節省 (或未節省) 的金額。

FinancialAnalysis

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

欄位
monthly_bill	Money 這項分析假設的每月電費。
default_bill	bool 是否為所選建築物所在區域的預設帳單大小。BuildingSolarPotential 中應只有一個 FinancialAnalysis 設定了 default_bill。
average_kwh_per_month	float 根據帳單金額和當地電費，計算房屋平均每月用電量。
financial_details	FinancialDetails 無論使用何種融資方式，都適用的財務資訊。
leasing_savings	LeasingSavings 太陽能板的租賃成本和效益。
cash_purchase_savings	CashPurchaseSavings 以現金購買太陽能板的成本和效益。
financed_purchase_savings	FinancedPurchaseSavings 透過融資購買太陽能板的成本和效益。
panel_config_index	int32 此帳單大小的最佳太陽能板配置的 solar_panel_configs 索引。這個值可以是 -1，表示沒有版面配置。在這種情況下，系統會略過剩餘的子訊息。

FinancialDetails

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

欄位
initial_ac_kwh_per_year	float 我們認為太陽能板在第一年可產生多少 AC kWh。
remaining_lifetime_utility_bill	Money 太陽能板使用期間，非太陽能產生的電費。
federal_incentive	Money 聯邦獎勵金金額；如果使用者購買太陽能板 (不論是否使用貸款)，就會適用這項資訊。
state_incentive	Money 使用者購買太陽能板 (無論是否使用貸款) 時，可獲得的政府補助金額。
utility_incentive	Money 可透過公用事業補助獲得的金額；如果使用者購買太陽能板 (不論是否透過貸款)，就會適用這項資訊。
lifetime_srec_total	Money 使用者在太陽能板使用期間可獲得的太陽能再生能源抵免額金額；如果使用者購買太陽能板 (無論是否貸款)，就會適用這項資訊。
cost_of_electricity_without_solar	Money 如果使用者未安裝太陽能板，在整個生命週期內所支付的電費總額。
net_metering_allowed	bool 是否允許淨計量。
solar_percentage	float 使用者太陽能供電的百分比 (0-100)。第一年有效，但未來幾年可能會有所變動。
percentage_exported_to_grid	float 我們假設太陽能發電量中，有多少百分比 (0-100%) 會輸出至電網，以第一季的發電量為依據。這會影響不允許淨計量時的計算結果。

FindClosestBuildingInsightsRequest

Solar.FindClosestBuildingInsights 的要求訊息。

欄位
location	LatLng 必要欄位。API 用來尋找最近已知建築物的經緯度。
required_quality	ImageryQuality 選用設定。結果中允許的最低品質等級。系統不會傳回品質低於此值的結果。如未指定，則系統會只限制高品質。

GetDataLayersRequest

Solar.GetDataLayers 的要求訊息。

欄位
location	LatLng 必要欄位。要取得資料的區域中心位置經緯度。
radius_meters	float 必要欄位。半徑 (以公尺為單位)，定義該中心點周圍的區域，系統會傳回該區域的資料。此值的限制如下： 您可以指定任何值 (上限為 100 公尺)。 只要 radius_meters <= pixel_size_meters * 1000，即可指定超過 100 公尺的值。 不過，如果值超過 175 公尺，請勿在要求中加入月度流量或每小時陰影的 DataLayerView。
view	DataLayerView 選用設定。要傳回的資料所需的子集。
required_quality	ImageryQuality 選用設定。結果中允許的最低品質等級。系統不會傳回品質低於此值的結果。如未指定，則系統會只限制高品質。
pixel_size_meters	float 選用設定。傳回資料的最小比例 (以每像素公尺為單位)。系統支援的值為 0.1 (如果未明確設定此欄位，則為預設值)、0.25、0.5 和 1.0。如果圖像元件的正常解析度小於 pixel_size_meters，系統會以 pixel_size_meters 指定的解析度傳回圖像元件；如果圖像元件的正常解析度等於或大於 pixel_size_meters，系統會以該正常解析度傳回圖像元件。
exact_quality_required	bool 選用設定。是否要求圖像的確切品質。如果設為 false，系統會將 required_quality 欄位解讀為最低要求的品質，因此當 required_quality 設為 MEDIUM 時，系統可能會傳回高品質圖像。如果設為 true，系統會將 required_quality 解讀為確切的必要品質，且只有在 required_quality 設為 MEDIUM 時，才會傳回 MEDIUM 品質的圖像。

GetGeoTiffRequest

Solar.GetGeoTiff 的要求訊息。

欄位
id	string 必要欄位。所要求素材資源的 ID。

ImageryQuality

用於計算部分 API 結果的影像品質。

注意：無論圖像品質等級為何，DSM 輸出結果一律為 0.1 公尺/像素，月流量輸出結果一律為 0.5 公尺/像素，每小時陰影輸出結果一律為 1 公尺/像素。

列舉
IMAGERY_QUALITY_UNSPECIFIED	品質不明。
HIGH	太陽資料是從低空拍攝的空拍圖像擷取，並以 0.1 公尺/像素的解析度處理。
MEDIUM	太陽能資料是從高空拍攝的強化空拍圖像擷取，並以 0.25 公尺/像素的解析度處理。
LOW	太陽能資料是從以 0.25 公尺/像素處理的強化衛星圖像衍生而來。
BASE	太陽能資料是從以 0.25 公尺/像素處理的強化衛星圖像衍生而來。

LatLngBox

經緯度座標中的邊界框。

欄位
sw	LatLng 盒子的西南角。
ne	LatLng 方塊的東北角。

LeasingSavings

租用特定太陽能板組合 (搭配特定用電量) 的成本和效益。

欄位
leases_allowed	bool 這個管轄區是否允許租賃 (部分州不允許租賃)。如果這個欄位為 false，系統可能會忽略此訊息中的值。
leases_supported	bool 財務計算引擎是否支援這個管轄區的租賃方案。如果這個欄位為 false，系統可能會忽略此訊息中的值。這與 leases_allowed 無關：在某些地區，租賃交易是允許的，但條件必須是財務模型無法處理的情況。
annual_leasing_cost	Money 預估每年租金費用。
savings	SavingsOverTime 在整個生命週期中，節省 (或未節省) 的金額。

RoofSegmentSizeAndSunshineStats

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

欄位
stats	SizeAndSunshineStats 屋頂區塊的總面積和日照百分位數。
center	LatLng 屋頂區段中心附近的點。
bounding_box	LatLngBox 屋頂區塊的邊界框。
pitch_degrees	float 屋頂區段相對於理論地面平面的角度。0 = 平行於地面，90 = 垂直於地面。
azimuth_degrees	float 屋頂區隔指向的指南針方向。0 代表北方、90 代表東方、180 代表南方。對於「平坦」屋頂區段 (pitch_degrees 非常接近 0)，方位角並未明確定義，因此為了保持一致性，我們將其任意定義為 0 (北方)。
plane_height_at_center_meters	float 屋頂區段平面高度 (以公尺為單位)，位於 center 指定的點。搭配傾斜度、方位角和中心位置，即可完整定義屋頂區段平面。

RoofSegmentSummary

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

欄位
panels_count	int32 這個區隔的面板總數。
yearly_energy_dc_kwh	float 假設太陽能板為上述型號，這部分的配置一年可捕捉多少日照能量 (以直流千瓦時計)。
pitch_degrees	float 屋頂區段相對於理論地面平面的角度。0 = 平行於地面，90 = 垂直於地面。
azimuth_degrees	float 屋頂區隔指向的指南針方向。0 代表北方、90 代表東方、180 代表南方。對於「平坦」屋頂區段 (pitch_degrees 非常接近 0)，方位角並未明確定義，因此為了保持一致性，我們將其任意定義為 0 (北方)。
segment_index	int32 對應 RoofSegmentSizeAndSunshineStats 在 roof_segment_stats 中的索引。

SavingsOverTime

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

欄位
savings_year1	Money 安裝太陽能板後，第一年可節省的費用。
savings_year20	Money 安裝太陽能板後，前二十年可節省的費用。
present_value_of_savings_year20	Money 假設折現率，20 年累積的儲蓄現值是多少？
savings_lifetime	Money 整個面板的使用壽命期間節省的費用。
present_value_of_savings_lifetime	Money 假設折現率為 10%，累計終身儲蓄的現值是多少？
financially_viable	bool 指出這個情境是否可行。如果財務可行性不佳 (例如虧損)，則為 false。

SizeAndSunshineStats

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

欄位
area_meters2	float 屋頂或屋頂區段的面積，以 m^2 為單位。這是屋頂面積 (考量傾斜度)，而非地面占地面積。
sunshine_quantiles[]	float 整個區域內各點的陽光強度百分位數。如果此處有 N 個值，則代表 (N-1) 個區間。舉例來說，如果有 5 個值，則會是四分位數 (最小值、25%、50%、75%、最大值)。值以每年 kWh/kW 為單位，例如 max_sunshine_hours_per_year。
ground_area_meters2	float 涼屋頂或涼屋頂區段所涵蓋的面積，以 m^2 為單位。

SolarPanel

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

欄位
center	LatLng 面板的中心。
orientation	SolarPanelOrientation 面板的方向。
yearly_energy_dc_kwh	float 這項配置在一年內可捕捉多少日照能量 (以直流千瓦時為單位)。
segment_index	int32 RoofSegmentSizeAndSunshineStats 的 roof_segment_stats 中索引，對應至放置此面板的屋頂區段。

SolarPanelConfig

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

欄位
panels_count	int32 面板總數。請注意，這會導致 roof_segment_summaries 中對應欄位的值 (加總) 重複。
yearly_energy_dc_kwh	float 假設太陽能板的配置方式如上所述，這項配置在一年內可捕捉多少日照能量 (以直流千瓦時計)。
roof_segment_summaries[]	RoofSegmentSummary 這個版面配置中，至少包含一個面板的每個屋頂區段產量資訊。roof_segment_summaries[i] 會說明第 i 個屋頂區段，包括其大小、預期產量和方向。

SolarPanelOrientation

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

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

SolarPotential

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

欄位
max_array_panels_count	int32 陣列大小上限，也就是可放置在屋頂的太陽能板數量上限。
panel_capacity_watts	float 計算中使用的面板容量 (以瓦為單位)。
panel_height_meters	float 計算中使用的面板高度 (以公尺為單位，直向模式)。
panel_width_meters	float 計算中使用的面板寬度 (以公尺為單位，直向)。
panel_lifetime_years	int32 太陽能板的預期壽命 (以年為單位)。這會用於財務計算。
max_array_area_meters2	float 陣列的大小 (以平方公尺為單位)。
max_sunshine_hours_per_year	float 屋頂任何一點每年可接收到的最大日照時數。日照小時是指每年所接收的總日照量 (能量)。1 小時日照 = 1 千瓦時/千瓦 (其中千瓦是指標準測試條件下的容量)。
carbon_offset_factor_kg_per_mwh	float 每 1,000 度電的電網電力產生的二氧化碳當量。這項指標可衡量太陽能取代電網電力後的碳強度。
whole_roof_stats	SizeAndSunshineStats 指派給某個屋頂區段的屋頂部分的總面積和日照百分位數。雖然名稱如此，但可能不包含整棟建築物。詳情請參閱《building_stats》。
building_stats	SizeAndSunshineStats 整棟建築物的大小和日照百分位數，包括未指派給某些屋頂區段的屋頂部分。由於這些部分的方向無法明確界定，因此屋頂面積的估計值不可靠，但地面面積的估計值可靠。您可以根據 building_stats 和 whole_roof_stats 的底部面積比率，從 whole_roof_stats 縮放屋頂面積，以便取得更可靠的整棟建築物屋頂面積。
roof_segment_stats[]	RoofSegmentSizeAndSunshineStats 每個屋頂區塊的大小和日照百分位數。
solar_panels[]	SolarPanel 每個 SolarPanel 都會描述單一太陽能板。這些內容會按照面板版面配置演算法放置的順序列出。這通常 (但不一定) 是依每年能源產量由高至低排序。
solar_panel_configs[]	SolarPanelConfig 每個 SolarPanelConfig 都會說明屋頂上太陽能板的不同排列方式。這些選項的順序是依面板數量遞增。SolarPanelConfig 的 panels_count=N 會根據 solar_panels 清單中前 N 個面板。只有在屋頂可容納至少 4 個太陽能板時，這個欄位才會填入資料。
financial_analyses[]	FinancialAnalysis FinancialAnalysis 會根據特定月費和特定電力供應商，計算採用太陽能系統可節省的費用。這些方案的月費金額依序遞增。如果 Solar API 在某個區域內沒有足夠的資訊可執行財務計算，則該區域內的建築物會顯示空白。