Request

Response

    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"
    }