به Solar API در پلتفرم Google Maps مهاجرت کنید

توسعه‌دهندگان منطقه اقتصادی اروپا (EEA)

اگر آدرس صورتحساب شما در منطقه اقتصادی اروپا باشد، که از ۸ ژوئیه ۲۰۲۵ لازم‌الاجرا است، شرایط خدمات پلتفرم نقشه‌های گوگل (EEA) برای استفاده شما از خدمات اعمال خواهد شد. اطلاعات بیشتر . علاوه بر این، محتوای خاصی از API خورشیدی دیگر بازگردانده نخواهد شد. اطلاعات بیشتر .

برای انتقال از Google Earth Engine Solar API به Google Maps Platform Solar API:

1. API خورشیدی پلتفرم نقشه‌های گوگل را در پروژه ابری خود فعال کنید.
2. یک کلید جدید ایجاد کنید و آن را به GMP Solar API محدود کنید.
3. کد خود را با استفاده از دستورالعمل‌های گام به گام زیر به‌روزرسانی کنید.

مقایسه‌ی پهلو به پهلو

	API خورشیدی (جدید)	رابط برنامه‌نویسی کاربردی موتور زمین برای سیستم خورشیدی (منسوخ شده)
وضعیت راه‌اندازی	راه‌اندازی شد	پایلوت (منسوخ شده)
دسترسی
مکانیسم	حساب Google Cloud از طریق کنسول Cloud، با فعال کردن Solar API و مدیریت API از طریق بخش Google Maps Platform	حساب Google Cloud از طریق کنسول Cloud، با فعال کردن Earth Engine Solar API
سازمان بهداشت جهانی	عمومی	دسترسی کنترل‌شده
سطح	خود تأمین‌شده	دسترسی به دفترچه راهنمای پروژه ابری
احراز هویت	کلید API و OAuth	کلید API
قیمت‌گذاری
استراتژی	پرداخت به ازای هر بار استفاده	۱۰۰٪ تخفیف
لایه بندی	به ازای هر ۱۰۰۰ درخواست، با کاهش قیمت بر اساس حجم	–
نقاط پایانی	قیمت‌های متفاوت برای هر نقطه پایانی	–
ابر
نظارت	نظارت بر فضای ابری تحت عنوان «پلتفرم نقشه‌های گوگل»	نظارت بر ابر در بخش «APIها و خدمات»
سهمیه	QPM (تعداد درخواست در دقیقه) و QPH (تعداد درخواست در ساعت)	سالانه
ثبت وقایع	ثبت وقایع ابری (اختیاری)	ثبت وقایع ابری (اختیاری)
صورتحساب	حساب پرداخت ابری	-
پشتیبانی	پشتیبانی کامل از پلتفرم نقشه‌های گوگل با SLO/SLA	محدود، از طریق ایمیل
رابط برنامه‌نویسی کاربردی
نام میزبان	https://solar.googleapis.com/v1/ (REST)	https://earthenginesolar.googleapis.com/v1/ (REST)
روش‌ها	buildingInsights:findClosest dataLayers:get	buildings:findClosest solar.get
پاسخ	هیچ تغییری نسبت به نسخه آزمایشی وجود ندارد	–
solarInfo	شعاع ≤100 متر	شعاع ≤100 متر
پوشش
مساحت	جهانی	جهانی
کیفیت داده‌ها	HIGH / MEDIUM	HIGH / MEDIUM
نوع ساختمان	هر ساختمانی که به یک آدرس و در محدوده پوشش تصاویر Solar API نگاشت شده باشد	هر ساختمانی که به یک آدرس و در محدوده پوشش تصاویر Solar API نگاشت شده باشد
شرایط خدمات
شرایط خدمات	شرایط پلتفرم نقشه گوگل	اصطلاحات موتور گوگل ارث

گام به گام

پروژه گوگل کلود خود را راه‌اندازی کنید

دستورالعمل‌های اینجا: پروژه Google Cloud خود را راه‌اندازی کنید .

