URL:
https://<root>/<serviceName>/RasterAnalysisTools/GPServer/FeatureSolarRadiation
Methods:
GET
Version Introduced:
12.2

Description

The FeatureSolarRadiation task calculates incoming solar insolation for point or polygon features on Earth or the Moon. Features can represent locations or engineered surfaces using attributes such as size, height, and orientation. Results provide total and average solar energy received over a specified time period, reported in kWh and kWh/m^2.

Example applications of FeatureSolarRadiation include the following:

  • Evaluate how much solar energy rooftop or ground-mounted solar installations can receive.
  • Assess solar exposure on building facades, windows, walls, and roofs to improve energy efficiency.
  • Evaluate solar illumination for Moon-based habitats, landers, rovers, and other infrastructure.

Request parameters

The following table lists the parameters with syntax and details for each:

ParameterDetails

inputSurfaceRaster (Required)

The input surface raster.

Syntax: This parameter can be specified as a portal item ID, a URL to a raster image service layer, a cloud raster dataset, or a shared raster dataset.

Examples:

Use dark colors for code blocksCopy
1
2
3
4
5
//Input surface raster as portal item
"inputSurfaceRaster": {"itemId": <portal item id>}

//Input surface raster as URL
"inputSurfaceRaster": {"url": <image service layer url>}

inputFeatures (Required)

The input point or polygon features from which to calculate the incoming solar insolation.

Syntax: This parameter can be specified as a URL to a feature service layer with an optional filter to select specific features, or a feature collection.

Examples:

Use dark colors for code blocksCopy
1
2
3
4
5
//Feature layer url
"inputFeatures": {"url":<feature service layer url> "filter":<where clause>}

//Feature collection
"inputFeatures": {"layerDefinition": {}, "featureSet":{}, "filter": <where clause>}

uniqueIdField (Required)

A field on the inputFeatures value that contains the values that define each set of unique features. It can be an OID, integer or a string field of the inputFeatures.

Example:

Use dark colors for code blocksCopy
1
"uniqueIdField": {"name": "MyIDField", "type": "esriFieldTypeInteger"}

outputTableName (Required)

The name of the output table or feature service that will be created.

Syntax: A JSON object describes the name of the output or the output table.

Output table name example:

Use dark colors for code blocksCopy
1
"outputTableName": {"serviceProperties":{"name":"solarRadiation_Table"}}

Output table examples:

Use dark colors for code blocksCopy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
//Output portal item:
"outputTableName": {"itemId": <portal item id>}

//Output url:
"outputTableName": {"url": <feature service url>}

//Output table layer service:
"outputTableName": {
  "serviceProperties": {
    "name":"testrasteranalysis",
    "serviceUrl":"https://<server name>/server/rest/services/Hosted/solarRadiation_Table/FeatureServer/0"
  },
  "itemProperties": {
    "itemId":"351fe8441a1a436d8001124487b02550",
    "folderId":"sdfwerfbd3ec25584d0d8f4"
  }
}

startDateTime (Required)

The start date and time for the analysis.

Syntax: A Unix timestamp in milliseconds or a date formatted using ISO 8601

Example:

Use dark colors for code blocksCopy
1
2
3
4
5
//input date that corresponds to 1 Jan 2026 02:00:00 PM GMT.
"startDateTime": 1767277800000

//or specify a formatted date. Note: AM/PM designator, time zone designator (z), and fractional second precision (.s) are not supported.
"startDateTime": "2026-01-01T14:30:00:000"

endDateTime (Required)

The end date and time for the analysis.

Syntax: A Unix timestamp in milliseconds or a date formatted using ISO 8601

Example:

Use dark colors for code blocksCopy
1
2
3
4
5
//input date that corresponds to 8 Jan 2026 02:30:00 PM GMT.
"endDateTime": 1767882600000

//or specify a formatted date. Note: AM/PM designator, time zone designator (z), and fractional second precision (.s) are not supported.
"endDateTime": "2026-01-08T14:30:00:000"

timeZone

The time zone that will be used for the start and end time. The default is coordinated universal time (UTC).

Example:

Use dark colors for code blocksCopy
1
2
// The time zone will be Eastern Standard Time (UTC-05:00)
"timeZone": "Eastern_Standard_Time"

adjustDST

Specifies whether the input time configuration will be adjusted for daylight saving time. If set as true, the input time values will be adjusted for daylight saving time. If set as false, the input time values will not be adjusted for daylight saving time. The default value is false.

