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 时，可能会返回高画质的图像。如果设置为 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

包含此建筑物的行政区 1（例如，在美国，指州）。例如，在美国，缩写可能是“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

每兆瓦时电网电力产生的二氧化碳当量。这是对太阳能电力所替代的电网电力的碳强度的衡量。
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

roofSegmentStats 中 RoofSegmentSizeAndSunshineStats 的索引，对应于此面板所在的屋顶区段。

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，表示没有布局。在这种情况下，其余子消息将被省略。

Money

表示含有货币类型的金额。

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

我们预计太阳能板在第一年产生的交流电千瓦时数。
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)

在整个生命周期内节省（或未节省）的金额。

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] ] ] }