New Endpoint: GET Locations in BIM 360/ACC

We're pleased to inform you that the long-awaited GET Locations endpoint for BIM 360/Autodesk Construction Cloud (ACC) is finally made available. 

Locations in BIM 360 and ACC is a tree structure that defines a hierarchical organization of areas used in the project, such as buildings, floors and rooms. Location is defined in Project Admin and is a dependency in other modules, such as Issues and Assets. You can find more information about location in the product help.

You can use this single endpoint to retrieve a collection of nodes in a tree structure or use a filter to obtain specific nodes: 

• GET List nodes (for BIM 360 project. With /bim360/ in base URL. Compatible with ACC project.) 
• GET List nodes (for ACC project only. With /construction/ in base URL.)  

Functionality wise, these two endpoints are identical.    

Response includes the details about each location, such as the name and ID of the location. To retrieve a full path of the node position in a given tree, you can also use the filter.

Here is an example of response to show you how it looks like: 

{
  "pagination": {
    "limit": 3,
    "offset": 0,
    "totalResults": 7,
    "next": "/locations/v2/containers/4a327b27-897c-4e5a-8e48-6e01c12345f3/trees/default/nodes?limit=3&offset=3"
  },
  "results": [
    {
      "id": "5add4375-f223-4201-88b9-4980e68416aa",
      "parentId": null,
      "type": "Root",
      "name": "Project",
      "description": "Project description",
      "barcode": null,
      "order": 0,
      "documentCount": 0,
      "areaDefined": false
    },
    {
      "id": "d14ce3a6-e61b-4ab0-a9be-5acf7b6653df",
      "parentId": "5add4375-f223-4201-88b9-8049e68416aa",
      "type": "Area",
      "name": "Level 1",
      "description": "A node of level 1.",
      "barcode": "ABC123",
      "order": 0,
      "documentCount": 2,
      "areaDefined": false
    },
    {
      "id": "826e102a-36de-41e7-8c58-1b1666ccbba6",
      "parentId": "5add4375-f223-4201-44b9-4449e68416aa",
      "type": "Area",
      "name": "Living Room",
      "description": "A node of living room.",
      "barcode": "DEF456",
      "order": 1,
      "documentCount": 3,
      "areaDefined": true
    }
  ]
}

Notes:

• Locations API supports 3-legged authentication only.
• The definition of location requires Project Admin privilege. But project members can read location data. 

For more information about this endpoint, please check the reference guide and give it a try:

Documentation:

• Reference Guide for BIM 360, and for ACC 

Updated Assets Sample

Now that we have GET locations API, we have updated one of Assets API samples to fill the missing feature:    

• View Assets in Design Model (Integration with Viewer and filtering by rooms and levels)

When we call Assets API, we see the location data as a GUID. For example,  

• Response of GET assets

{
    "pagination": {
        // ...
    },
    "results": [
        {
            "id": "f6b0b2c5-780b-4dd9-b1b4-480a55565e1a",
            // ...
            "isActive": true,
            "categoryId": "28",
            "clientAssetId": "464528",
            "statusId": "151fa9dc-3fd2-47b8-90b7-eb73b33334a2",
            "locationId": "826e102a-36de-41e7-8c58-1b2226ccbba8", //!<<< Asset Location Id
        }
    ]
}

• Request body of POST assets:batch-create

[
  {
    "clientAssetId": "MVS-3D2",
    "categoryId": "42",
    "statusId": "84eb6a10-dde3-475f-aaf4-b5df3aebbd0b",
    "description": "AC unit for basement",
    "locationId": "826e102a-36de-41e7-8c58-1b1696ccbba8", //!<<< Asset Location Id
    "barcode": "F0086728"
  }
]

Using locations API, you can obtain the human recognizable name of the location.  No more workaround like executing Data Connector API for the entire account!   

Write APIs are also in pipeline. We hope to see them coming near future.