發出資料層要求

dataLayers 端點可針對指定位置周圍的區域提供詳細的太陽能資訊。端點會傳回 17 個可下載的 TIFF 檔案，包括：

• 數位表面模型 (DSM)
• RGB 複合圖層 (空照圖像)
• 識別分析邊界的遮罩層
• 年度太陽能流感，或特定表面的年收益
• 每月太陽能流動量，或特定表面的每月產量
• 每小時遮蔭 (24 小時)

如要進一步瞭解 Solar API 如何定義 flux，請參閱「Solar API 概念」。

關於資料層要求

以下範例顯示向 dataLayers 方法發出的 REST 要求網址：

https://solar.googleapis.com/v1/dataLayers:get?parameters

加入要求網址參數，並指定下列各項：

• 營業地點的經緯度座標
• 位置周圍的區域半徑
• 要傳回的資料子集 (DSM、RGB、遮罩、年度流量或每月流動量)
• 結果所允許的最低品質
• 要傳回的資料最小尺度 (以像素為單位)

資料層要求範例

以下範例會要求該位置以經緯度座標 = 37.4450，且經度 = -122.1390 為 100 公尺的所有建築物深入分析資訊：

API 金鑰

如要對回應中的網址提出要求，請在網址內附加 API 金鑰：

curl -X GET "https://solar.googleapis.com/v1/dataLayers:get?location.latitude=37.4450&location.longitude=-122.1390&radiusMeters=100&view=FULL_LAYERS&requiredQuality=HIGH&exactQualityRequired=true&pixelSizeMeters=0.5&key=YOUR_API_KEY"

您也可以在瀏覽器的網址列貼上 cURL 要求中的網址，藉此提出 HTTP 要求。傳遞 API 金鑰可讓您享有更好的使用與分析功能，以及更精準地控管回應資料。

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/dataLayers:get?location.latitude=37.4450&location.longitude=-122.1390&radius_meters=100&required_quality=HIGH&exactQualityRequired=true"
        

TypeScript

如要對回應中的網址提出要求，請在要求中加入 API 金鑰或 OAuth 權杖。以下範例使用 API 金鑰：

/**
 * Fetches the data layers information from the Solar API.
 *   https://developers.google.com/maps/documentation/solar/data-layers
 *
 * @param  {LatLng} location      Point of interest as latitude longitude.
 * @param  {number} radiusMeters  Radius of the data layer size in meters.
 * @param  {string} apiKey        Google Cloud API key.
 * @return {Promise<DataLayersResponse>}  Data Layers response.
 */
export async function getDataLayerUrls(
  location: LatLng,
  radiusMeters: number,
  apiKey: string,
): Promise<DataLayersResponse> {
  const args = {
    'location.latitude': location.latitude.toFixed(5),
    'location.longitude': location.longitude.toFixed(5),
    radius_meters: radiusMeters.toString(),
    // The Solar API always returns the highest quality imagery available.
    // By default the API asks for HIGH quality, which means that HIGH quality isn't available,
    // but there is an existing MEDIUM or LOW quality, it won't return anything.
    // Here we ask for *at least* LOW quality, but if there's a higher quality available,
    // the Solar API will return us the highest quality available.
    required_quality: 'LOW',
  };
  console.log('GET dataLayers\n', args);
  const params = new URLSearchParams({ ...args, key: apiKey });
  // https://developers.google.com/maps/documentation/solar/reference/rest/v1/dataLayers/get
  return fetch(`https://solar.googleapis.com/v1/dataLayers:get?${params}`).then(
    async (response) => {
      const content = await response.json();
      if (response.status != 200) {
        console.error('getDataLayerUrls\n', content);
        throw content;
      }
      console.log('dataLayersResponse', content);
      return content;
    },
  );
}
solar.ts

注意：請參閱這份指南，瞭解如何使用 Google 地圖和 TypeScript。

TypeScript 中的欄位和資料類型都是"type"。在此範例中，我們會定義自訂類型，以儲存回應中感興趣的欄位，例如像素值和經緯度定界框。您可以視需要加入更多欄位。

export interface GeoTiff {
  width: number;
  height: number;
  rasters: Array<number>[];
  bounds: Bounds;
}
solar.ts

注意：請參閱這份指南，瞭解如何使用 Google 地圖和 TypeScript。

資料類型定義

支援的資料類型如下：

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;
  };
}
solar.ts

注意：請參閱這份指南，瞭解如何使用 Google 地圖和 TypeScript。

API 會以下列格式傳回網址：

https://solar.googleapis.com/v1/solar/geoTiff:get?id=HASHED_ID

這些網址可用於存取所要求資料的 GeoTIFF 檔案。

回應範例

要求會產生 JSON 回應，格式如下：

{
  "imageryDate": {
    "year": 2022,
    "month": 4,
    "day": 6
  },
  "imageryProcessedDate": {
    "year": 2023,
    "month": 8,
    "day": 4
  },
  "dsmUrl": "https://solar.googleapis.com/v1/geoTiff:get?id=6d654a0300e454f4c6db7fff24d7ab98-f51261151c9d4c7e055dd21ce57fa3b5",
  "rgbUrl": "https://solar.googleapis.com/v1/geoTiff:get?id=7c71f407a36c1cd051f5ada9c17a6cb8-4b1a9e2b489656febfb7676f205aea1d",
  "maskUrl": "https://solar.googleapis.com/v1/geoTiff:get?id=814470096c53cb221b524119e1e2700c-ac51cf76452dd6c2e843e6b11922ccc0",
  "annualFluxUrl": "https://solar.googleapis.com/v1/geoTiff:get?id=e044991d7f376dc23f9abe8d4efc909b-982983cd98d0572b9d62ca0a2db38eb3",
  "monthlyFluxUrl": "https://solar.googleapis.com/v1/geoTiff:get?id=9b4638db10d2d58560b9f1e9fb013551-dff565175a1e6861a7afb62ece41e218",
  "hourlyShadeUrls": [
    "https://solar.googleapis.com/v1/geoTiff:get?id=9aa96f4568d2561ad8b6db495b8f8582-da043a2c74541668b3d668e556451e31",
    "https://solar.googleapis.com/v1/geoTiff:get?id=125e26c35e4eb07d385a6868253fb1e3-54fa27bd2c5cd72b79e9f14cf0fa9899",
    ...
  ],
  "imageryQuality": "HIGH"
}