This parameter is not applicable for analysis on the Moon.

Syntax: An enumerated string value

Values: true | false

useTimeInterval

Specifies whether to calculate a single total insolation value or radiation values at regular intervals. Using intervals creates a multidimensional raster output. If set as true, radiation values are calculated for each time interval. If set as false, a single radiation value is calculated for the entire time period. The default value is false.

Syntax: An enumerated string value

Values: true | false

intervalUnit

Specifies the time unit that will be used for calculating solar radiation values over the entire time configuration. Note that the MINUTE value is only available for Earth-based data. The default value is DAY.

Syntax: An enumerated string value

Values: MINUTE | HOUR | DAY | WEEK

interval

The value of the duration or time between intervals. The default values for the available interval units are listed below:

  • MINUTE: 60
  • HOUR: 4
  • DAY: 14
  • WEEK: 2

Syntax: A numerical value.

Example:

Use dark colors for code blocksCopy
1
"interval": 2

featureOffset

A vertical distance that will be added to the raster surface for analysis. It must be a positive integer or floating-point value.

Specify a field or a numeric value. A value applies to all features, while a field allows unique values for each feature.

Syntax: A composite parameter with data type name and its value

Examples:

Use dark colors for code blocksCopy
1
2
3
4
5
// Specify a value
"featureOffset": {"value": 8, "dataType": "GPDouble"}

// Specify a field
"featureOffset": {"name": "Value", "type": "esriFieldTypeInteger"},

featureArea

The area associated with the input features. It must be a positive integer or floating-point value.

Specify a field or a numeric value. A value applies to all features, while a field allows unique values for each feature.

Syntax: A composite parameter with data type name and its value

Examples:

Use dark colors for code blocksCopy
1
2
3
4
5
// Specify a value
"featureArea": {"value": 30, "dataType": "GPDouble"}

// Specify a field
"featureArea": {"name": "Value", "type": "esriFieldTypeInteger"},

featureSlope

The relative slope or incline associated with the input features. It must be a positive integer or floating-point value.

Specify a field or a numeric value. A value applies to all features, while a field allows unique values for each feature.

Slope is expressed in degrees from 0 to 90. The default values are the slope values calculated from the input surface raster.

Syntax: A composite parameter with data type name and its value

Examples:

Use dark colors for code blocksCopy
1
2
3
4
5
// Specify a value
"featureSlope": {"value": 32.5, "dataType": "GPDouble"}

// Specify a field
"featureSlope": {"name": "Value", "type": "esriFieldTypeInteger"},

featureAspect

The relative aspect or direction associated with the input features. It must be a positive integer or floating-point value.

Specify a field or a numeric value. A value applies to all features, while a field allows unique values for each feature.

Aspect is expressed in degrees from 0 to 360. The default values are the aspect values calculated from the input surface raster.

Syntax: A composite parameter with data type name and its value

Examples:

Use dark colors for code blocksCopy
1
2
3
4
5
// Specify a value
"featureAspect": {"value": 160.5, "dataType": "GPDouble"}

// Specify a field
"featureAspect": {"name": "Value", "type": "esriFieldTypeInteger"},

neighborhoodDistance

The output will be calculated over this distance from the target cell center. It determines the neighborhood size. The default value is the input raster cell size, resulting in a 3 by 3 neighborhood.

Syntax: A linear unit specifying the distance and units.

Supported units: Kilometers | Meters | Decimeters | Centimeters | Millimeters | Nautical Miles | Miles | Yards | Feet | Inches | Decimal Degrees | Points

Example:

Use dark colors for code blocksCopy
1
"neighborhoodDistance": {"distance": <value>, "units": <unit>}

useAdaptiveNeighborhood

Specify whether the neighborhoodDistance value will vary with landscape changes (adaptive). The maximum distance is determined by the neighborhood distance. The minimum distance is the input raster cell size. When set as true, an adaptive neighborhood distance will be used at all locations. When set as false, a single (fixed) neighborhood distance will be used at all locations. The default value is false.

Syntax: An enumerated string value

Values: true | false

diffuseModelType

Specifies the type of diffuse radiation model that will be used. When set as UNIFORM_SKY, the uniform diffuse model will be used. The incoming diffuse radiation is the same from all sky directions. When set as STANDARD_OVERCAST_SKY, the standard overcast diffuse model will be used. The incoming diffuse radiation flux varies with the zenith angle. The default value is UNIFORM_SKY.

