Request

Response

    Get analysis
    GET

    v1alpha/analyses/{analysisId}

    Get the metadata of an analysis

    Resource Information

    Method and URI
    GET
    https://developer.api.autodesk.com/forma/sun-analysis/v1alpha/analyses/{analysisId}
    Authentication Context
    user context required
    Required OAuth Scopes
    data:read
    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.
    * Required

    Request

    URI Parameters

    analysisId
    string
    The id of the analysis

    Request

    Query String Parameters

    authcontext*
    string
    The authcontext of the resource you are requesting
    * Required

    Response

    HTTP Status Code Summary

    200
    OK
    The response will contain the metadata of the analysis, such as status and the analysis’ parameters. If there exists a result for the ground on the analysis, there is also a groundResultsDataUrl, which is a location for the raw ground results of that analysis. The results will be in msgpack format.
    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?
    404
    Not Found
    No analysis exists for this analysis ID
    500
    Internal Server Error
    Internal server error

    Response

    Body Structure (200)

    Expand all
    id
    string
    The id of the analysis
    createdAt
    datetime: ISO 8601
    ISO8601 timestamp (UTC) of when the analysis was created
    completedAt
    datetime: ISO 8601
    ISO8601 timestamp (UTC) of when the analysis finished
    status
    enum:string
    The status of the analysis. Possible values: IN_PROGRESS, SUCCEEDED, FAILED, STOPPED, INVALIDATED
    parameters
    object
    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.
    groundResultsDataUrl
    string
    The location of the raw results data. The data is in ``msgpack` <https://msgpack.org/index.html>`_ format.

    See the groundResultsDataUrlFormat property for documentation of the data structure. Note that groundResultsDataUrlFormat is never included in the response.

    groundResultsDataUrlFormat
    object
    (This property is not included in the reponse. It only describes the format of the file that can retrieved by the URL above.)

    Metadata of the analysis that describes how you should parse the analysis in relation to the proposal it was run on. Is used to place the result in the real world.

    grid
    array: number
    The grid is a Uint8Array and each sample point is represented with 30 Uint8 values. Each of the 8 bits in the Uint8 signals if the location is sunlit (1) or not (0) at a certain time. Results are provided for every 6 minutes throughout the day, which is why 30 bytes are required to represent the results for each sample point. The analysis is run 00:00 to 23:59 local time on the date on which the analysis was run; the first value for a sample point is for 00:00 local time for that day. Local time uses the timezone derived from the input geolocation.
    mask
    array: integer
    Boolean array which denotes if each sample point is a valid point. Invalid sample points are typically the ones where a building is placed.
    resolution
    number
    Meters between each sample point in the scores array
    width
    int
    Number of points in the horizontal direction (columns) in the scores array.
    height
    int
    Number of points in the vertical direction (rows) in the scores array.
    x0
    number
    x-coordinate of the upper left corner of the ground grid.
    y0
    number
    y-coordinate of the upper left corner of the ground grid.

    Example

    The response will contain the metadata of the analysis, such as status and the analysis’ parameters. If there exists a result for the ground on the analysis, there is also a groundResultsDataUrl, which is a location for the raw ground results of that analysis. The results will be in msgpack format.

    Request

    curl -v 'https://developer.api.autodesk.com/forma/sun-analysis/v1alpha/analyses/:analysisId' \
      -H 'Authorization: Bearer AuIPTf4KYLTYGVnOHQ0cuolwCW2a'
    

    Response

    {
      "id": "",
      "createdAt": "",
      "completedAt": "",
      "status": "IN_PROGRESS",
      "parameters": {
        "rootElementUrn": "urn:adsk-forma-elements:proposal:pro_123:id134unique:1707471576213",
        "sunDate": {
          "month": "",
          "date": ""
        },
        "geoLocation": {
          "latitude": "",
          "longitude": ""
        },
        "selectedElementPaths": [
          ""
        ]
      },
      "groundResultsDataUrl": "",
      "groundResultsDataUrlFormat": {
        "grid": [
          ""
        ],
        "mask": [
          0
        ],
        "resolution": "",
        "width": "",
        "height": "",
        "x0": "",
        "y0": ""
      }
    }
    
    Show More