احتیاط: در بخش «فعال کردن API» از «راه‌اندازی پروژه Google Cloud» توقف کنید.

فقط نقش‌های خاصی می‌توانند یک پروژه ابری ایجاد کنند؛ اگر نمی‌توانید پروژه‌ای ایجاد کنید، با مدیر سازمان خود تماس بگیرید.

همچنین می‌توانید از یک پروژه ابری موجود استفاده کنید. برای کسب اطلاعات بیشتر، به شروع به کار با پلتفرم نقشه‌های گوگل مراجعه کنید.

حساب صورتحساب خود را تنظیم کنید

دستورالعمل‌های اینجا: نحوه مدیریت حساب صورتحساب شما .

شما می‌توانید از یک پروژه ابری موجود با یک حساب پرداخت موجود استفاده کنید.

یک کلید API دریافت کنید یا از توکن OAuth استفاده کنید

پس از راه‌اندازی پروژه Google Cloud خود، باید کلید API خود را برای استفاده از Solar API همانطور که در بخش «استفاده از کلیدهای API» توضیح داده شده است، ایجاد و ایمن کنید. یا می‌توانید یک توکن OAuth همانطور که در بخش «استفاده از OAuth» توضیح داده شده است، ایجاد کنید.

استفاده از API خورشیدی

• درخواست‌های GET را به نقاط انتهایی جدید ارسال کنید: https://solar.googleapis.com
• توجه داشته باشید که نام برخی از متدهای API تغییر کرده است:
  • buildings:findClosest → buildingInsights:findClosest
  • solarinfo:get → dataLayers:get

آزمایش سریع : قبل از بارگذاری URL در مرورگر خود، از کلید API ذخیره شده از مرحله قبل استفاده کنید و YOUR_API_KEY در مثال زیر جایگزین کنید:

https://solar.googleapis.com/v1/dataLayers:get?location.latitude=37.2746464&location.longitude=-121.7530949&radius_meters=10&key=YOUR_API_KEY

پاسخ به انتشار اولیه پیش‌نمایش

برای نسخه پیش‌نمایش اصلی در ۹ مه ۲۰۲۳، آدرس‌های اینترنتی (URL) در پاسخ به شکل زیر هستند:

https://earthengine.googleapis.com/v1alpha/projects/sunroof-api/thumbnails/THUMBNAIL_ID:getPixels

قطعه کد زیر یک نمونه پاسخ است:

{
  "imageryDate": {
    "year": 2015,
    "month": 8,
    "day": 8
  },
  "imageryProcessedDate": {
    "year": 2021,
    "month": 2,
    "day": 15
  },
  "dsmUrl": "https://earthengine.googleapis.com/v1alpha/projects/geo-solar-api/thumbnails/fbde33e9cd16d5fd10d19a19dc580bc1-8614f599c5c264553f821cd034d5cf32:getPixels",
  "rgbUrl": "https://earthengine.googleapis.com/v1alpha/projects/geo-solar-api/thumbnails/91ed3551f2d0abee20af35e07bd0c927-c96c59e80cf1fc1dc86cf59fc8ec86ba:getPixels",
  "maskUrl": "https://earthengine.googleapis.com/v1alpha/projects/geo-solar-api/thumbnails/e4051553dba6870c03d855ae82c30b7e-7cc8ae6ce7c73f219e3c1924e5c17fc6:getPixels",
  "annualFluxUrl": "https://earthengine.googleapis.com/v1alpha/projects/geo-solar-api/thumbnails/9b0f87f49d778a65c9e27ff936e6dbba-b90be2fe80d25abd4c9e8c4dc809f763:getPixels",
  "monthlyFluxUrl": "https://earthengine.googleapis.com/v1alpha/projects/geo-solar-api/thumbnails/90e7cca77402f14809e349937f0a0be8-94fafeb4ef42d72f1b3c0652a1cb5518:getPixels",
  "hourlyShadeUrls": [
    "https://earthengine.googleapis.com/v1alpha/projects/geo-solar-api/thumbnails/dcd276e4782aef4ff1b230b781736d37-e193b231ce57a03449afc3e21cf6783b:getPixels",
    ...
  ]
  }