存取回應資料

需要額外驗證才能透過回應網址存取資料。如果您使用驗證金鑰，就必須將 API 金鑰附加至網址。如果您要使用 OAuth 驗證，就必須新增 OAuth 標頭。

API 金鑰

如要對回應中的網址提出要求，請在網址內附加 API 金鑰：

curl -X GET "https://solar.googleapis.com/v1/solar/geoTiff:get?id=fbde33e9cd16d5fd10d19a19dc580bc1-8614f599c5c264553f821cd034d5cf32&key=YOUR_API_KEY"

您也可以在瀏覽器的網址列貼上 cURL 要求中的網址，藉此提出 HTTP 要求。傳遞 API 金鑰可讓您享有更好的使用與分析功能，以及更精準地控管回應資料。

OAuth 憑證

如要對回應中的網址發出要求，請傳入帳單專案名稱和 OAuth 權杖：

curl -X GET \
-H 'X-Goog-User-Project: PROJECT_NUMBER_OR_ID' \
-H "Authorization: Bearer $TOKEN" \
"https://solar.googleapis.com/v1/solar/geoTiff:get?id=fbde33e9cd16d5fd10d19a19dc580bc1-8614f599c5c264553f821cd034d5cf32"
        

TypeScript

以下範例說明如何取得像素資料值 (數位圖片個別像素中儲存的資訊，包括色彩值和其他屬性)、計算 GeoTIFF 的經緯度，並儲存在 TypeScript 物件中。

針對這個範例，我們選擇允許類型檢查，以便降低類型錯誤、增加程式碼可靠性，以及更輕鬆地維護。

// npm install geotiff geotiff-geokeys-to-proj4 proj4

import * as geotiff from 'geotiff';
import * as geokeysToProj4 from 'geotiff-geokeys-to-proj4';
import proj4 from 'proj4';

/**
 * Downloads the pixel values for a Data Layer URL from the Solar API.
 *
 * @param  {string} url        URL from the Data Layers response.
 * @param  {string} apiKey     Google Cloud API key.
 * @return {Promise<GeoTiff>}  Pixel values with shape and lat/lon bounds.
 */
export async function downloadGeoTIFF(url: string, apiKey: string): Promise<GeoTiff> {
  console.log(`Downloading data layer: ${url}`);

  // Include your Google Cloud API key in the Data Layers URL.
  const solarUrl = url.includes('solar.googleapis.com') ? url + `&key=${apiKey}` : url;
  const response = await fetch(solarUrl);
  if (response.status != 200) {
    const error = await response.json();
    console.error(`downloadGeoTIFF failed: ${url}\n`, error);
    throw error;
  }

  // Get the GeoTIFF rasters, which are the pixel values for each band.
  const arrayBuffer = await response.arrayBuffer();
  const tiff = await geotiff.fromArrayBuffer(arrayBuffer);
  const image = await tiff.getImage();
  const rasters = await image.readRasters();

  // Reproject the bounding box into lat/lon coordinates.
  const geoKeys = image.getGeoKeys();
  const projObj = geokeysToProj4.toProj4(geoKeys);
  const projection = proj4(projObj.proj4, 'WGS84');
  const box = image.getBoundingBox();
  const sw = projection.forward({
    x: box[0] * projObj.coordinatesConversionParameters.x,
    y: box[1] * projObj.coordinatesConversionParameters.y,
  });
  const ne = projection.forward({
    x: box[2] * projObj.coordinatesConversionParameters.x,
    y: box[3] * projObj.coordinatesConversionParameters.y,
  });

  return {
    // Width and height of the data layer image in pixels.
    // Used to know the row and column since Javascript
    // stores the values as flat arrays.
    width: rasters.width,
    height: rasters.height,
    // Each raster reprents the pixel values of each band.
    // We convert them from `geotiff.TypedArray`s into plain
    // Javascript arrays to make them easier to process.
    rasters: [...Array(rasters.length).keys()].map((i) =>
      Array.from(rasters[i] as geotiff.TypedArray),
    ),
    // The bounding box as a lat/lon rectangle.
    bounds: {
      north: ne.y,
      south: sw.y,
      east: ne.x,
      west: sw.x,
    },
  };
}
solar.ts

注意：請參閱這份指南，瞭解如何使用 Google 地圖和 TypeScript。

除了 RGB 層以外，所有 TIFF 檔案會在圖片檢視器應用程式中顯示為空白圖片。如要查看下載的 TIFF 檔案，請將這些檔案匯入對應應用程式軟體，例如 QGIS。

如需這項要求和回應的完整規格，請參閱參考說明文件。

注意： 回應網址只有在初次要求後一小時後才會生效。如要存取超過這個時間範圍的網址，您必須再次傳送要求至 dataLayer 端點。