درخواست لایه های داده را بدهید

نقطه پایانی dataLayers اطلاعات دقیق خورشیدی را برای منطقه اطراف یک مکان مشخص ارائه می دهد. نقطه پایانی 17 فایل TIFF قابل دانلود را برمی گرداند، از جمله:

  • مدل سطح دیجیتال (DSM)
  • لایه ترکیبی RGB (تصاویر هوایی)
  • یک لایه ماسک که مرزهای تجزیه و تحلیل را مشخص می کند
  • شار سالانه خورشیدی، یا بازده سالانه یک سطح معین
  • شار ماهانه خورشیدی، یا بازده ماهانه یک سطح معین
  • سایه ساعتی (24 ساعت)

برای اطلاعات بیشتر در مورد نحوه تعریف شار توسط Solar API، به مفاهیم Solar API مراجعه کنید.

درباره درخواست های لایه های داده

مثال زیر URL درخواست REST به متد dataLayers را نشان می دهد:

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

پارامترهای URL درخواست خود را وارد کنید که موارد زیر را مشخص می کند:

  • مختصات طول و عرض جغرافیایی مکان
  • شعاع منطقه اطراف محل
  • زیر مجموعه داده هایی که باید برگردانده شوند (DSM، RGB، ماسک، شار سالانه یا شار ماهانه)
  • حداقل کیفیت مجاز در نتایج
  • حداقل مقیاس داده برای بازگشت، بر حسب متر بر پیکسل

نمونه درخواست لایه های داده

مثال زیر تمام اطلاعات بینش ساختمان را در شعاع 100 متر برای مکان در مختصات عرض جغرافیایی = 37.4450 و طول جغرافیایی = 122.1390 ​​درخواست می کند:

کلید 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 در نوار 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/dataLayers:get?location.latitude=37.4450&location.longitude=-122.1390&radius_meters=100&required_quality=HIGH&exactQualityRequired=true"

TypeScript

برای درخواست از 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 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

فیلدها و نوع داده ها یک "نوع" در TypeScript است. در این مثال، ما یک نوع سفارشی برای ذخیره فیلدهای مورد علاقه در پاسخ، مانند مقادیر پیکسل و کادر lat/long bounding تعریف می کنیم. شما می توانید فیلدهای بیشتری را به دلخواه اضافه کنید.

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

تعاریف نوع داده

انواع داده های زیر پشتیبانی می شوند:

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 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 در نوار URL مرورگر خود، درخواست های 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"

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

به استثنای لایه RGB، همه فایل های TIFF به صورت تصاویر خالی در برنامه های نمایشگر تصویر نمایش داده می شوند. برای مشاهده فایل های TIFF دانلود شده، آنها را در یک نرم افزار کاربردی نقشه برداری مانند QGIS وارد کنید.

مشخصات کامل این درخواست و پاسخ در مستندات مرجع موجود است.

بعدی
درباره فایل های GeoTIFF