Migrate to the Solar API on Google Maps Platform

To move from Google Earth Engine Solar API to the Google Maps Platform Solar API:

  1. Enable the Google Maps Platform Solar API in your cloud project.
  2. Create a new key and restrict it to GMP Solar API.
  3. Update your code using the step-by-step instructions below.

Side-by-side comparison

Solar API (new) Houses with a sun Earth Engine Solar API (deprecated) EE icon
Launch status Launched Pilot (deprecated)
Access
Mechanism Google Cloud account via the Cloud console, by enabling the Solar API and managing the API via the Google Maps Platform section Google Cloud account via the Cloud console, by enabling the Earth Engine Solar API
Who Public Access-controlled
Level Self-provisioned Cloud project manual access
Authentication API Key and OAuth API Key
Pricing
Strategy Pay-as-you-go 100% discount
Tiering Per 1000 queries, with decreasing pricing based on volume –
Endpoints Different, per-endpoint prices –
Cloud
Monitoring Cloud Monitoring under "Google Maps Platform" Cloud Monitoring under "APIs and Services"
Quota QPM (query per minute) and QPH (query per hour) Annual
Logging Cloud Logging (optional) Cloud Logging (optional)
Billing Cloud Billing account -
Support Full Google Maps Platform support with SLO/SLA Limited, by email
API
Hostname https://solar.googleapis.com/v1/ (REST) https://earthenginesolar.googleapis.com/v1/ (REST)
Methods
  • buildingInsights:findClosest
  • dataLayers:get
  • buildings:findClosest
  • solar.get
Response No changes compared to pilot –
solarInfo ≤100m radius ≤100m radius
Coverage
Area Global Global
Data quality HIGH/MEDIUM HIGH/MEDIUM
Building type Any building that is mapped to an address AND within Solar API imagery coverage Any building that is mapped to an address AND within Solar API imagery coverage
Terms of Service
TOS Google Maps Platform terms Google Earth Engine terms

Step by step

Set up your Google Cloud project

Instructions here: Set up your Google Cloud project.

Only certain roles can create a Cloud project; if you can't create a project, reach out to your organization's administrator.

You can also use an existing Cloud project. To learn more, see Getting started with Google Maps Platform.

Set up your Billing Account

Instructions here: How to manage Your billing Account.

You can use an existing Cloud project with an existing billing account.

Get an API Key or use OAuth token

After setting up your Google Cloud project, you must create and secure your API Key to use the Solar API as described in Use API Keys. Or, you can create an OAuth token as described in Use OAuth.

Use the Solar API

  • Make GET requests to the new endpoints : https://solar.googleapis.com
  • Note that some API method names have changed:
    • buildings:findClosest → buildingInsights:findClosest
    • solarinfo:get → dataLayers:get

Quick trial: Use the saved API key from prior step and replace YOUR_API_KEY in the example query below, before loading the URL in your browser:

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

Response for the original Preview release

For the original Preview release on May 9, 2023, the URLs in the response are in the form:

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

The following snippet is an example response:

{
  "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",
    ...
  ]
  }

To make a request to a URL in the response, include the entire URL in the request.

The full specification of this request and response is in the reference documentation.

Write an app to support both response formats

You can now write an app that handles both the original Preview and current response formats.

The main difference between the two responses, other than the actual URL itself, is that you must pass an API key to a request that accesses the URLs from the new response format. If you omit the API key, the request fails.

For example, you can add the following code to your app to examine the URL and handle each version correctly:

JavaScript

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

Python

# 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

Java

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

Monitor

Project level Billing Account level

Cloud Monitoring Cloud Billing

Good-to-know tips

  • Quota: consumption that can scale (rather than annual which will disappear)
    • Current quota which will be changed to QPM
    • Best practices: set client-side quota and send alerts
  • Pricing:
    • Pay-as-you-go
    • 404 NOT_FOUND responses, when location is not in coverage range, will not be billed but will count against quota
  • General usage Terms: Google Maps Platform Terms of Service