Đ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
- Thông lượng mặt trời hằng năm, hoặc sản lượng 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 API năng lượng mặt trời xác định thông lượng, hãy xem Khái niệm về API năng lượng mặt trời.
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 dataLayers
phương thức:
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 cho phép trong các 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ể gửi 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. Việc chuyển khoá API giúp bạn có khả năng sử dụng và phân tích tốt hơn, cũng như kiểm soát quyền truy cập tốt hơn 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 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 -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; }, ); }
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ể bao gồm nhiều trường hơn nếu muốn.
export interface GeoTiff { width: number; height: number; rasters: Array<number>[]; bounds: Bounds; }
Định nghĩa kiểu 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; }; }
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 vào dữ liệu phản hồi
Việc truy cập dữ liệu qua URL phản hồi yêu cầu xác thực bổ sung. 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ể gửi 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. Việc chuyển khoá API giúp bạn có khả năng sử dụng và phân tích tốt hơn, cũng như kiểm soát quyền truy cập tốt hơn 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, }, }; }
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 .