Make a data layers request
Stay organized with collections
Save and categorize content based on your preferences.
Page Summary
-
The dataLayers endpoint provides downloadable TIFF files containing detailed solar information for a specified location and radius.
-
Request parameters include location coordinates, radius, data subsets, minimum quality, and pixel scale.
-
The response provides URLs to access GeoTIFF files containing solar data, such as DSM, RGB imagery, and solar flux.
-
These URLs require authentication (API key or OAuth token) and are active for one hour.
-
To view the data, import the TIFF files into mapping software like QGIS, as most will appear blank in standard image viewers.
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 or satellite 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&exactQualityRequired=true&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&exactQualityRequired=true"
TypeScript
To make a request to the URL in the response, include either your API key or the OAuth token in the request. The following example uses an API key:
/** * 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. */ exportasyncfunctiongetDataLayerUrls( location:LatLng, radiusMeters:number, apiKey:string, ):Promise<DataLayersResponse>{ constargs={ '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 BASE quality, it won't return anything. // Here we ask for *at least* BASE quality, but if there's a higher quality available, // the Solar API will return us the highest quality available. required_quality:'BASE', }; console.log('GET dataLayers\n',args); constparams=newURLSearchParams({...args,key:apiKey}); // https://developers.google.com/maps/documentation/solar/reference/rest/v1/dataLayers/get returnfetch(`https://solar.googleapis.com/v1/dataLayers:get?${params}`).then( async(response)=>{ constcontent=awaitresponse.json(); if(response.status!=200){ console.error('getDataLayerUrls\n',content); throwcontent; } console.log('dataLayersResponse',content); returncontent; }, ); }
Fields and type of data is a "type" in TypeScript. In this example, we define a custom type to store the fields of interest in the response, such as the pixel values and the lat/long bounding box. You can include more fields as desired.
exportinterfaceGeoTiff{ width:number; height:number; rasters:Array<number>[]; bounds:Bounds; }
Data type definitions
The following data types are supported:
exportinterfaceDataLayersResponse{ imageryDate:Date; imageryProcessedDate:Date; dsmUrl:string; rgbUrl:string; maskUrl:string; annualFluxUrl:string; monthlyFluxUrl:string; hourlyShadeUrls:string[]; imageryQuality:'HIGH'|'MEDIUM'|'BASE'; } exportinterfaceBounds{ north:number; south:number; east:number; west:number; } // https://developers.google.com/maps/documentation/solar/reference/rest/v1/buildingInsights/findClosest exportinterfaceBuildingInsightsResponse{ name:string; center:LatLng; boundingBox:LatLngBox; imageryDate:Date; imageryProcessedDate:Date; postalCode:string; administrativeArea:string; statisticalArea:string; regionCode:string; solarPotential:SolarPotential; imageryQuality:'HIGH'|'MEDIUM'|'BASE'; } exportinterfaceSolarPotential{ 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; } exportinterfaceSizeAndSunshineStats{ areaMeters2:number; sunshineQuantiles:number[]; groundAreaMeters2:number; } exportinterfaceRoofSegmentSizeAndSunshineStats{ pitchDegrees:number; azimuthDegrees:number; stats:SizeAndSunshineStats; center:LatLng; boundingBox:LatLngBox; planeHeightAtCenterMeters:number; } exportinterfaceSolarPanel{ center:LatLng; orientation:'LANDSCAPE'|'PORTRAIT'; segmentIndex:number; yearlyEnergyDcKwh:number; } exportinterfaceSolarPanelConfig{ panelsCount:number; yearlyEnergyDcKwh:number; roofSegmentSummaries:RoofSegmentSummary[]; } exportinterfaceRoofSegmentSummary{ pitchDegrees:number; azimuthDegrees:number; panelsCount:number; yearlyEnergyDcKwh:number; segmentIndex:number; } exportinterfaceLatLng{ latitude:number; longitude:number; } exportinterfaceLatLngBox{ sw:LatLng; ne:LatLng; } exportinterfaceDate{ year:number; month:number; day:number; } exportinterfaceRequestError{ error:{ code:number; message:string; status:string; }; }
The API returns URLs in the following format:
https://solar.googleapis.com/v1/solar/geoTiff:get?id=HASHED_ID
These URLs can be used to access GeoTIFF files with the requested data.
Example response
The request produces a JSON response in the form:
{ "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" }
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"
TypeScript
The following example shows how to get pixel data values (the information stored in individual pixels of a digital image, including color values and other attributes), calculate the latitude and longitude from the GeoTIFF, and store it in a TypeScript object.
For this specific example, we chose to allow type checking, which reduces type errors, adds reliability to your code, and makes it easier to maintain.
// npm install geotiff geotiff-geokeys-to-proj4 proj4 import*asgeotifffrom'geotiff'; import*asgeokeysToProj4from'geotiff-geokeys-to-proj4'; importproj4from'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. */ exportasyncfunctiondownloadGeoTIFF(url:string,apiKey:string):Promise<GeoTiff>{ console.log(`Downloading data layer: ${url}`); // Include your Google Cloud API key in the Data Layers URL. constsolarUrl=url.includes('solar.googleapis.com')?url+`&key=${apiKey}`:url; constresponse=awaitfetch(solarUrl); if(response.status!=200){ consterror=awaitresponse.json(); console.error(`downloadGeoTIFF failed: ${url}\n`,error); throwerror; } // Get the GeoTIFF rasters, which are the pixel values for each band. constarrayBuffer=awaitresponse.arrayBuffer(); consttiff=awaitgeotiff.fromArrayBuffer(arrayBuffer); constimage=awaittiff.getImage(); constrasters=awaitimage.readRasters(); // Reproject the bounding box into lat/lon coordinates. constgeoKeys=image.getGeoKeys(); constprojObj=geokeysToProj4.toProj4(geoKeys); constprojection=proj4(projObj.proj4,'WGS84'); constbox=image.getBoundingBox(); constsw=projection.forward({ x:box[0]*projObj.coordinatesConversionParameters.x, y:box[1]*projObj.coordinatesConversionParameters.y, }); constne=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]asgeotiff.TypedArray), ), // The bounding box as a lat/lon rectangle. bounds:{ north:ne.y, south:sw.y, east:ne.x, west:sw.x, }, }; }
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.