건물 통계 요청하기

buildingInsights 엔드포인트는 건물의 위치, 크기, 태양광 발전량에 대한 유용한 정보를 제공합니다. 특히 다음에 관한 정보를 확인할 수 있습니다.

  • 태양광 패널 크기, 연간 일사량, 탄소 상쇄 요인 등 잠재 태양광 발전량
  • 태양 전지판 위치, 방향, 에너지 생산
  • 최적의 태양광 레이아웃과 관련 비용 및 이점에 대한 월 예상 에너지 청구서

Solar API가 태양광 잠재력과 햇빛을 정의하는 방식에 관한 자세한 내용은 Solar API 개념을 참고하세요.

API 탐색기를 사용하면 실시간 요청을 수행하여 API 및 API 옵션에 익숙해질 수 있습니다.

실습

통계 요청 작성 정보

빌드 통계를 요청하려면 다음 위치로 HTTP GET 요청을 보냅니다.

https://solar.googleapis.com/v1/buildingInsights:findClosest?key=YOUR_API_KEY

위치의 위도 및 경도 좌표와 결과에 허용되는 최소 필수 품질 수준을 지정하는 요청 URL 매개변수를 포함합니다.

빌드 통계 요청 예시

다음 예에서는 위도 = 37.4450, 경도 = -122.1390의 좌표에 해당하는 위치의 건물 통계 정보를 요청합니다.

API 키

응답의 URL에 요청을 하려면 API 키를 URL에 추가합니다.

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 요청을 수행할 수도 있습니다. API 키를 전달하면 사용 및 분석 기능이 향상되고 응답 데이터에 대한 액세스를 더 효과적으로 제어할 수 있습니다.

OAuth 토큰

참고: 이 형식은 테스트 환경 전용입니다. 자세한 내용은 OAuth 사용을 참고하세요.

응답의 URL에 요청을 하려면 결제 프로젝트 이름과 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

