Developer Network NREL NREL Developer Network

Solar Resource Data (GET /api/solar/solar_resource/v1)

Returns various types of solar data for a location. The service currently returns data for average Direct Normal Irradiance, average Global Horizontal Irradiance, and average Tilt at Latitude.

Request URL

GET /api/solar/solar_resource/v1.format?parameters

Request Parameters

Parameter Required Value Description
format Yes
Type: string
Default: None
Options: json, xml

The output response format.

api_key Yes
Type: string
Default: None

Your developer API key. See API keys for more information.

address Depends
Type: string
Default: None

The address to use (lat/lon returned by Google's geocoding service). Required if lat/lon not specified.

lat Depends
Type: decimal
Default: None
Range: -90 to 90
The latitude for the location to use. Required if address not specified.
lon Depends
Type: decimal
Default: None
Range: -180 to 180
The longitude for the location to use. Required if address not specified.

Response Fields

The response is composed of service-related informational fields and the results of the data query.

Field Value Description
inputs Type: collection The input parameters received in the request.
version Type: string The current version of the web service.
errors Type: array of strings Any error messages resulting from the request.
warnings Type: array of strings Any warning messages resulting from the request.
metadata Type: collection Any metadata associated with the request (sources, etc)
outputs Type: collection The data outputs from the request. (see output fields for more detail)

Output Fields

The output fields contain the following solar data.

Field Value Description
avg_dni

Type:

decimal (annual),

collection of decimals (monthly)

Average Direct Normal Irradiance: This data provides monthly average and annual average daily total solar resource averaged over surface cells of 0.1 degrees in both latitude and longitude, or about 10 km in size. The values returned are kWh/m2/day (kilowatt hours per square meter per day). The insolation values represent the resource available to concentrating systems that track the sun throughout the day. The data are created using the SUNY Satellite Solar Radiation model (Perez, et.al., 2002). The data are averaged from hourly model output over 12 years (1998-2009). This model uses hourly radiance images from geostationary weather satellites, daily snow cover data, and monthly averages of atmospheric water vapor, trace gases, and the amount of aerosols in the atmosphere to calculate the hourly total insolation (sun and sky) falling on a horizontal surface. The direct beam radiation is then calculated using the atmospheric water vapor, trace gases, and aerosols, which are derived from a variety of sources. Where possible, existing ground measurement stations are used to validate the data. (see http://www.nrel.gov/gis)
avg_ghi

Type:

decimal (annual),

collection of decimals (monthly)

Average Global Horizontal Irradiance: This data provides monthly average and annual average daily total solar resource averaged over surface cells of 0.1 degrees in both latitude and longitude, or about 10 km in size. The values returned are kWh/m2/day (kilowatt hours per square meter per day). The insolation values represent the global horizontal resource - the geometric sum of direct normal and diffuse irradiance components, representing total energy available on a planar surface. The data are created using the SUNY Satellite Solar Radiation model (Perez, et.al., 2002). The data are averaged from hourly model output over 12 years (1998-2009). This model uses hourly radiance images from geostationary weather satellites, daily snow cover data, and monthly averages of atmospheric water vapor, trace gases, and the amount of aerosols in the atmosphere to calculate the hourly total insolation (sun and sky) falling on a horizontal surface. The direct beam radiation is then calculated using the atmospheric water vapor, trace gases, and aerosols, which are derived from a variety of sources. Where possible, existing ground measurement stations are used to validate the data. (see http://www.nrel.gov/gis)
avg_lat_tilt

Type:

decimal (annual),

collection of decimals (monthly)

Average Tilt at Latitude: This data provides monthly average and annual average daily total solar resource averaged over surface cells of 0.1 degrees in both latitude and longitude, or about 10 km in size. The values returned are kWh/m2/day (kilowatt hours per square meter per day). The insolation values represent the resource available to fixed flat plate system tilted towards the equator at an angle equal to the latitude. The data are created using the SUNY Satellite Solar Radiation model (Perez, et.al., 2002). The data are averaged from hourly model output over 12 years (1998-2009). This model uses hourly radiance images from geostationary weather satellites, daily snow cover data, and monthly averages of atmospheric water vapor, trace gases, and the amount of aerosols in the atmosphere to calculate the hourly total insolation (sun and sky) falling on a horizontal surface. The direct beam radiation is then calculated using the atmospheric water vapor, trace gases, and aerosols, which are derived from a variety of sources. Where possible, existing ground measurement stations are used to validate the data. (see http://www.nrel.gov/gis)

Examples

JSON Output Format

GET /api/solar/solar_resource/v1.json?api_key=DEMO_KEY&lat=40&lon=-105
{
  "version": "1.0.0",
  "warnings": [

  ],
  "errors": [

  ],
  "metadata": {
    "sources": [
      "Perez-SUNY/NREL, 2012"
    ]
  },
  "inputs": {
    "api_key": "DEMO_KEY",
    "lat": "40",
    "lon": "-105"
  },
  "outputs": {
    "avg_dni": {
      "annual": 6.06,
      "monthly": {
        "jan": 5,
        "feb": 5.34,
        "mar": 5.94,
        "apr": 6.11,
        "may": 6.36,
        "jun": 7.43,
        "jul": 7.48,
        "aug": 6.65,
        "sep": 6.81,
        "oct": 5.82,
        "nov": 5.11,
        "dec": 4.67
      }
    },
    "avg_ghi": {
      "annual": 4.81,
      "monthly": {
        "jan": 2.5,
        "feb": 3.43,
        "mar": 4.69,
        "apr": 5.69,
        "may": 6.6,
        "jun": 7.25,
        "jul": 7.14,
        "aug": 6.24,
        "sep": 5.35,
        "oct": 3.85,
        "nov": 2.75,
        "dec": 2.19
      }
    },
    "avg_lat_tilt": {
      "annual": 5.82,
      "monthly": {
        "jan": 4.79,
        "feb": 5.4,
        "mar": 6.07,
        "apr": 6.11,
        "may": 6.25,
        "jun": 6.47,
        "jul": 6.58,
        "aug": 6.44,
        "sep": 6.53,
        "oct": 5.71,
        "nov": 4.99,
        "dec": 4.47
      }
    }
  }
}

XML Output Format

GET /api/solar/solar_resource/v1.xml?api_key=DEMO_KEY&lat=40&lon=-105
<?xml version="1.0"?>
<response>
  <version>1.0.0</version>
  <warnings type="array"/>
  <errors type="array"/>
  <metadata>
    <sources type="array">
      <source>Perez-SUNY/NREL, 2012</source>
    </sources>
  </metadata>
  <inputs>
    <api-key>DEMO_KEY</api-key>
    <lat>40</lat>
    <lon>-105</lon>
  </inputs>
  <outputs>
    <avg-dni>
      <annual type="float">6.06</annual>
      <monthly>
        <jan type="float">5.0</jan>
        <feb type="float">5.34</feb>
        <mar type="float">5.94</mar>
        <apr type="float">6.11</apr>
        <may type="float">6.36</may>
        <jun type="float">7.43</jun>
        <jul type="float">7.48</jul>
        <aug type="float">6.65</aug>
        <sep type="float">6.81</sep>
        <oct type="float">5.82</oct>
        <nov type="float">5.11</nov>
        <dec type="float">4.67</dec>
      </monthly>
    </avg-dni>
    <avg-ghi>
      <annual type="float">4.81</annual>
      <monthly>
        <jan type="float">2.5</jan>
        <feb type="float">3.43</feb>
        <mar type="float">4.69</mar>
        <apr type="float">5.69</apr>
        <may type="float">6.6</may>
        <jun type="float">7.25</jun>
        <jul type="float">7.14</jul>
        <aug type="float">6.24</aug>
        <sep type="float">5.35</sep>
        <oct type="float">3.85</oct>
        <nov type="float">2.75</nov>
        <dec type="float">2.19</dec>
      </monthly>
    </avg-ghi>
    <avg-lat-tilt>
      <annual type="float">5.82</annual>
      <monthly>
        <jan type="float">4.79</jan>
        <feb type="float">5.4</feb>
        <mar type="float">6.07</mar>
        <apr type="float">6.11</apr>
        <may type="float">6.25</may>
        <jun type="float">6.47</jun>
        <jul type="float">6.58</jul>
        <aug type="float">6.44</aug>
        <sep type="float">6.53</sep>
        <oct type="float">5.71</oct>
        <nov type="float">4.99</nov>
        <dec type="float">4.47</dec>
      </monthly>
    </avg-lat-tilt>
  </outputs>
</response>

Rate Limits

Standard rate limits apply. No more than 1,000 requests may be made in any hour

Errors

Standard errors may be returned. In addition, the following service-specific errors may be returned:

HTTP Status Code Description
422 Unprocessable Entity - One or more parameters did not pass validation, or a parameter may be missing. Check the errors section of the response to see how the request should be modified to address the error.
Help Improve this Content