Syntax: An enumerated string value

Values: UNIFORM_SKY | STANDARD_OVERCAST_SKY

diffuseProportion

The proportion of global normal radiation flux that is diffuse. Values range from 0 to 1.

Set this value according to atmospheric conditions. The default value is 0.3 for generally clear sky conditions.

Syntax: A numerical value.

Example:

Use dark colors for code blocksCopy
1
"diffuseProportion": 0.3

transmittivity

The fraction of radiation that passes through the atmosphere (averaged overall wavelengths). Values range from 0 (no transmission) to 1 (all transmission).

The default is 0.5 for a generally clear sky.

Syntax: A numerical value.

Example:

Use dark colors for code blocksCopy
1
"transmittivity": 0.5

sunmapGridLevel

The resolution that will be used to generate the H3 hexagonal grid cells used for internal calculations. A lower grid level value creates fewer, larger sun map areas and decreases tool run time. A higher grid level creates more smaller sun maps improving the accuracy of the result.

Valid values of the sun map grid level for Earth range from 5 to 7. For the Moon, the valid value range is from 4 to 6.

Default Grid Level: Determined by the input surface raster. For Earth, the default is Level 6 when the analysis cell size is ≤ 4 m, otherwise Level 5. For the Moon, the default is Level 6.

Syntax: A numerical value.

Example:

Use dark colors for code blocksCopy
1
"sunmapGridLevel": 6

analysisTargetDevice

The analysis target device allow you to choose where and how you want to process your data. You can process your data using the computer central processing unit (CPU) or the graphics processing unit (GPU). When set as CPU_ONLY, data will be processed using only the computer's CPU. When set as GPU_ONLY, data will be processed using only the computer's GPU. When set as GPU_THEN_CPU, if a compatible GPU is found, it will be used to process data; otherwise, the CPU will be used. This default value is GPU_THEN_CPU.

Syntax: An enumerated string value

Values: CPU_ONLY | GPU_ONLY | GPU_ONLY

context

Contains additional settings that affect task processing. This task has the following settings:

  • Extent (extent)—A bounding box that defines the analysis area.

  • Output Spatial Reference (outSR )—The output raster will be projected into the output spatial reference.

  • Snap Raster (snapRaster )—The output raster will have its cells aligned with the specified snap raster.

  • Cell Size (cellSize )—The output raster will have the resolution specified by cell size.

  • Mask (mask)—Only cells that fall within the analysis mask will be considered in the operation.

f

The response format. The default response format is html .

Values: html | json | pjson

Response

When you submit a request, the task assigns a unique job ID for the transaction.

Use dark colors for code blocksCopy
1
2
3
4
{
  "jobId": "<unique job identifier>",
  "jobStatus": "<job status>"
}

After the initial request is submitted, you can use the jobId to periodically check the status of the job and messages as described in Checking job status. Once the job has successfully completed, you use the jobId to retrieve the results. To track the status, you can make a request of the following form:

Use dark colors for code blocksCopy
1
https://<raster analysis tools url>/FeatureSolarRadiation/jobs/<jobId>

When the status of the job request is esriJobSucceeded , you can access the results of the analysis by making a request of the following form:

Use dark colors for code blocksCopy
1
https://<raster analysis tools url>/FeatureSolarRadiation/jobs/<jobId>/results/<output parameters>

Example usage

The following is a sample request URL for FeatureSolarRadiation :

Use dark colors for code blocksCopy
1
https://services.myserver.com/arcgis/rest/services/System/RasterAnalysisTools/GPServer/FeatureSolarRadiation/submitJob

JSON Response syntax

The response returns the outputTable output parameters, which have properties for parameter name, data type, and value. The content of value is always the output table itemId and the feature service URL.

Use dark colors for code blocksCopy
1
2
3
4
5
6
7
8
{
  "paramName": <parameter name>,
  "dataType": "GPString",
  "value": {
    "itemId": <item Id>,
    "url": <URL>
  }
}

JSON Response example

Use dark colors for code blocksCopy
1
2
3
4
5
6
7
8
{
  "paramName": "outputTable",
  "dataType": "GPString",
  "value": {
    "url": "https://<server name>/server/rest/services/Hosted/<service name>/FeatureServer/0",
    "itemId": "f121390b85ef419790479fc75b493efd"
  }
}

Your browser is no longer supported. Please upgrade your browser for the best experience. See our browser deprecation post for more details.