- URL:
- https://<root>/<serviceName>/RasterAnalysisTools/GPServer/FeatureSolarRadiation
- Methods:
GET- Version Introduced:
- 12.2
Description
The Feature 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 Feature 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:
| Parameter | Details |
|---|---|
| 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: |
| 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: |
| 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: |
| 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: Output table examples: |
| The start date and time for the analysis. Syntax: A Unix timestamp in milliseconds or a date formatted using ISO 8601 Example: |
| The end date and time for the analysis. Syntax: A Unix timestamp in milliseconds or a date formatted using ISO 8601 Example: |
| The time zone that will be used for the start and end time. The default is coordinated universal time (UTC). Example: |
| Specifies whether the input time configuration will be adjusted for daylight saving time. If set as This parameter is not applicable for analysis on the Moon. Syntax: An enumerated string value Values: |
| 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 Syntax: An enumerated string value Values: |
| Specifies the time unit that will be used for calculating solar radiation values over the entire time configuration. Note that the Syntax: An enumerated string value Values: |
| The value of the duration or time between intervals. The default values for the available interval units are listed below:
Syntax: A numerical value. Example: |
| 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: |
| 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: |
| 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: |
| 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: |
| 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: Example: |
| Specify whether the Syntax: An enumerated string value Values: |
| Specifies the type of diffuse radiation model that will be used. When set as Syntax: An enumerated string value Values: |
| 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: |
| 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: |
| 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: |
| 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 Syntax: An enumerated string value Values: |
|
Contains additional settings that affect task processing. This task has the following settings:
|
|
The response format. The default response format is Values: |
Response
When you submit a request, the task assigns a unique job ID for the transaction.
{
"jobId": "<unique job identifier>",
"jobStatus": "<job status>"
}After the initial request is submitted, you can use the job 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 job to retrieve the results. To track the status, you can make a request of the following form:
https://<raster analysis tools url>/FeatureSolarRadiation/jobs/<jobId>When the status of the job request is esri , you can access the results of the analysis by making a request of the following form:
https://<raster analysis tools url>/FeatureSolarRadiation/jobs/<jobId>/results/<output parameters>Example usage
The following is a sample request URL for Feature :
https://services.myserver.com/arcgis/rest/services/System/RasterAnalysisTools/GPServer/FeatureSolarRadiation/submitJobJSON Response syntax
The response returns the output output parameters, which have properties for parameter name, data type, and value. The content of value is always the output table item and the feature service URL.
{
"paramName": <parameter name>,
"dataType": "GPString",
"value": {
"itemId": <item Id>,
"url": <URL>
}
}JSON Response example
{
"paramName": "outputTable",
"dataType": "GPString",
"value": {
"url": "https://<server name>/server/rest/services/Hosted/<service name>/FeatureServer/0",
"itemId": "f121390b85ef419790479fc75b493efd"
}
}