Trigger an analysis
POST
v1alpha/analyses/trigger
Trigger a sun analysis for a proposal or element on a given date. When the analysis is finished, you can fetch the raw ground results for the analysis.
Resource Information
| Method and URI | POST https://developer.api.autodesk.com/forma/sun-analysis/v1alpha/analyses/trigger |
| Authentication Context | user context required |
| Required OAuth Scopes | data:read data:write |
| Data Format | JSON |
Request
Headers
| Authorization* string | Must be Bearer <token>, where <token> is obtained via a three-legged OAuth flow. |
| X-Ads-Region string | Specifies the geographical location (region) of the service. US or EMEA. Defaults to US. |
| Content-Type* string | Must be application/json |
* Required
Request
Query String Parameters
| authcontext* string | The authcontext of the resource you are requesting |
* Required
Request
Body Structure
Expand all
| rootElementUrn* string | The root urn for the analysis. The root needs a terrain for the analysis to run properly. |
| sunDate* object | The month and day the analysis is run on. |
| month* int | Month of year, starting at 1. |
| date* int | Day of month, starting at 1. |
| geoLocation* object | The location the analysis should be run for |
| latitude* number | |
| longitude* number | |
| selectedElementPaths* array: string | The selected elements’ paths relative to the root. |
* Required
Response
HTTP Status Code Summary
| 200 OK | The response will contain the metadata of the newly triggered analysis.
If the configuration of the analysis has previously been triggered, no new analysis will be triggered, but the already created analysis metadata will be returned. |
| 400 Bad Request | Malformed request. The request body is not valid according to the schema. See response for details. |
| 401 Unauthorized | Bearer token is not valid |
| 403 Forbidden | Token does not have access to the specified project. Are you in the right region? |
| 429 Too Many Requests | There are limits to how many analysis can be run on a given day or concurrently. If that limit is exceeded, 429 will be returned |
| 500 Internal Server Error | Internal server error |
Response
Body Structure (200)
| id string | The id of the analysis |
| status enum:string | Status of the analysis
Possible values: IN_PROGRESS, SUCCEEDED, STOPPED |
Example
The response will contain the metadata of the newly triggered analysis.
If the configuration of the analysis has previously been triggered, no new analysis will be triggered, but the already created analysis metadata will be returned.
Request
curl -v 'https://developer.api.autodesk.com/forma/sun-analysis/v1alpha/analyses/trigger' \
-X 'POST' \
-H 'Authorization: Bearer AuIPTf4KYLTYGVnOHQ0cuolwCW2a' \
-H 'Content-Type: application/json' \
-d '{
"rootElementUrn": "urn:adsk-forma-elements:proposal:pro_123:id134unique:1707471576213",
"sunDate": {
"month": "",
"date": ""
},
"geoLocation": {
"latitude": "",
"longitude": ""
},
"selectedElementPaths": [
""
]
}'
Show More
Response
{
"id": "",
"status": "IN_PROGRESS"
}