برای ارسال درخواست به یک URL در پاسخ، کل URL را در درخواست قرار دهید.

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

یک برنامه بنویسید که از هر دو فرمت پاسخ پشتیبانی کند

اکنون می‌توانید برنامه‌ای بنویسید که هم قالب‌های پیش‌نمایش اصلی و هم قالب‌های پاسخ فعلی را مدیریت کند.

تفاوت اصلی بین این دو پاسخ، به غیر از خود URL، این است که شما باید یک کلید API به درخواستی که از قالب پاسخ جدید به URLها دسترسی پیدا می‌کند، ارسال کنید. اگر کلید API را حذف کنید، درخواست با شکست مواجه می‌شود.

توجه: کلید API را به آدرس اینترنتی با فرمت اصلی، یعنی آدرسی که از دامنه https://earthengine.googleapis.com استفاده می‌کند ، ارسال نکنید . ارسال کلید API به آن آدرس اینترنتی باعث خطا می‌شود.

برای مثال، می‌توانید کد زیر را به برنامه خود اضافه کنید تا URL را بررسی کرده و هر نسخه را به درستی مدیریت کند:

جاوا اسکریپت

/**
* Function to examine a response URL and to append the API key to the
* URL if it is in the new format.
*/
function prepareGetGeoTiffUrl(geoTiffUrl, apiKey) {
  if (geoTiffUrl.match("solar.googleapis.com")) {
    let url = new URL(geoTiffUrl);
    url.searchParams.set('apiKey', apiKey);
    return url.toString();
  }
  return geoTiffUrl;
}

پایتون

# Functions to examine a response URL and to append the API key to the
# URL if it is in the new format.

def add_api_key_to_url(base_url: str, api_key: str) -> str:
  '''Formats URL that currently lacks an API key to use the one provided.'''
  return base_url + "&key=" +api_key;

def prepare_geo_tiff_url(base_url: str, api_key: str) -> str:
  '''Prepares URL from GetDataLayers depending on API being called.
    If the geoTIFF url from GetDataLayers is for the solar API GetGeoTiff
      endpoint, append the API key. Otherwise return the URL as is.
  '''
  if re.search("solar.googleapis.com", geo_tiff_url):
    return add_api_key_to_url(geo_tiff_url, api_key)
  return geo_tiff_url

جاوا

/** Adds API key to a URL. */
private String addApiKeyToUrl(String geoTiffUrl, String apiKey) {
  return geoTiffUrl + "&key=" + apiKey;
}

/**
* Function to examine a response URL and to append the API key to the
* URL if it is in the new format.
*/
private String prepareGetGeoTiffUrl(String geoTiffUrl, String apiKey) {
  Pattern pattern = Pattern.compile("solar.googleapis.com");
  Matcher matcher = pattern.matcher(geoTiffUrl);
  if (matcher.find()) {
    return addApiKeyToUrl(geoTiffUrl, apiKey);
  } else {
    return geoTiffUrl;
  }
}

مانیتور

سطح پروژه	سطح حساب صورتحساب

نکات مفید و کاربردی

• سهمیه: مصرفی که قابل افزایش است (به جای مصرف سالانه که از بین خواهد رفت)
  • سهمیه فعلی که به QPM تغییر خواهد کرد
  • بهترین شیوه‌ها: سهمیه سمت کلاینت را تعیین کنید و هشدار ارسال کنید
• قیمت گذاری:
  • پرداخت به ازای هر بار استفاده
  • پاسخ‌های ۴۰۴ NOT_FOUND، زمانی که مکان در محدوده پوشش نباشد، صورتحسابی برای آن صادر نمی‌شود اما جزو سهمیه محاسبه می‌شود.
• شرایط استفاده عمومی: شرایط خدمات پلتفرم نقشه‌های گوگل