BIM Track API
We have the production API connected with regular services and the sandbox connected with the beta services. Please note that the beta service is not the regular BIMTrackapp services and is used to get early access to feature and API version access. See links to our BIM Track API documentation as well as the beta sandbox environment URL below.
- Prod: https://bimtrackapp.co/
*For third party software developpers, once your account is created please send a request to activate with the hub name.
- Beta sandbox: https://bimtrackbeta.co/ (we will need your hub name to unlock all features)
*The beta sandbox has separate credentials, once the account is created please send a request to firstname.lastname@example.org to activate with your hub name.
- First of all you need to login.
- After you are logged you need to go to the HubSettings page from the left side menu.
- On that page HUB OWNERS are able to generate your access token by clicking the gear in the upper right corner of the page and then "API Access Token".
- From the modal window you can generate your API access token and copy it for further use in our API test page.
- Open a new browser tab, go to our API test page at : https://api.bimtrackbeta.co//swagger/ui/index
- On that page you will be able to fully test our web API functions but first off all you need to provide your access token.
- After you apply your token, you will be able to test all the functions but first let me explain a bit the content of the test page.
- On the left side, as you scroll down or click on the main areas(File/Hub/Issue/Project) you will see the functions related to each areas.
- In the middle, you have the functions/route and parameters needed and a button to test.
- On the right side, for each functions, you have the response sample as well as the response schema if you click on it.
- After you have filled the mandatory fields and clicked on TRY, you will have your information on a modal window like this one
To use our addins for Autodesk and Trimble in the beta sandbox environment:
In Autodesk products:
- Browse: %appdata%\Roaming\Autodesk\ApplicationPlugins\BimOne.BIMTrack.bundle\Contents
- Select the appropriate software and version (i.e.: Navisworks/2017)
- Open "BIMOne.BIMTrack.Addins.Autodesk.Navisworks.dll.config".
- Replace all 'bimtrackservice.bimtrackapp.co' by bimtrackservice.bimtrackbeta.co
In Trimble product:
- Browse: C:\Program Files (x86)\BIM Track
- Open "BIMOne.BIMTrack.Addins.Autodesk.Navisworks.dll.config".
- Replace all 'bimtrackservice.bimtrackapp.co' by Bimtrackservice.bimtrackbeta.co
See also example of powerBI dashboard, functions and quick video:
Note: By default every file / image is protected by an access token that is generated on demand. The expiration delay for these tokens are set to 8 hours, and tokens are reused util there is 1 hour validity left. If the API is queried within the last hour of validity, then a new token is generated, again valid for 8 hours.
This mechanism may cause issues in Power BI if the dataset is refreshed just before the last hour. In such case, the API would return the existing token (that will expire within the next hour), so the URL might not be reliable until the next refresh. We added a way of forcing the regeneration of tokens, and controlling the lifetime of the generated tokens. To take advantage of this, headers should be added to the requests:
x-externalLinksTokenPolicy-createNewTokens = true
Use this header to force new token generation, having the default life span defined in BIM Track (8 hour)
x-externalLinksTokenPolicy-expirationDelay = 480
Use this header to control the lifetime, in minutes, of the generated tokens
Example in PostMan:
How to query BIM Track API
In order to query data from the BIM Track API you can either:
Build a new web query from the documentation
Note that creating a simple query of issues for a project with more than 100 issues will only return the latest 100 issues unless you are building a pagination function
Use one of the functions in this file to query data.
By using these functions, you will be able to fetch all the data as they are built to do pagination.
- In the power query editor, select one of the functions
- Fill in the requested fields and invoke the function
- You now have the data requested and need to expand and process it in Power BI
DEMO PROJECT data is displayed and expanded as is. To get relevant data out of queries you should understand some of the principles behind the data structure to make sure you are getting results right:
- When you expand, a list you might have several lines for the same issue id for example. That makes sense once you understand that for example, an issue can have several screenshots image, and therefore several imageUrl, Depending on the data you will want to analyze, you will want to set the filtering to "unique data"
- [Modeling][Manage relationships] or the relationship tab on the left panel allows you to set relations between queries. From one query containing the issue id, you will be able to link thet issue id to the one of another query and be able to correctly use the data of both queries in one vizualization
- In order to see the image of a project you should set the data of the column to the ImageURL category in the [MODELING][PROPERTIES][DATA CATEGORY] tab.
DEMO PROJECT data is irrelevant, it is here only as a demonstration of resulting functions queries and the access token may be revoked at anytime. You should understand that the access token is private and allows not only to read data from BIMTrack's hub database but also allows you to write data, therefore it should not be shared outside of your organization without notice.
Q: How do I change the viewpoint image of an issue
A: You will understand how to change the viewpoint image of an issue in this video: Issue viewpoints interaction
Q: Why am I hitting a lot of "quota-exceeded" responses?
A: This happens when you make more than 10 requests per second to the API. It happens most of the time when you get the data periodically.
This is supported workflow, but we suggest you do not get the data from all the issues in all the projects in your hub since this leads to the throttling errors you are getting. Depending on how you handle these errors, this can lead to an incomplete data set.
One different approach to getting the data is to get only the issues that were created/updated since the last execution time. In order to achieve this, you could sort the data by Last Modification Date (descending order), and then stop retrieving the issues once the "last modification date" is less than the last time the query ran.
This way is much more efficient since you would be getting only a subset of the data, which in turn can be updated in your own data storage.