The dataLayers endpoint returns data encoded as GeoTIFF files, which can be used in any geographic information system (GIS) application to design solar systems.
Each string in the dataLayers response contains a URL, which you can use to fetch the corresponding GeoTIFF. URLs are valid for up to an hour after they are generated from the original data layers request. GeoTIFF files can be stored for up to 30 days.
With the exception of the RGB layer, GeoTIFF files don't display correctly with an image viewer, as the content is encoded data rather than RGB images. GeoTIFF files also cannot be used directly as an overlay image with Maps Javascript API.
The following table describes each layer in detail.
| Layer | Pixel depth | Resolution | Description |
|---|---|---|---|
| Digital Surface Model (DSM) | 32-bit float | 0.1 m/pixel | Elevation data that represents the topography of Earth's surface, including natural and built features. Values are in meters above sea level. Invalid locations, or areas where we don't have data, are stored as -9999. |
| RGB | 8-bit | 0.1 m/pixel 0.25 m/pixel 0.5 m/pixel 1 m/pixel |
An aerial image of the region. The GeoTIFF imagery file contains
three bands corresponding to red, green and blue values in order to form
24-bit RGB value for each pixel. By default, the pixel resolution is 0.1 m/pixel. |
| Building mask | 1-bit | 0.1 m/pixel | One bit per pixel indicating whether that pixel is considered to be part of a rooftop. |
| Annual flux | 32-bit float | 0.1 m/pixel | The annual flux map, or annual sunlight on roofs, of the region.
Values are kWh/kW/year. Flux is computed for every location, not just building rooftops. Invalid locations, or areas where we couldn't calculate flux, are stored as -9999. Locations outside our coverage area are invalid. Note: This is unmasked flux. |
| Monthly flux | 32-bit float | 0.5 m/pixel | The monthly flux map (sunlight on roofs, broken down by month) of the region. Values are kWh/kW/year. The GeoTIFF imagery file contains 12 bands corresponding to January — December, in order. |
| Hourly shade | 32-bit integer | 1 m/pixel | 12 URLs for hourly shade maps corresponding to January — December, in
order. Each GeoTIFF file contains 24 bands, corresponding to the 24 hours of the day. Each pixel is a 32 bit integer, corresponding to the (up to) 31 days of that month. A 1 bit means that the corresponding location is able to see the sun on that day, at that hour, in that month. Invalid locations are stored as -9999 and have bit 31 set, as that corresponds to the 32nd day of the month and is therefore invalid. |
Decode hourly shade rasters
Hourly shade data is encoded in multiband rasters. To learn more about raster basics, see Solar API Concepts.
When you make a request for hourly shade data, you can receive up to 12 rasters, one for each month of the calendar year (January through December). Each raster is composed of 24 layers, or bands, which correspond to the 24 hours of the day.
Each band is represented by a matrix of cells, or pixels. Each pixel has a depth of 32 bits, which correspond to the (maximum) 31 days of the month. Decoding the day, time, and month of shade data, therefore, requires understanding the bit, band, and raster that you are analyzing.
For example, to identify whether a given location at coordinates (x, y) saw the sun at 4:00 PM on June 22, do the following:
- Make a data layers request for all layers for location (x, y).
- Because the month of June is the sixth month of the year, fetch the sixth
URL in the
hourlyShadeUrlslist. - Hourly bands are given in 24-hour time. To get data for 4:00 PM (16:00), look up the 17th channel.
- Bits (days) index from 0. To get data for the 22nd day of June, read bit 21.
- Bits provide binary data indicating whether that location saw sun at the given date and time. If the bit is 1, the location saw sun. If the bit is 0, the location saw shade.
The following code summarizes the steps above:
(hourly_shade[month - 1])(x, y)[hour] & (1 << (day - 1))