buildingInsights 엔드포인트는 건물의 위치, 크기, 태양광 잠재 발전량에 관한 정보를 제공합니다. 특히 다음과 같은 정보를 확인할 수 있습니다.
- 태양광 패널 크기, 연간 일조량, 탄소 상쇄 요인 등을 포함한 태양광 잠재 발전량
- 태양광 패널 위치, 방향, 에너지 생산량
- 최적의 태양광 레이아웃의 예상 월별 에너지 요금 및 관련 비용과 이점
Solar API에서 태양광 잠재 발전량과 일조량을 정의하는 방법을 자세히 알아보려면 Solar API 개념을 참고하세요.
API 탐색기를 사용하면 실시간 요청을 수행하여 API 및 API 옵션을 숙지할 수 있습니다.
건물 통계 요청 정보
건물 통계를 요청하려면 다음 주소로 HTTP GET 요청을 보냅니다.
https://solar.googleapis.com/v1/buildingInsights:findClosest?key=YOUR_API_KEY
위치의 위도 및 경도 좌표와 결과에 허용되는 최소 필수 품질 수준을 지정하는 요청 URL 매개변수를 포함합니다.
통계 응답 작성 정보
Solar API는 응답 본문에서 건물의 위치, 크기, 태양광 잠재력에 관한 정보를 반환합니다.
이미지 품질
특정 위치에서 요청된 이미지 품질이 사용 가능한 이미지 품질과 다른 경우도 있습니다. 이러한 시나리오에서는 다음과 같은 동작이 예상됩니다.
| 시나리오 | 응답 동작 |
|---|---|
위치에 requiredQuality을 충족하는 이미지가 없습니다. |
Solar API는 404 상태 코드와 함께 NOT_FOUND 오류를 반환합니다. |
요청에서 특정 requiredQuality를 지정하지만 더 높은 이미지 품질 수준의 데이터만 사용할 수 있습니다. |
Solar API는 해당 위치에서 사용할 수 있는 최고 품질의 데이터를 반환합니다. |
건물 통계 요청 예시
다음 예시에서는 위도 = 37.4450, 경도 = -122.1390 좌표에 있는 위치의 건물 통계 정보를 요청합니다.
API 키
API 키를 사용하여 요청하려면 API 키를 입력 매개변수로 포함합니다.
curl -X GET "https://solar.googleapis.com/v1/buildingInsights:findClosest?location.latitude=37.4450 &location.longitude=-122.1390 &requiredQuality=HIGH &key=YOUR_API_KEY"
cURL 요청의 URL을 브라우저의 URL 표시줄에 붙여넣어 HTTP 요청을 수행할 수도 있습니다.
OAuth 토큰
참고: 이 형식은 테스트 환경 전용입니다. 자세한 내용은 OAuth 사용을 참고하세요.
OAuth를 사용하여 요청하려면 결제 프로젝트 이름과 OAuth 토큰을 전달합니다.
curl -H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "X-Goog-User-Project: PROJECT_NUMBER_OR_ID" \
"https://solar.googleapis.com/v1/buildingInsights:findClosest?location.latitude=37.4450&location.longitude=-122.1390"
TypeScript
TypeScript를 사용하여 요청하려면 요청에 API 키 또는 OAuth 토큰을 포함하세요. 다음 예시에서는 API 키를 사용합니다.
/** * Fetches the building insights information from the Solar API. * https://developers.google.com/maps/documentation/solar/building-insights * * @param {LatLng} location Point of interest as latitude longitude. * @param {string} apiKey Google Cloud API key. * @return {Promise<DataLayersResponse>} Building Insights response. */ export async function findClosestBuilding( location: google.maps.LatLng, apiKey: string, ): Promise<BuildingInsightsResponse> { const args = { 'location.latitude': location.lat().toFixed(5), 'location.longitude': location.lng().toFixed(5), // The Solar API always returns the highest quality imagery available. required_quality: 'BASE', }; console.log('GET buildingInsights\n', args); const params = new URLSearchParams({ ...args, key: apiKey }); // https://developers.google.com/maps/documentation/solar/reference/rest/v1/buildingInsights/findClosest return fetch(`https://solar.googleapis.com/v1/buildingInsights:findClosest?${params}`).then( async (response) => { const content = await response.json(); if (response.status != 200) { console.error('findClosestBuilding\n', content); throw content; } console.log('buildingInsightsResponse', content); return content; }, ); }
데이터 유형 정의
지원되는 데이터 유형은 다음과 같습니다.
export interface DataLayersResponse { imageryDate: Date; imageryProcessedDate: Date; dsmUrl: string; rgbUrl: string; maskUrl: string; annualFluxUrl: string; monthlyFluxUrl: string; hourlyShadeUrls: string[]; imageryQuality: 'HIGH' | 'MEDIUM' | 'BASE'; } export interface Bounds { north: number; south: number; east: number; west: number; } // https://developers.google.com/maps/documentation/solar/reference/rest/v1/buildingInsights/findClosest export interface BuildingInsightsResponse { name: string; center: LatLng; boundingBox: LatLngBox; imageryDate: Date; imageryProcessedDate: Date; postalCode: string; administrativeArea: string; statisticalArea: string; regionCode: string; solarPotential: SolarPotential; imageryQuality: 'HIGH' | 'MEDIUM' | 'BASE'; } export interface SolarPotential { maxArrayPanelsCount: number; panelCapacityWatts: number; panelHeightMeters: number; panelWidthMeters: number; panelLifetimeYears: number; maxArrayAreaMeters2: number; maxSunshineHoursPerYear: number; carbonOffsetFactorKgPerMwh: number; wholeRoofStats: SizeAndSunshineStats; buildingStats: SizeAndSunshineStats; roofSegmentStats: RoofSegmentSizeAndSunshineStats[]; solarPanels: SolarPanel[]; solarPanelConfigs: SolarPanelConfig[]; financialAnalyses: object; } export interface SizeAndSunshineStats { areaMeters2: number; sunshineQuantiles: number[]; groundAreaMeters2: number; } export interface RoofSegmentSizeAndSunshineStats { pitchDegrees: number; azimuthDegrees: number; stats: SizeAndSunshineStats; center: LatLng; boundingBox: LatLngBox; planeHeightAtCenterMeters: number; } export interface SolarPanel { center: LatLng; orientation: 'LANDSCAPE' | 'PORTRAIT'; segmentIndex: number; yearlyEnergyDcKwh: number; } export interface SolarPanelConfig { panelsCount: number; yearlyEnergyDcKwh: number; roofSegmentSummaries: RoofSegmentSummary[]; } export interface RoofSegmentSummary { pitchDegrees: number; azimuthDegrees: number; panelsCount: number; yearlyEnergyDcKwh: number; segmentIndex: number; } export interface LatLng { latitude: number; longitude: number; } export interface LatLngBox { sw: LatLng; ne: LatLng; } export interface Date { year: number; month: number; day: number; } export interface RequestError { error: { code: number; message: string; status: string; }; }
이 요청은 다음과 같은 형식의 JSON 응답을 생성합니다.
{ "name": "buildings/ChIJh0CMPQW7j4ARLrRiVvmg6Vs", "center": { "latitude": 37.4449439, "longitude": -122.13914659999998 }, "imageryDate": { "year": 2022, "month": 8, "day": 14 }, "postalCode": "94303", "administrativeArea": "CA", "statisticalArea": "06085511100", "regionCode": "US", "solarPotential": { "maxArrayPanelsCount": 1163, "maxArrayAreaMeters2": 1903.5983, "maxSunshineHoursPerYear": 1802, "carbonOffsetFactorKgPerMwh": 428.9201, "wholeRoofStats": { "areaMeters2": 2399.3958, "sunshineQuantiles": [ 351, 1396, 1474, 1527, 1555, 1596, 1621, 1640, 1664, 1759, 1864 ], "groundAreaMeters2": 2279.71 }, "roofSegmentStats": [ { "pitchDegrees": 11.350553, "azimuthDegrees": 269.6291, "stats": { "areaMeters2": 452.00052, "sunshineQuantiles": [ 408, 1475, 1546, 1575, 1595, 1606, 1616, 1626, 1635, 1643, 1761 ], "groundAreaMeters2": 443.16 }, "center": { "latitude": 37.444972799999995, "longitude": -122.13936369999999 }, "boundingBox": { "sw": { "latitude": 37.444732099999996, "longitude": -122.1394224 }, "ne": { "latitude": 37.4451909, "longitude": -122.13929279999999 } }, "planeHeightAtCenterMeters": 10.7835045 }, /.../ ], "solarPanelConfigs": [ { "panelsCount": 4, "yearlyEnergyDcKwh": 1819.8662, "roofSegmentSummaries": [ { "pitchDegrees": 12.273684, "azimuthDegrees": 179.12555, "panelsCount": 4, "yearlyEnergyDcKwh": 1819.8663, "segmentIndex": 1 } ] }, /.../ ] "financialAnalyses": [ { "monthlyBill": { "currencyCode": "USD", "units": "20" }, "panelConfigIndex": -1 }, { "monthlyBill": { "currencyCode": "USD", "units": "25" }, "panelConfigIndex": -1 }, { "monthlyBill": { "currencyCode": "USD", "units": "30" }, "panelConfigIndex": -1 }, { "monthlyBill": { "currencyCode": "USD", "units": "35" }, "panelConfigIndex": 0, "financialDetails": { "initialAcKwhPerYear": 1546.8864, "remainingLifetimeUtilityBill": { "currencyCode": "USD", "units": "2563" }, "federalIncentive": { "currencyCode": "USD", "units": "1483" }, "stateIncentive": { "currencyCode": "USD" }, "utilityIncentive": { "currencyCode": "USD" }, "lifetimeSrecTotal": { "currencyCode": "USD" }, "costOfElectricityWithoutSolar": { "currencyCode": "USD", "units": "10362" }, "netMeteringAllowed": true, "solarPercentage": 86.7469, "percentageExportedToGrid": 52.136684 }, "leasingSavings": { "leasesAllowed": true, "leasesSupported": true, "annualLeasingCost": { "currencyCode": "USD", "units": "335", "nanos": 85540771 }, "savings": { "savingsYear1": { "currencyCode": "USD", "units": "-10" }, "savingsYear20": { "currencyCode": "USD", "units": "1098" }, "presentValueOfSavingsYear20": { "currencyCode": "USD", "units": "568", "nanos": 380859375 }, "financiallyViable": true, "savingsLifetime": { "currencyCode": "USD", "units": "1098" }, "presentValueOfSavingsLifetime": { "currencyCode": "USD", "units": "568", "nanos": 380859375 } } }, "cashPurchaseSavings": { "outOfPocketCost": { "currencyCode": "USD", "units": "5704" }, "upfrontCost": { "currencyCode": "USD", "units": "4221" }, "rebateValue": { "currencyCode": "USD", "units": "1483", "nanos": 40039063 }, "paybackYears": 11.5, "savings": { "savingsYear1": { "currencyCode": "USD", "units": "325" }, "savingsYear20": { "currencyCode": "USD", "units": "7799" }, "presentValueOfSavingsYear20": { "currencyCode": "USD", "units": "1083", "nanos": 500244141 }, "financiallyViable": true, "savingsLifetime": { "currencyCode": "USD", "units": "7799" }, "presentValueOfSavingsLifetime": { "currencyCode": "USD", "units": "1083", "nanos": 500244141 } } }, "financedPurchaseSavings": { "annualLoanPayment": { "currencyCode": "USD", "units": "335", "nanos": 85540771 }, "rebateValue": { "currencyCode": "USD" }, "loanInterestRate": 0.05, "savings": { "savingsYear1": { "currencyCode": "USD", "units": "-10" }, "savingsYear20": { "currencyCode": "USD", "units": "1098" }, "presentValueOfSavingsYear20": { "currencyCode": "USD", "units": "568", "nanos": 380859375 }, "financiallyViable": true, "savingsLifetime": { "currencyCode": "USD", "units": "1098" }, "presentValueOfSavingsLifetime": { "currencyCode": "USD", "units": "568", "nanos": 380859375 } } } }, ], /.../ "panelCapacityWatts": 400, "panelHeightMeters": 1.879, "panelWidthMeters": 1.045, "panelLifetimeYears": 20, "buildingStats": { "areaMeters2": 2533.1233, "sunshineQuantiles": [ 348, 1376, 1460, 1519, 1550, 1590, 1618, 1638, 1662, 1756, 1864 ], "groundAreaMeters2": 2356.03 }, "solarPanels": [ { "center": { "latitude": 37.4449659, "longitude": -122.139089 }, "orientation": "LANDSCAPE", "yearlyEnergyDcKwh": 455.40714, "segmentIndex": 1 }, /.../ ] "imageryQuality": "HIGH", "imageryProcessedDate": { "year": 2023, "month": 8, "day": 4 } }
패널 설치를 위한 지붕 세그먼트 선택
경우에 따라 태양광 패널 배치를 위해 특정 지붕 세그먼트를 선택할 수 있습니다. roofSegmentStats는 지정된 지붕 세그먼트의 크기, 방향, 일조량 분위수에 대한 정보를 제공합니다.
"roofSegmentStats": [ { "pitchDegrees": 11.350553, "azimuthDegrees": 269.6291, "stats": { "areaMeters2": 452.00052, "sunshineQuantiles": [409.601, 1482.1255, 1553.5117, 1582.7875, 1602.3456, 1613.7804, 1623.6434, 1634.0812, 1642.697, 1651.0267, 1771.4792], "groundAreaMeters2": 443.16 }, "center": { "latitude": 37.4449728, "longitude": -122.1393637 }, "boundingBox": { "sw": { "latitude": 37.4447321, "longitude": -122.1394224 }, "ne": { "latitude": 37.4451909, "longitude": -122.1392928 } }, "planeHeightAtCenterMeters": 10.7835045 }, { "pitchDegrees": 12.273684, "azimuthDegrees": 179.12555, "stats": { "areaMeters2": 309.87268, "sunshineQuantiles": [650.5504, 1701.709, 1745.0032, 1768.4081, 1779.1625, 1787.4258, 1794.9333, 1801.3938, 1806.7461, 1814.0724, 1845.8717], "groundAreaMeters2": 302.79 }, "center": { "latitude": 37.4449286, "longitude": -122.1389889 }, "boundingBox": { "sw": { "latitude": 37.4448617, "longitude": -122.1392095 }, "ne": { "latitude": 37.444982, "longitude": -122.1387809 } }, "planeHeightAtCenterMeters": 10.67585 }, /.../ ],
이러한 특성을 기반으로 특정 지붕 세그먼트에 배치된 패널만 선택할 수 있습니다. buildingInsights 엔드포인트를 통해 반환되는 모든 패널에는 패널이 배치된 지붕 세그먼트를 나타내는 segmentIndex 값이 포함됩니다.
{ "panelsCount": 142, "yearlyEnergyDcKwh": 101170.17, "roofSegmentSummaries": [ { "pitchDegrees": 12.273684, "azimuthDegrees": 179.12555, "panelsCount": 122, "yearlyEnergyDcKwh": 87260.48, "segmentIndex": 1 }, { "pitchDegrees": 11.245564, "azimuthDegrees": 179.204, "panelsCount": 18, "yearlyEnergyDcKwh": 12544.052, "segmentIndex": 3 }, { "pitchDegrees": 2.5699794, "azimuthDegrees": 86.05642, "panelsCount": 1, "yearlyEnergyDcKwh": 681.69183, "segmentIndex": 10 }, { "pitchDegrees": 0.10844088, "azimuthDegrees": 0, "panelsCount": 1, "yearlyEnergyDcKwh": 683.9312, "segmentIndex": 14 } ] },
특정 특성이 있는 지붕 세그먼트의 패널을 선택하려면 segmentIndex로 필터링하면 됩니다. 예를 들어 지붕의 남향 부분에 패널을 배치하려면 azimuthDegrees 값이 90~270인 지붕 세그먼트를 식별한 다음 해당 segmentIndex를 사용하여 해당 지붕 세그먼트의 전체 패널 목록을 필터링합니다.
감지된 배열 데이터 요청
Solar API는 위성 이미지를 사용하여 기존 옥상 태양광 설치를 감지합니다. 지원되는 지역에 대한 자세한 내용은 지원 지역 지도를 참고하세요.
감지된 배열 데이터를 요청하려면 요청 본문에서 additionalInsights 매개변수를 DETECTED_ARRAYS로 설정합니다.
curl -X GET "https://solar.googleapis.com/v1/buildingInsights:findClosest?location.latitude=49.9263 &location.longitude=11.5870 &additionalInsights=DETECTED_ARRAYS &required_quality=BASE &key=YOUR_API_KEY"
응답 본문에는 다음과 같은 감지된 배열 정보가 포함됩니다.
- 건물 옥상에 태양광 설치가 감지되었는지 여부(
detectionStatus) - 감지에 사용된 최신 위성 이미지 캡처 날짜(
latestCaptureDate)(사용 가능한 경우) - 감지된 태양광 패널 (
arrays) 목록입니다. 각 배열은 태양광 패널의 단일 연속 영역을 나타내며 다음을 포함합니다.polygonGeojson: 태양광 패널이 감지된 지붕 면적의 GeoJSON 표현입니다. GeoJSON 데이터는 RFC 7946 형식이며 단일 연속 영역의Polygon를 나타냅니다. 구멍이 있는 다각형은 여러 루프로 표현됩니다.
arrays 목록은 detectionStatus가 DETECTION_STATUS_ARRAYS_DETECTED인 경우에만 채워집니다.
다음 예는 배열이 감지된 건물에 대한 응답을 보여줍니다(응답이 잘림).
{ "name": "buildings/ChIJ7zV8T9a8oUcRapOpazDCQEE", "center": { "latitude": 49.9262649, "longitude": 11.587273999999999 }, "imageryQuality": "HIGH", "imageryDate": { "year": 2016, "month": 6, "day": 11 }, ... "detectedArrays": { "detectionStatus": "DETECTION_STATUS_ARRAYS_DETECTED", "arrays": [ { "polygonGeojson": { "type": "Polygon", "coordinates": [ [ [11.5873992221349, 49.9262569599232], [11.5873991692473, 49.9262899326168], [11.5873805103546, 49.9262899153611], [11.5873807666599, 49.9262569221221], [11.5873992221349, 49.9262569599232] ] ] } }, ... ], "latestCaptureDate": { "year": 2025, "month": 5, "day": 14 } } }
기능을 사용해 보세요.
API 탐색기를 사용하면 샘플 요청을 수행하여 API 및 API 옵션을 숙지할 수 있습니다.
페이지 오른쪽에서 API 아이콘 api을 선택합니다.
원하는 경우 요청 매개변수를 수정합니다.
실행 버튼을 선택합니다. 대화상자에서 요청에 사용할 계정을 선택합니다.
I API 탐색기 패널에서 전체 화면 아이콘 전체 화면을 선택하여 API 탐색기 창을 펼칩니다.