Make a data layers request

The dataLayers endpoint provides detailed solar information for a region surrounding a specified location. The endpoint returns 17 downloadable TIFF files, including:

  • Digital surface model (DSM)
  • RGB composite layer (aerial imagery)
  • A mask layer that identifies the boundaries of the analysis
  • Annual solar flux, or the annual yield of a given surface
  • Monthly solar flux, or the monthly yield of a given surface
  • Hourly shade (24 hours)

For more information about how the Solar API defines flux, see Solar API Concepts.

About data layers requests

The following example shows the URL of a REST request to the dataLayers method:

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

Include your request URL parameters that specify the following:

  • Latitude and longitude coordinates of the location
  • The radius of the region surrounding the location
  • The subset of the data to return (DSM, RGB, mask, annual flux, or monthly flux)
  • The minimum quality allowed in the results
  • The minimum scale of data to return, in meters per pixels

Example data layers request

The following example requests all building insights information in a 100 meter radius for the location at the coordinates of latitude = 37.4450 and longitude = -122.1390:

API key

To make a request to the URL in the response, append your API key to the 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&pixelSizeMeters=0.5&key=YOUR_API_KEY"

You can also make HTTP requests by pasting the URL in the cURL request into your browser's URL bar. Passing the API key provides you with better usage and analytics capabilities and better access control to the response data.

OAuth token

Note: This format is for a testing environment only. For more information, see Use OAuth.

To make a request to the URL in the response, pass in your billing project name and your OAuth token:

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"
        

The API returns URLs in the following format:

https://solar.googleapis.com/v1/solar/geoTiff:get?id=HASHED_ID

Example response

The request produces a JSON response in the form:

{
  "imageryDate": {
    "year": 2019,
    "month": 7,
    "day": 9
  },
  "imageryProcessedDate": {
    "year": 2022,
    "month": 3,
    "day": 21
  },
  "dsmUrl": "https://solar.googleapis.com/v1/geoTiff:get?id=14f82e6931a8c33fc31ab8378e51804a-852f4ca7f056addda5b8fcb93e02c2fd",
  "rgbUrl": "https://solar.googleapis.com/v1/geoTiff:get?id=bf769c43d72eb85493b20df583bc0c95-d13126638efaa89e44951abc8664d6a3",
  "maskUrl": "https://solar.googleapis.com/v1/geoTiff:get?id=ed089240efc78e417c96a945460830ef-e666758b7cc183f82d1c7b7a891f858b",
  "annualFluxUrl": "https://solar.googleapis.com/v1/geoTiff:get?id=aaa2637073d62cc7331d067eb7080bbe-f94eab79915f66759f5265b2ff8b1ad4",
  "monthlyFluxUrl": "https://solar.googleapis.com/v1/geoTiff:get?id=d1608d342a3d0393b5decd063d330271-2a2e27504a2009cad1f1f3d2b471bcd3",
  "hourlyShadeUrls": [
    "https://solar.googleapis.com/v1/geoTiff:get?id=541c2f32b936f190f7562309ea1d60fc-432bf94bcd0dc918f0c828d07aa00e7c",
    "https://solar.googleapis.com/v1/geoTiff:get?id=4eb7a0b9c0f34e0e746816d0f3085274-4794b9eb35ab18ad4fbe2c3ee59f151d",
    ...
  ],
  "imageryQuality": "HIGH"
}

Access response data

Accessing data via response URLs requires additional authentication. If you use an authentication key, you must append your API key to the URL. If you use OAuth authentication, you must add OAuth headers.

API key

To make a request to the URL in the response, append your API key to the URL:

curl -X GET "https://solar.googleapis.com/v1/solar/geoTiff:get?id=fbde33e9cd16d5fd10d19a19dc580bc1-8614f599c5c264553f821cd034d5cf32&key=YOUR_API_KEY"

You can also make HTTP requests by pasting the URL in the cURL request into your browser's URL bar. Passing the API key provides you with better usage and analytics capabilities and better access control to the response data.

OAuth token

To make a request to the URL in the response, pass in your billing project name and your OAuth token:

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"
        

With the exception of the RGB layer, all TIFF files will display as blank images in image viewer applications. To view downloaded TIFF files, import them into a mapping application software, such as QGIS.

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