21 Jul 2021

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:

 

Updated Assets Sample

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

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

{
    "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
        }
    ]
}
[
  {
    "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. 

 

Related Article

Posted By

Mikako Harada

Mikako Harada

Mikako Harada works as an AEC technical lead and Americas manager for the Developer Technical Services (DevTech) team at Autodesk. She provides API (Application Programming Interface) technical support to the members of Autodesk Developer Network worldwide for AEC products. Prior to joining Autodesk, she worked as a researcher for the Swiss Federal Institute of Technology (ETH) in Zurich. While at ETH, she...

Eason Kang

Eason Kang is a member of the Autodesk Developer Network ADN DevTech team, focusing on providing programming support, consulting, training and evangelism to external developers. He started his career in Taiwan and now lives in Taipei, Taiwan. He is a developer consultant in the team DevTech, the worldwide team of API gurus providing technical services through the Autodesk Developer Network. He supports various...