نقطه پایانی dataLayers اطلاعات خورشیدی دقیقی را برای منطقهای اطراف یک مکان مشخص ارائه میدهد. این نقطه پایانی ۱۷ فایل TIFF قابل دانلود را برمیگرداند، از جمله:
- مدل سطح دیجیتال (DSM)
- لایه ترکیبی RGB (تصاویر هوایی یا ماهوارهای)
- یک لایه ماسک که مرزهای تحلیل را مشخص میکند
- شار خورشیدی سالانه یا بازده سالانه یک سطح معین
- شار خورشیدی ماهانه یا بازده ماهانه یک سطح معین
- سایه ساعتی (۲۴ ساعته)
برای اطلاعات بیشتر در مورد نحوه تعریف شار توسط Solar API، به Solar API Concepts مراجعه کنید.
درباره درخواستهای لایههای داده
مثال زیر آدرس اینترنتی (URL) یک درخواست REST به متد dataLayers را نشان میدهد:
https://solar.googleapis.com/v1/dataLayers:get?parameters
پارامترهای URL درخواست خود را که موارد زیر را مشخص میکنند، وارد کنید:
- مختصات طول و عرض جغرافیایی محل مورد نظر
- شعاع ناحیه اطراف محل
- زیرمجموعهای از دادهها که باید بازگردانده شوند (DSM، RGB، ماسک، شار سالانه یا شار ماهانه)
- حداقل کیفیت مجاز در نتایج
- حداقل مقیاس داده برای بازگشت، بر حسب متر بر پیکسل
درخواست لایههای داده نمونه
مثال زیر تمام اطلاعات بینش ساختمان را در شعاع ۱۰۰ متری برای موقعیت مکانی در مختصات عرض جغرافیایی = ۳۷.۴۴۵۰ و طول جغرافیایی = -۱۲۲.۱۳۹۰ درخواست میکند:
کلید API
برای ارسال درخواست به URL در پاسخ، کلید API خود را به 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"
همچنین میتوانید با قرار دادن URL موجود در درخواست cURL در نوار آدرس مرورگر خود، درخواستهای 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/dataLayers:get?location.latitude=37.4450&location.longitude=-122.1390&radius_meters=100&required_quality=HIGH&exactQualityRequired=true"
تایپ اسکریپت
برای ارسال درخواست به URL در پاسخ، کلید 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 BASE quality, it won't return anything. // Here we ask for *at least* BASE quality, but if there's a higher quality available, // the Solar API will return us the highest quality available. required_quality: 'BASE', }; 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; }, ); }
فیلدها و نوع داده در TypeScript یک "نوع" است. در این مثال، ما یک نوع سفارشی برای ذخیره فیلدهای مورد نظر در پاسخ، مانند مقادیر پیکسل و کادر مرزی lat/long تعریف میکنیم. شما میتوانید فیلدهای بیشتری را به دلخواه اضافه کنید.
export interface GeoTiff { width: number; height: number; rasters: Array<number>[]; bounds: Bounds; }
تعاریف نوع داده
انواع داده زیر پشتیبانی میشوند:
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; }; }
این API آدرسهای اینترنتی (URL) را با فرمت زیر برمیگرداند:
https://solar.googleapis.com/v1/solar/geoTiff:get?id=HASHED_ID
از این URLها میتوان برای دسترسی به فایلهای 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=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" }
دسترسی به دادههای پاسخ
دسترسی به دادهها از طریق URLهای پاسخ نیاز به احراز هویت اضافی دارد. اگر از کلید احراز هویت استفاده میکنید، باید کلید API خود را به URL اضافه کنید. اگر از احراز هویت OAuth استفاده میکنید، باید هدرهای OAuth را اضافه کنید.
کلید API
برای ارسال درخواست به URL در پاسخ، کلید API خود را به URL اضافه کنید:
curl -X GET "https://solar.googleapis.com/v1/solar/geoTiff:get?id=fbde33e9cd16d5fd10d19a19dc580bc1-8614f599c5c264553f821cd034d5cf32&key=YOUR_API_KEY"
همچنین میتوانید با قرار دادن URL موجود در درخواست cURL در نوار آدرس مرورگر خود، درخواستهای HTTP ایجاد کنید. ارسال کلید API، قابلیتهای استفاده و تجزیه و تحلیل بهتر و کنترل دسترسی بهتری به دادههای پاسخ را برای شما فراهم میکند.
توکن OAuth
برای ارسال درخواست به URL در پاسخ، نام پروژه صورتحساب و توکن 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"
تایپ اسکریپت
مثال زیر نحوه دریافت مقادیر دادههای پیکسلی (اطلاعات ذخیره شده در پیکسلهای منفرد یک تصویر دیجیتال، شامل مقادیر رنگ و سایر ویژگیها)، محاسبه طول و عرض جغرافیایی از 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, }, }; }
به استثنای لایه RGB، تمام فایلهای TIFF در برنامههای نمایش تصویر به صورت تصاویر خالی نمایش داده میشوند. برای مشاهده فایلهای TIFF دانلود شده، آنها را به یک نرمافزار نقشهبرداری مانند QGIS وارد کنید.
مشخصات کامل این درخواست و پاسخ در مستندات مرجع آمده است.