**European Economic Area (EEA) developers**

> [!NOTE]
> If your billing address is in the European Economic Area, effective on 8 July 2025, the [Google
> Maps Platform EEA Terms of Service](https://cloud.google.com/terms/maps-platform/eea) will apply to your use of the Services. [Learn more](https://developers.google.com/maps/comms/eea/faq.md.txt). In addition, certain content from the Solar API will no longer be returned. [Learn more](https://developers.google.com/maps/comms/eea/solar.md.txt).

To move from Google Earth Engine Solar API to the [Google Maps Platform](https://developers.google.com/maps)
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](https://developers.google.com/maps/documentation/solar/migration.md.txt#step_by_step) instructions below.

## Side-by-side comparison

|   | Solar API (new) ![Houses with a sun](https://developers.google.com/static/maps/documentation/solar/images/solar-icon.png) | Earth Engine Solar API (deprecated) ![EE icon](https://developers.google.com/static/maps/documentation/solar/images/ee-icon.png) |
|---|---|---|
| Launch status | Launched | Pilot (deprecated) |
| 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 |
| Strategy | [Pay-as-you-go](https://developers.google.com/maps/documentation/solar/usage-and-billing.md.txt) | 100% discount |
| Tiering | Per 1000 queries, with decreasing pricing based on volume | -- |
| Endpoints | Different, per-endpoint prices | -- |
| Monitoring | [Cloud Monitoring](https://cloud.google.com/monitoring) under "Google Maps Platform" | [Cloud Monitoring](https://cloud.google.com/monitoring) under "APIs and Services" |
| Quota | QPM (query per minute) and QPH (query per hour) | Annual |
| Logging | [Cloud Logging](https://cloud.google.com/logging) (optional) | [Cloud Logging](https://cloud.google.com/logging) (optional) |
| Billing | Cloud Billing account | - |
| Support | Full Google Maps Platform support with SLO/SLA | Limited, by email |
| 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 |
| 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 |
| TOS | [Google Maps Platform terms](https://cloud.google.com/maps-platform/terms) | [Google Earth Engine terms](https://earthengine.google.com/terms/) |

## Step by step

### Set up your Google Cloud project

Instructions here: [Set up your Google Cloud
project](https://developers.google.com/maps/documentation/solar/cloud-setup).

> [!CAUTION]
> **Caution:** Stop at the "Enable API" part of the "Set up your Google Cloud project".

Only certain [roles](https://cloud.google.com/iam/docs/understanding-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](https://developers.google.com/maps/get-started).

### Set up your Billing Account

Instructions here: [How to manage Your billing
Account](https://cloud.google.com/billing/docs/how-to/manage-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](https://developers.google.com/maps/documentation/solar/get-api-key). Or, you can create an OAuth token
as described in [Use OAuth](https://developers.google.com/maps/documentation/solar/oauth-token).

### 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:

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

The following snippet is an example response:

```json
{
  "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](https://developers.google.com/maps/documentation/solar/reference/rest/v1/dataLayers/get).

#### 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.

> [!NOTE]
> **Note:** **Do not pass** an API key to a URL in the original format, meaning one using the `https://earthengine.googleapis.com` domain. Passing an API key to that URL causes an error.

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

### JavaScript

```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

```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

```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 <br /> |
| ![Cloud Monitoring](https://developers.google.com/static/maps/documentation/solar/images/cloud-monitor.png "gmp monitoring") | ![Cloud Billing](https://developers.google.com/static/maps/documentation/solar/images/tutorial-billing-reports-tour.png "cloud billing") |

### Good-to-know tips

- Quota: consumption that can scale (rather than annual which will disappear)
  - [Current
    quota](https://developers.google.com/maps/documentation/solar/usage-and-billing#other-usage-limits) 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](https://cloud.google.com/maps-platform/terms)