Thực hiện yêu cầu lớp dữ liệu

Điểm cuối dataLayers cung cấp thông tin chi tiết về năng lượng mặt trời cho khu vực xung quanh một vị trí cụ thể. Điểm cuối trả về 17 tệp TIFF có thể tải xuống, bao gồm:

  • Mô hình bề mặt kỹ thuật số (DSM)
  • Lớp tổng hợp RGB (hình ảnh trên không)
  • Một lớp mặt nạ xác định các ranh giới của quá trình phân tích
  • Lượng bức xạ mặt trời hằng năm hoặc năng suất hằng năm của một bề mặt nhất định
  • Thông lượng mặt trời hằng tháng, hoặc sản lượng hằng tháng của một bề mặt cụ thể
  • Màu sắc theo giờ (24 giờ)

Để biết thêm thông tin về cách Solar API xác định luồng, hãy xem phần Khái niệm về Solar API.

Giới thiệu về yêu cầu lớp dữ liệu

Ví dụ sau đây cho thấy URL của một yêu cầu REST đến phương thức dataLayers:

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

Thêm các thông số URL yêu cầu chỉ rõ những thông tin sau:

  • Vĩ độ và kinh độ của vị trí
  • Bán kính của khu vực xung quanh vị trí
  • Tập hợp con dữ liệu cần trả về (DSM, RGB, mặt nạ, thông lượng hằng năm hoặc hằng tháng thông lượng)
  • Chất lượng tối thiểu được phép trong kết quả
  • Tỷ lệ dữ liệu tối thiểu cần trả về, tính bằng mét trên mỗi pixel

Ví dụ về yêu cầu lớp dữ liệu

Ví dụ sau đây yêu cầu tất cả thông tin chi tiết về toà nhà trong 100 mét bán kính của vị trí tại toạ độ vĩ độ = 37,4450 và kinh độ = -122.1390:

Khóa API

Để tạo yêu cầu tới URL trong phản hồi, hãy thêm khoá API vào URL:

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"

Bạn cũng có thể tạo yêu cầu HTTP bằng cách dán URL trong yêu cầu cURL vào thanh URL của trình duyệt. Sau khi chuyển khoá API, bạn có thể sử dụng và phân tích hiệu quả hơn, cũng như kiểm soát tốt hơn quyền truy cập vào dữ liệu phản hồi.

Mã thông báo OAuth

Lưu ý: Định dạng này chỉ dành cho môi trường thử nghiệm. Để biết thêm thông tin, hãy xem bài viết Sử dụng OAuth.

Để gửi yêu cầu đến URL trong phản hồi, hãy truyền tên dự án thanh toán và mã thông báo OAuth của bạn:

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

Để gửi yêu cầu tới URL trong phản hồi, hãy thêm API của bạn hoặc mã thông báo OAuth trong yêu cầu. Ví dụ sau đây sử dụng một API khoá:

/**
 * 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

Trường và loại dữ liệu là một "type" trong TypeScript. Trong ví dụ này, chúng ta xác định một loại tuỳ chỉnh để lưu trữ các trường quan tâm trong phản hồi, chẳng hạn như giá trị pixel và hộp giới hạn vĩ độ/kinh độ. Bạn có thể thêm các trường khác nếu muốn.

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

Định nghĩa loại dữ liệu

Các loại dữ liệu sau được hỗ trợ:

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

API trả về URL theo định dạng sau:

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

Các URL này có thể được sử dụng để truy cập vào các tệp GeoTIFF chứa dữ liệu được yêu cầu.

Ví dụ về phản hồi

Yêu cầu tạo ra phản hồi JSON dưới dạng:

{
  "imageryDate": {
    "year": 2022,
    "month": 4,
    "day": 6
  },
  "imageryProcessedDate": {
    "year": 2023,
    "month": 8,
    "day": 4
  },
  "dsmUrl": "https://solar.googleapis.com/v1/geoTiff:get?id=MmQyMzI0NTMyZDc3YjBjNmQ3OTgyM2ZhNzMyNzk5NjItN2ZjODJlOThkNmQ5ZDdmZDFlNWU3MDY4YWFlMWU0ZGQ6UkdCOkhJR0g=",
  "rgbUrl": "https://solar.googleapis.com/v1/geoTiff:get?id=NzQwNGQ0NmUyMzAzYWRiNmMxNzMwZTJhN2IxMTc4NDctOTI5YTNkZTlkM2MzYjRiNjE4MGNkODVmNjNiNDhkMzE6UkdCOkhJR0g=",
  "maskUrl": "https://solar.googleapis.com/v1/geoTiff:get?id=ZTk1YTBlZmY5Y2FhMThlNWYzMWEzZGZhYzEzMGQzOTAtM2Q4NmUyMmM5ZThjZmE0YjhhZWMwN2UzYzdmYmQ3ZjI6TUFTSzpISUdI",
  "annualFluxUrl": "https://solar.googleapis.com/v1/geoTiff:get?id=OTE0OWIxZDM3NmNlYjkzMWY2YjQyYjY5Y2RkYzNiOTAtZjU5YTVjZGQ3MzE3ZTQ4NTNmN2M4ZmY2MWZlZGZkMzg6QU5OVUFMX0ZMVVg6SElHSA==",
  "monthlyFluxUrl": "https://solar.googleapis.com/v1/geoTiff:get?id=Y2NhOGRhOWI2MjVmYmNiZTY3Njk4Yjk0MGJhNTk1NDUtY2MyYTI4NDJmN2Q5YTI0MmY2NDQyZGUwZWJkMWQ0ZDg6TU9OVEhMWV9GTFVYOkhJR0g=",
  "hourlyShadeUrls": [
    "https://solar.googleapis.com/v1/geoTiff:get?id=OWFhOTZmNDU2OGQyNTYxYWQ4YjZkYjQ5NWI4Zjg1ODItZGEwNDNhMmM3NDU0MTY2OGIzZDY2OGU1NTY0NTFlMzE6TU9OVEhMWV9GTFVYOkhJR0g=",
    "https://solar.googleapis.com/v1/geoTiff:get?id=MTI1ZTI2YzM1ZTRlYjA3ZDM4NWE2ODY4MjUzZmIxZTMtNTRmYTI3YmQyYzVjZDcyYjc5ZTlmMTRjZjBmYTk4OTk6TU9OVEhMWV9GTFVYOkhJR0g=",
    ...
  ],
  "imageryQuality": "HIGH"
}

Truy cập dữ liệu phản hồi

Bạn cần xác thực thêm để truy cập dữ liệu qua URL phản hồi. Nếu bạn sử dụng khoá xác thực, bạn phải thêm khoá API vào URL. Nếu bạn sử dụng OAuth xác thực, bạn phải thêm tiêu đề OAuth.

Khóa API

Để tạo yêu cầu tới URL trong phản hồi, hãy thêm khoá API vào URL:

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

Bạn cũng có thể tạo yêu cầu HTTP bằng cách dán URL trong yêu cầu cURL vào thanh URL của trình duyệt. Sau khi chuyển khoá API, bạn có thể sử dụng và phân tích hiệu quả hơn, cũng như kiểm soát tốt hơn quyền truy cập vào dữ liệu phản hồi.

Mã thông báo OAuth

Để gửi yêu cầu tới URL trong phản hồi, hãy nhập tên dự án thanh toán và mã thông báo OAuth của bạn:

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

Ví dụ sau đây trình bày cách nhận giá trị dữ liệu pixel ( thông tin được lưu trữ trong từng pixel riêng lẻ của một hình ảnh kỹ thuật số, bao gồm và các thuộc tính khác), tính vĩ độ và kinh độ từ GeoTIFF và lưu trữ kinh độ đó trong đối tượng TypeScript.

Đối với ví dụ cụ thể này, chúng tôi đã chọn cho phép kiểm tra kiểu, điều này giảm lỗi loại, tăng độ tin cậy cho mã và giúp bạn dễ dàng duy trì.

// 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

Ngoại trừ lớp RGB, tất cả các tệp TIFF sẽ hiển thị dưới dạng hình ảnh trống trong các ứng dụng trình xem hình ảnh. Để xem các tệp TIFF đã tải xuống, hãy nhập chúng vào phần mềm ứng dụng lập bản đồ, chẳng hạn như QGIS.

Thông số đầy đủ của yêu cầu và phản hồi này có trong tài liệu tham khảo .

Tiếp
Giới thiệu về tệp GeoTIFF