응답의 URL에 대한 요청을 하려면 요청에 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),
  };
  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' | 'LOW';
}

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' | 'LOW';
}

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.13911639999999
  },
  "imageryDate": {
    "year": 2018,
    "month": 6,
    "day": 4
  },
  "postalCode": "94303",
  "administrativeArea": "CA",
  "statisticalArea": "06085511100",
  "regionCode": "US",
  "solarPotential": {
    "maxArrayPanelsCount": 1373,
    "maxArrayAreaMeters2": 2247.3264,
    "maxSunshineHoursPerYear": 1809.6869,
    "carbonOffsetFactorKgPerMwh": 428.9201,
    "wholeRoofStats": {
      "areaMeters2": 2861.0686,
      "sunshineQuantiles": [
        384.4651,
        1385.7468,
        1465.545,
        1523.7301,
        1553.636,
        1589.27,
        1619.2816,
        1640.2871,
        1663.76,
        1750.4572,
        1883.4658
      ],
      "groundAreaMeters2": 2740.45
    },
    "roofSegmentStats": [
      {
        "pitchDegrees": 11.54571,
        "azimuthDegrees": 269.49054,
        "stats": {
          "areaMeters2": 478.75748,
          "sunshineQuantiles": [
            477.1805,
            1391.751,
            1515.6603,
            1555.4863,
            1579.1082,
            1594.9426,
            1607.4075,
            1621.5597,
            1631.4178,
            1641.8871,
            1727.1367
          ],
          "groundAreaMeters2": 469.07
        },
        "center": {
          "latitude": 37.4449647,
          "longitude": -122.1393672
        },
        "boundingBox": {
          "sw": {
            "latitude": 37.4447303,
            "longitude": -122.1394371
          },
          "ne": {
            "latitude": 37.4451819,
            "longitude": -122.1392963
          }
        },
        "planeHeightAtCenterMeters": 8.942595
      },
    ],
   "solarPanelConfigs": [
      {
        "panelsCount": 4,
        "yearlyEnergyDcKwh": 1823.9904,
        "roofSegmentSummaries": [
          {
            "pitchDegrees": 12.41514,
            "azimuthDegrees": 179.66463,
            "panelsCount": 4,
            "yearlyEnergyDcKwh": 1823.9905,
            "segmentIndex": 2
          }
        ]
      },
      /.../
    ]
   "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": 1550.3918,
          "remainingLifetimeUtilityBill": {
            "currencyCode": "USD",
            "units": "2548"
          },
          "federalIncentive": {
            "currencyCode": "USD",
            "units": "1483"
          },
          "stateIncentive": {
            "currencyCode": "USD"
          },
          "utilityIncentive": {
            "currencyCode": "USD"
          },
          "lifetimeSrecTotal": {
            "currencyCode": "USD"
          },
          "costOfElectricityWithoutSolar": {
            "currencyCode": "USD",
            "units": "10362"
          },
          "netMeteringAllowed": true,
          "solarPercentage": 86.94348,
          "percentageExportedToGrid": 52.350193
        },
        "leasingSavings": {
          "leasesAllowed": true,
          "leasesSupported": true,
          "annualLeasingCost": {
            "currencyCode": "USD",
            "units": "335",
            "nanos": 85540771
          },
          "savings": {
            "savingsYear1": {
              "currencyCode": "USD",
              "units": "-9"
            },
            "savingsYear20": {
              "currencyCode": "USD",
              "units": "1113"
            },
            "presentValueOfSavingsYear20": {
              "currencyCode": "USD",
              "units": "579",
              "nanos": 113281250
            },
            "financiallyViable": true,
            "savingsLifetime": {
              "currencyCode": "USD",
              "units": "1113"
            },
            "presentValueOfSavingsLifetime": {
              "currencyCode": "USD",
              "units": "579",
              "nanos": 113281250
            }
          }
        },
        "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": "326"
            },
            "savingsYear20": {
              "currencyCode": "USD",
              "units": "7815"
            },
            "presentValueOfSavingsYear20": {
              "currencyCode": "USD",
              "units": "1094",
              "nanos": 233276367
            },
            "financiallyViable": true,
            "savingsLifetime": {
              "currencyCode": "USD",
              "units": "7815"
            },
            "presentValueOfSavingsLifetime": {
              "currencyCode": "USD",
              "units": "1094",
              "nanos": 233276367
            }
          }
        },
        "financedPurchaseSavings": {
          "annualLoanPayment": {
            "currencyCode": "USD",
            "units": "335",
            "nanos": 85540771
          },
          "rebateValue": {
            "currencyCode": "USD"
          },
          "loanInterestRate": 0.05,
          "savings": {
            "savingsYear1": {
              "currencyCode": "USD",
              "units": "-9"
            },
            "savingsYear20": {
              "currencyCode": "USD",
              "units": "1113"
            },
            "presentValueOfSavingsYear20": {
              "currencyCode": "USD",
              "units": "579",
              "nanos": 113281250
            },
            "financiallyViable": true,
            "savingsLifetime": {
              "currencyCode": "USD",
              "units": "1113"
            },
            "presentValueOfSavingsLifetime": {
              "currencyCode": "USD",
              "units": "579",
              "nanos": 113281250
            }
          }
        }
      },
    ],
    /.../
    "panelCapacityWatts": 250,
    "panelHeightMeters": 1.65,
    "panelWidthMeters": 0.992,
    "panelLifetimeYears": 20,
    "buildingStats": {
      "areaMeters2": 2945.2869,
      "sunshineQuantiles": [
        372.5415,
        1371.2333,
        1456.3909,
        1519.6279,
        1550.9833,
        1586.4949,
        1617.6183,
        1639.3303,
        1662.812,
        1748.7468,
        1892.1855
      ],
      "groundAreaMeters2": 2789.4
    },
    "solarPanels": [
      {
        "center": {
          "latitude": 37.4449709,
          "longitude": -122.13907649999999
        },
        "orientation": "LANDSCAPE",
        "yearlyEnergyDcKwh": 456.5196,
        "segmentIndex": 2
      },
      /.../
    ]
  "imageryQuality": "HIGH",
  "imageryProcessedDate": {
    "year": 2022,
    "month": 10,
    "day": 16
  }
}

사용해 보기

API 탐색기를 사용하면 샘플 요청을 수행하여 API 및 API 옵션에 익숙해질 수 있습니다.

  1. 원하는 경우 요청 매개변수를 수정합니다.

  2. 실행 버튼을 선택합니다. 팝업 대화상자에서 요청에 사용할 계정을 선택합니다.