Public API v1.0 Documentation
Draft: October 22, 2014
Contents
Introduction ................................................................................................................................ 5
How to get your API Key ........................................................................................................ 5
Date format ............................................................................................................................ 5
Authentication......................................................................................................................... 6
POD Specific domain urls ....................................................................................................... 6
Exceptions .............................................................................................................................. 6
Notes ...................................................................................................................................... 6
APIs ........................................................................................................................................... 7
Authentication......................................................................................................................... 7
Access Token Based .......................................................................................................... 7
Cookie based ...................................................................................................................... 8
Project .................................................................................................................................... 9
List of Project Locations ...................................................................................................... 9
List of Projects .................................................................................................................... 9
Get Project Info ..................................................................................................................10
Create Projects ..................................................................................................................11
Folder ....................................................................................................................................11
Folder contents ..................................................................................................................11
Folder contents by path......................................................................................................13
Create Folder .....................................................................................................................13
Get Folder Details ..............................................................................................................14
Get Folder versions............................................................................................................14
Rename Folder ..................................................................................................................15
Delete Folder .....................................................................................................................15
File ........................................................................................................................................16
Upload File.........................................................................................................................16
Get File Details ..................................................................................................................16
Get File versions ................................................................................................................17
Download File ....................................................................................................................18
Checkout Files ...................................................................................................................18
Checkin Files .....................................................................................................................19
Rename File ......................................................................................................................19
Delete File..........................................................................................................................20
ToDo .....................................................................................................................................21
List of ToDos......................................................................................................................21
Create ToDo ......................................................................................................................22
Comment...............................................................................................................................23
List of Comments ...............................................................................................................23
Create Comment................................................................................................................24
Edit Comment ...................................................................................................................25
Delete Comment ................................................................................................................25
Release .................................................................................................................................26
List of Releases .................................................................................................................26
Get Releases details ..........................................................................................................26
List of Release Files ...........................................................................................................27
Model ....................................................................................................................................27
Get Model Alignment .........................................................................................................27
Set Model Alignment ..........................................................................................................28
B. Public 3D Viewer APIs (Token based) ..................................................................................31
1. Prerequisites: SSL Server Setup .........................................................................................31
2. Authentication ...................................................................................................................34
3. Instantiating the Embedded Viewer ...................................................................................36
Full example for embed viewer ..............................................................................................39
4. API List ..............................................................................................................................41
addToSelection ...................................................................................................................41
getExternalIds ....................................................................................................................41
getObjectCount ..................................................................................................................42
getObjectsRange ................................................................................................................42
getProperties ......................................................................................................................42
getSelected ........................................................................................................................43
hide ....................................................................................................................................43
highlight .............................................................................................................................43
hideType ............................................................................................................................44
getInternalIds ....................................................................................................................44
removeFromSelection .........................................................................................................45
reset ...................................................................................................................................45
selectByName .....................................................................................................................45
setMaterial .........................................................................................................................46
setSelection ........................................................................................................................46
show ..................................................................................................................................47
showType ...........................................................................................................................47
zoom ..................................................................................................................................48
5.a Glossary .......................................................................................................................48
5.b Javascript php post request code: ................................................................................50
Introduction
APIs in Trimble Connect allows one to read, write and update data into/out of the Connect
platform. Now, one can create folders, upload/download files, modify views and do much more
from within an application using Trimble Connect’s powerful API.
This document has two sections:
A. Public Server APIs (Token based)
B. Public 3D Viewer APIs (Token based)
Section A
Public Server APIs are token based REST APIs that can be used from any client and can be
exposed to the outside world or be used for systems integration/Apps etc.
Section B
Public Viewer APIs are token based JavaScript APIs can be used to manipulate the viewer which
can be embedded into any other web based application.
How to get your API Key
API key is used to generate access token to access all the Trimble Connect APIs. This key is
based on your account email and does not change or expire. To generate this key you must
first sign in to Trimble Connect. Another option for authentication is to use cookie based sync
login API rather than logging in directly to Trimble Connect.
Use your credentials or signup for a new account: https://app.prod.gteam.com/gteam/app
After signing in, copy this URL in the same browser address bar you signed in and get your API
Key
URL
GET
https://app.prod.gteam.com/gteam/app/useraccounts/me/apikey
EXAMPLE RESPONSE
1. {
2.
3. }
"key": "lpv5XiiJnD1XaCPvFW1QIU4tZFd1akpOUVhBOlFRckxtsk9qUm9Z"
Date format
The date value used in the APIs is expressed as Unix epoch timestamp. All dates are in UTC.
EXAMPLE: 1410412870000
Authentication
To use the public APIs, you will need to add the “Authorization” header to your requests.
Authorization
Bearer access_token
Replace “access_token” with the value you get from the /auth API request explained below
POD Specific domain urls
Use the “origin” field value from the /regions API to determine the host URL for the API calls for
specific POD of the project.
Exceptions
The APIs return JSON responses for most of the APIs on success. In case of exceptions, a
JSON object is returned with error code and a message with HTTP status 409.
EXAMPLE RESPONSE
HTTP 409 Conflict
1. {
2.
3.
4. }
"message": "INVALID_SESSION",
"errorcode": "INVALID_SESSION"
Notes
-
Unless specified, all input parameters mentioned in the APIs are required
APIs
Authentication
Access Token Based
Using the API key, you can generate an access token to be used for authentication in all other
APIs. The access token is valid for 8 hours.
URL
POST
https://app.prod.gteam.com/gteam/app/1.0/auth
REQUEST BODY ATTRIBUTES
emailAddress
string
Login email address
key
string
API Key
RESPONSE ATTRIBUTES
token
string
Authentication Token
EXAMPLE REQUEST BODY
1. {
2. "emailAddress": "demouser@example.com",
3. "key" : "wJVOlWAgR5ZncCZBOTTN6kR5Znc0ODFmRTlVOlFRckxtak9qUm9Z"
4. }
EXAMPLE SUCCESS RESPONSE
HTTP 200 OK
1. {
2.
"token": "eyJhbGciOiJIUzI1NiJ9.eyJleHAiOjE0MTE2MjYyMDksInN1YiI6IlFRckxtak9qUm9ZIiwi
dXNlcklkIjoiTS1kV3VqSk5RWEEiLCJpc3MiOiInYXBpLmd0ZWFtLmNvbSciLCJqdGkiOiJEeWZ3NDgxZkU5VSI
sInNJZCI6IlVOSUpISjh4VXpBIiwiaWF0IjoxNDExNTk3NDA5fQ.roDQ7ingV4egNPNktyFye11RL9hLXtiRwqJfFv-ztk"
3. }
Cookie based
Use this API to simulate cookie based login, which can be used with all further API calls and in
this case you do not need API key.
URL
POST
https://app.prod.gteam.com/gteam/app/sync/login/password_based
REQUEST BODY ATTRIBUTES
emailAddress
string
Login email address
password
string
User password
EXAMPLE REQUEST BODY
1. {
2. "emailAddress": "demouser@example.com",
3. "password" : "xxxxxxxx"
4. }
EXAMPLE SUCCESS RESPONSE
HTTP 200 OK with cookies
Project
List of Project Locations
Returns list of project locations. The “origin” value is used to determine the base URL for
subsequent APIs. This is called on the master pod.
URL
GET
https://app.prod.gteam.com/gteam/app/1.0/regions
RESPONSE ATTRIBUTES
pod
integer
Pod Id
isMaster
boolean
Boolean to indicate if the pod is the master pod
origin
string
Base URL to access the pod (Add protocol to the value)
location
string
Pod location
EXAMPLE SUCCESS RESPONSE
1. [
2.
3.
4.
5.
6.
7.
8.
9.
10.
11.
12.
13.
14. ]
{
"podId": "Dyfw481fE9U",
"isMaster": true,
"origin": "//app.prod.gteam.com",
"location": "northAmerica"
},
{
"podId": "pNCBBwArq-g",
"isMaster": false,
"origin": "//app.prod.gteam.com",
"location": "europe"
}
List of Projects
Returns a list of projects from the project location (defined by “origin”)
URL
GET
https:<origin>/gteam/app/1.0/projects
RESPONSE ATTRIBUTES
Id
string
Project Identifier
Name
string
Project name
rootId
string
Root folder Identifier for the project
Image
string
Project image URL
Location
string
Project location
lastVisited
date
Timestamp of last visit by the user making the request
Modified
date
Timestamp of last modification by any user
Created
date
Timestamp when the project was created
createdBy
object
User that created the project
Size
string
Total project size
noOfFiles
integer
Total number of files in project
noOfVersions
integer
Total number of versions across all files/folders in the project
noOfUsers
integer
Total number of users in the project
EXAMPLE SUCCESS RESPONSE
1. [
2.
3.
4.
5.
6.
7.
8.
9.
10.
11.
12.
13.
14.
15.
16.
17.
18.
19.
20.
21. ]
{
"id": "M-dWujJNQXA",
"name": "Demo project",
"rootId": "tadQfUkLbrU",
"image": "/gteam/static/img/icons/no_projects_light_110.png",
"location": “northAmerica”,
"lastVisited": 1410412870000,
"modified": 1396485986000,
"created": 1396485986000,
"createdBy": {
"id": "M-dWujJNQXA",
"name": "imti gt-global s",
"email": "imti@gt-global.com"
},
"size": "10.38 MB",
"noOfFiles": 5,
"noOfVersions": 5,
"noOfUsers": 2
}
Get Project Info
URL
GET
https:<origin>/gteam/app/1.0/projects/<projectId>?fullyLoaded=<fullyLoaded>
PATH PARAMETERS
string
projectId
Project Identifier
QUERY PARAMETERS
fullyLoaded
boolean
Boolean to fetch additional details [size, noOfFiles,
noOfVersions, noOfUsers]
RESPONSE ATTRIBUTES
See here [Response Attributes for Project content API]
EXAMPLE SUCCESS RESPONSE
See here [Response Attributes for Project content API]
Create Projects
URL
GET
https:<origin>/gteam/app/1.0/projects
REQUEST BODY ATTRIBUTES
name
string
Project name
RESPONSE ATTRIBUTES
See here [Response Attributes for Project content API]
EXAMPLE SUCCESS RESPONSE
See here [Response Attributes for Project content API]
Folder
Folder contents
Returns a list of folders and files in a given folder
URL
GET
https:<origin>/gteam/app/1.0/folders/<folderId>/children?projectId=<projectId>
Optional
PATH PARAMETERS
string
folderId
Folder identifier to fetch children for
QUERY PARAMETERS
string
projectId
Project identifier
RESPONSE ATTRIBUTES
id
string
Folder Identifier
versionId
string
Version identifier
name
string
Folder name
projectId
string
Project identifier
parentVersionId
string
Parent folder version identifier
parentId
string
Parent folder identifier
hasChildren
boolean
Boolean value indicating if folder is empty
type
string
Type of object (Valid values are [‘FILE’, ‘FOLDER’])
modified
date
Timestamp of last modification by any user
modifiedBy
object
User that last modified the folder
createdOn
date
Folder creation timestamp
createdBy
object
User that created the project
size
string
Folder size
thumbnailUrl
string
Image URL
EXAMPLE SUCCESS RESPONSE
1. [
2.
3.
4.
5.
6.
7.
8.
9.
10.
11.
12.
13.
14.
{
"id": "3cIuFv8lfic",
"versionId": "3cIuFv8lfic",
"name": "Documents",
"projectId": "upZz8FMYa6k",
"parentVersionId": "xrHjrY6muOc",
"parentId": "xrHjrY6muOc",
"hasChildren": true,
"type": "FOLDER",
"modified": 1401231929000,
"modifiedBy": {
"id": "W1G1WjZPULI",
"name": "Karthik R",
15.
16.
17.
18.
19.
20.
21.
22.
23.
24.
25.
26.
27.
28. ]
"email": "krajagopal@gt-global.com"
},
"createdBy": {
"id": "W1G1WjZPULI",
"name": "Karthik R",
"email": "krajagopal@gt-global.com"
},
"createdOn": 1401231929000,
"size": "3.31 MB",
"thumbnailUrl": [
"/gteam/static/img/icons/folder_60.png"
]
}
Folder contents by path
Returns a list of folders and files in a given folder
URL
GET
https:<origin>/gteam/app/1.0/folders/by_path?projectId=<projectId>&path=<path>
QUERY PARAMETERS
path
string
Folder path, starting with root folder (Ex: /samples/3dfiles)
projectId
string
Project identifier
RESPONSE ATTRIBUTES
See here [Response Attributes for Folder content API]
Create Folder
URL
POST
https:<origin>/gteam/app/1.0/folders
REQUEST BODY ATTRIBUTES
name
string
Folder name
parentId
string
Parent folder identifier
projectId
string
Project Identifier
RESPONSE ATTRIBUTES
See here [Response Attributes for Folder content API]
EXAMPLE SUCCESS RESPONSE
See here [Response Attributes for Folder content API]
Get Folder Details
Fetch details of the specified versionId
URL
GET
https:<origin>/gteam/app/1.0/folders/<versionId>?projectId=<projectId>
PATH PARAMETERS
versionId
string
Folder identifier
QUERY PARAMETERS
projectId
string
Project Identifier
RESPONSE ATTRIBUTES
See here [Response Attributes for Folder content API]
EXAMPLE SUCCESS RESPONSE
See here [Response Attributes for Folder content API]
Get Folder versions
Fetch all versions of the specified versionId
URL
GET
https:<origin>/gteam/app/1.0/folders/<versionId>/versions?projectId=<projectId>
PATH PARAMETERS
versionId
string
QUERY PARAMETERS
Folder Identifier
string
projectId
Project Identifier
RESPONSE ATTRIBUTES
See here [Response Attributes for Folder content API]
EXAMPLE SUCCESS RESPONSE
See here [Response Attributes for Folder content API]
Rename Folder
Rename a folder given the latest versionId
URL
POST
https:<origin>/gteam/app/1.0/folders/rename
REQUEST BODY ATTRIBUTES
name
string
Folder name
id
string
Folder identifier
versionId
string
Version identifier
projectId
string
Project Identifier
RESPONSE ATTRIBUTES
See here [Response Attributes for Folder content API]
EXAMPLE SUCCESS RESPONSE
See here [Response Attributes for Folder content API]
POSSIBLE RESPONSE CODES
INVALID_OPERATION_OLD_REVISION
If versionId specified is not latest versionId
Delete Folder
URL
DELETE
https:<origin>/gteam/app/1.0/folders/<folderId>
PATH PARAMETERS
string
folderId
Folder Identifier
EXAMPLE SUCCESS RESPONSE
HTTP 204 No Content
File
Upload File
URL
POST
https:<origin>/gteam/app/1.0/files?parentId=<parentId>&projectId=<projectId>
QUERY PARAMETERS
projectId
string
Project identifier
parentId
string
Parent folder identifier
REQUEST BODY ATTRIBUTES
filename
string
File name
This is a multi-part request body, add the following header
Content-Type
multipart/form-data
RESPONSE ATTRIBUTES
See here [Response Attributes for Folder content API]
EXAMPLE SUCCESS RESPONSE
See here [Response Attributes for Folder content API]
Get File Details
Fetch details of the specified versionId
URL
GET
https:<origin>/gteam/app/1.0/files/<versionId>?projectId=<projectId>
PATH PARAMETERS
versionId
string
File identifier
QUERY PARAMETERS
projectId
string
Project Identifier
RESPONSE ATTRIBUTES
See here [Response Attributes for Folder content API]
EXAMPLE SUCCESS RESPONSE
See here [Response Attributes for Folder content API]
Get File versions
Fetch details of the specified versionId
URL
GET
https:<origin>/gteam/app/1.0/files/<versionId>/versions?projectId=<projectId>
PATH PARAMETERS
versionId
string
File identifier to fetch versions for
QUERY PARAMETERS
projectId
string
Project Identifier
RESPONSE ATTRIBUTES
See here [Response Attributes for Folder content API]
EXAMPLE SUCCESS RESPONSE
See here [Response Attributes for Folder content API]
Download File
URL
https:<origin>/gteam/app/1.0/files?versionId=<versionId>&projectId=<projectId>
GET
QUERY PARAMETERS
projectId
string
Project identifier
versionId
string
Version identifier
This returns a stream for the file, add the following header to the request
Content-Type
application/octet-stream
RESPONSE
HTTP 200 OK
Checkout Files
URL
POST
https:<origin>/gteam/app/1.0/files/checkout
REQUEST BODY ATTRIBUTES
Array of ids of files/folders to checkout
In case of folder ids, the API will recursively checkout files under that folder
EXAMPLE REQUEST BODY
1. ["pT06-8_AzZE","LcJWPwE3YI4"]
EXAMPLE SUCCESS RESPONSE
See here [Response Attributes for File content API]
POSSIBLE RESPONSE CODES
FILE_ALREADY_CHECKED_OUT
If file is already checked out by same user
FILE_CHECKED_OUT_BY_ANOTHER_USER
If file is already checked out by another user
Checkin Files
URL
POST
https:<origin>/gteam/app/1.0/files/checkin
REQUEST BODY ATTRIBUTES
Array of ids of files/folders to check-in
In case of folder ids, the API will recursively check-in files under that folder
EXAMPLE REQUEST BODY
1. ["pT06-8_AzZE","LcJWPwE3YI4"]
EXAMPLE SUCCESS RESPONSE
See here [Response Attributes for File content API]
POSSIBLE RESPONSE CODES
FILE_NOT_CHECKED_OUT
If file is not checked out
Rename File
Rename a file given the latest versionId
URL
POST
https:<origin>/gteam/app/1.0/files/rename
REQUEST BODY ATTRIBUTES
name
string
New name
id
string
File identifier
versionId
string
Version Identifier
projectId
string
Project Identifier
RESPONSE ATTRIBUTES
See here [Response Attributes for Folder content API]
EXAMPLE SUCCESS RESPONSE
See here [Response Attributes for Folder content API]
POSSIBLE RESPONSE CODES
If versionId specified is not latest versionId
INVALID_OPERATION_OLD_REVISION
Delete File
Delete the file for the specified versionId
URL
DELETE
https:<origin>/gteam/app/1.0/files/<versionId>?projectId=<projectId>
PATH PARAMETERS
versionId
string
Version identifier
QUERY PARAMETERS
projectId
string
RESPONSE
HTTP 204 No Content
Project identifier
ToDo
List of ToDos
URL
GET
https:<origin>/gteam/app/1.0/todos?projectId=<projectId>
QUERY PARAMETERS
projectId
string
Project identifier
RESPONSE ATTRIBUTES
id
string
Todo Identifier
label
string
User friendly identifier
description
string
Description
dueDate
date
Due date
objectStatusDto
object
Object to represent Todo status (details below)
priorityDto
object
Object to represent Todo priority (details below)
modified
date
Last modification timestamp
modifiedBy
object
User that modified the Todo
created
date
Todo creation timestamp
createdBy
object
User that created the Todo
projectId
string
Project Identifier
NESTED OBJECT DETAILS
objectStatusDto –
id
string
Status label Identifier
label
string
Status value - Valid options are ["NEW", "IN_PROGRESS",
"RESOLVED", "BLOCKED", "CLOSED"]
sequence
integer
Sort order (read-only)
id
string
Status label Identifier
label
string
Status value - Valid options are ["LOW", "NORMAL ", "HIGH",
"CRITICAL"]
priorityDto –
integer
sequence
Sort order (read-only)
EXAMPLE REQUEST BODY
1. [
2.
3.
4.
5.
6.
7.
8.
9.
10.
11.
12.
13.
14.
15.
16.
17.
18.
19.
20.
21.
22.
23.
24.
25.
26.
27.
28.
29.
30.
31. ]
{
"id": "pKvW7zKEIRk",
"label": "DEMO-23",
"description": "missing column",
"dueDate": null,
"objectStatusDto": {
"id": "Dyfw481fE9U",
"label": "NEW",
"sequence": 1
},
"priorityDto": {
"id": "3UUWLWca4SQ",
"label": "HIGH",
"sequence": 6
},
"projectId": "upZz8FMYa6k",
"createdBy": {
"id": "M-dWujJNQXA",
"name": "imti gt-global s",
"email": "imti@gt-global.com"
},
"modifiedBy": {
"id": "M-dWujJNQXA",
"name": "imti gt-global s",
"email": "imti@gt-global.com"
},
"created": 1411582930000,
"modified": 1411582930000
}
Create ToDo
URL
POST
https:<origin>/gteam/app/1.0/todos
REQUEST BODY ATTRIBUTES
description
string
Description
projectId
string
Project Identifier
OPTIONAL REQUEST BODY ATTRIBUTES
dueDate
date
Due date [Example Format: 2014-10-29T07:00:00.000Z]
priorityDto
object
Object to represent Todo priority
RESPONSE ATTRIBUTES
See here [Response Attributes for Todo Listing API]
EXAMPLE SUCCESS RESPONSE
See here [Response Attributes for Todo Listing API]
Comment
List of Comments
URL
GET
https:<origin>/gteam/app/1.0/comments?projectId=<projectId>&objectId=<objectId>&objectType
=<objectType>
QUERY PARAMETERS
projectId
string
Project identifier
objectId
string
Object identifier [VersionId of File/Folder or ToDo Id, depending on
object type]
objectType
string
Object type – Valid options are ["FILE", "FOLDER ", "TODO"]
RESPONSE ATTRIBUTES
id
string
Comment Identifier
objectId
string
objectType
string
Object Identifier [VersionId of File/Folder or ToDo Id, depending
on object type]
Object type – Valid options are ["FILE", "FOLDER ", "TODO"]
description
string
Description
modified
date
Last modification timestamp
modifiedBy
object
User that modified the Comment
created
date
Comment creation timestamp
createdBy
object
User that created the Comment
EXAMPLE REQUEST BODY
1. [
2.
3.
4.
5.
6.
7.
8.
9.
10.
11.
12.
13.
14.
15.
16.
17.
18.
19.
20.
21.
22.
23.
24.
25.
26. ]
{
"id": "qiZymj5TbzY",
"description": "Image missing on page 3",
"createdBy": {
"id": "eX9gwJqSe8I",
"name": "Imtiyaz S",
"email": "imti@gt-global.com"
},
"created": 1413846301000,
"objectId": "jzdQBWZ1q5U",
"objectType": "FOLDER"
},
{
"id": "IaFXVwzc3Dk",
"description": "Good find.",
"createdBy": {
"id": "eX9gwJqSe8I",
"name": "Imtiyaz S",
"email": "imti@gt-global.com"
},
"created": 1413846298000,
"objectId": "jzdQBWZ1q5U",
"objectType": "FOLDER"
}
POSSIBLE RESPONSE CODES
OBJECT_NOT_FOUND
If object of “objectType” specified in request is not found
OBJECT_NOT_IN_PROJECT
If object of “objectType” specified in request does not belong
to specified project
UNSUPPORTED_TYPE
If “objectType” is not supported
Create Comment
URL
POST
https:<origin>/gteam/app/1.0/comments
REQUEST BODY ATTRIBUTES
description
String
Description
objectId
String
Object Identifier [VersionId of File/Folder or ToDo Id, depending on
object type]
objectType
String
Object type – Valid options are ["FILE", "FOLDER ", "TODO"]
projectId
String
Project Identifier
RESPONSE ATTRIBUTES
See here [Response Attributes for Comments Listing API]
EXAMPLE SUCCESS RESPONSE
See here [Response Attributes for Comments Listing API]
Edit Comment
URL
PATCH
https:<origin>/gteam/app/1.0/comments
REQUEST BODY ATTRIBUTES
description
string
Description
id
string
Comment Identifier
projectId
string
Project Identifier
RESPONSE ATTRIBUTES
See here [Response Attributes for Comments Listing API]
EXAMPLE SUCCESS RESPONSE
See here [Response Attributes for Comments Listing API]
Delete Comment
URL
DELETE
https:<origin>/gteam/app/1.0/comments/<commentId>
PATH PARAMETERS
commentId
RESPONSE
string
Comment Identifier
HTTP 204 No Content
Release
List of Releases
URL
GET
https:<origin>/gteam/app/1.0/releases?status=<releaseStatus>&projectId=<projectId>
QUERY PARAMETERS
projectId
string
Project Identifier
Required
status
string
Release status - Valid options are ["OPEN", "SENT",
"RECEIVED"]. If excluded, will return all statuses
Optional
RESPONSE ATTRIBUTES
id
string
Release Identifier
name
string
Release name
status
string
Status value - Valid options are ["OPEN", "SENT",
"RECEIVED"]
projectId
string
Project identifier
notes
string
Release notes
dueDate
date
Release due date
recipients
array
List of user objects
createdBy
object
User that created the release
created
date
Release creation timestamp
modifiedBy
object
User that modified the release
modified
date
Release modification timestamp
Get Releases details
URL
GET
https:<origin>/gteam/app/1.0/releases/<releaseId>?projectId=<projectId>
PATH PARAMETERS
releaseId
string
Release Identifier
projectId
string
Project Identifier
RESPONSE ATTRIBUTES
See here [Response Attributes for Releases Listing API]
EXAMPLE SUCCESS RESPONSE
See here [Response Attributes for Releases Listing API]
List of Release Files
Returns list of files included in the release
URL
GET
https:<origin>/gteam/app/1.0/releases/files?projectId=<projectId>&releaseId=<releaseId>
QUERY PARAMETERS
projectId
string
Project Identifier
releaseId
string
Release Identifier
RESPONSE ATTRIBUTES
See here [Response Attributes for File content API]
EXAMPLE SUCCESS RESPONSE
See here [Response Attributes for File content API]
Model
Get Model Alignment
Get the alignment for the specified versionId
URL
GET
https:<origin>/gteam/app/1.0/ model/align/<versionId>
PATH PARAMETERS
string
versionId
File identifier
RESPONSE ATTRIBUTES
id
string
Model offset id.
matrix
Array of
double
Row major 4x4 transformation matrix.
Model unit is mm.
EXAMPLE RESPONSE BODY
1. {
2.
3.
4.
5.
6.
7.
8.
9.
10.
11.
12.
13.
14.
15.
16.
17.
18.
19.
20.
21. }
"id": "Skd-09NiKrg",
"matrix": [
0.999999,
-0.000781397,
0.00117874,
25.4,
0.000999999,
0.980066,
-0.198668,
50.8,
-0.001,
0.198669,
0.980066,
101.6,
0,
0,
0,
1
]
Set Model Alignment
Set the alignment for the specified versionId
URL
POST
https:<origin>/gteam/app/1.0/model/align/<versionId>
PATH PARAMETERS
versionId
String
File identifier
RESPONSE ATTRIBUTES
id
String
Model offset id.
Array of
double
matrix
Model unit is mm.
EXAMPLE REQUEST BODY
1. {
2.
3.
4.
5.
6.
7.
8.
9.
10.
11.
12.
13.
14.
15.
16.
17.
18.
19.
20. }
"matrix": [
0.999999,
-0.000781397,
0.00117874,
25.4,
0.000999999,
0.980066,
-0.198668,
50.8,
-0.001,
0.198669,
0.980066,
101.6,
0,
0,
0,
1
]
EXAMPLE RESPONSE BODY
1. {
2.
3.
4.
5.
6.
7.
8.
9.
10.
11.
12.
13.
14.
15.
16.
17.
18.
19.
20.
21. }
"id": "Skd-09NiKrg",
"matrix": [
0.999999,
-0.000781397,
0.00117874,
25.4,
0.000999999,
0.980066,
-0.198668,
50.8,
-0.001,
0.198669,
0.980066,
101.6,
0,
0,
0,
1
]
Row major 4x4 transformation matrix.
B. Public 3D Viewer APIs (Token based)
Public Viewer APIs are token based JavaScript APIs can be used to manipulate the viewer which
can be embedded into any other web based application.
1. Prerequisites: SSL Server Setup
Enabling SSL on Apache [SSL is required for Trimble Connect API use]
This tutorial uses XAMPP version 3.2.x
1.a.1. Install XAMPP Server
XAMPP URL: https://www.apachefriends.org/index.html
1.a.2. Open the following file in a plain text editor such as notepad or gedit [not Excel]:
C:\xampp\apache\makecert.bat
1.a.3. Change the second line in the file from:
set OPENSSL_CONF=./bin/openssl.cnf
to:
set OPENSSL_CONF=./conf/openssl.cnf
1.a.4. Open the windows command prompt [or the terminal if using OSX or GNU Linux]
1.a.5. In the command prompt, point to the Apache installation folder by entering the
following command:
cd C:\xampp\apache
1.a.6. Create a new SSL certificate by entering the following command:
makecert
* Enter values when prompted.
* The 'Common Name' should be the domain name or IP address of the XAMPP server.
* For local testing, 'localhost' can be entered.
* The 'challenge password' is an optional entry that can be left blank if preferred.
1.a.7. Enter the following text into the file 'C:\xampp\apache\conf\extra\httpdxampp.conf' at the top line:
<IfModule mod_rewrite.c>
RewriteEngine On
# Redirect -xampp folder to https
RewriteCond %{HTTPS} !=on
RewriteCond %{REQUEST_URI} xampp
RewriteRule ^(.*) https:--%{SERVER_NAME}$1 [R,L]
# Redirect -phpMyAdmin folder to https
RewriteCond %{HTTPS} !=on
RewriteCond %{REQUEST_URI} phpmyadmin
RewriteRule ^(.*) https:--%{SERVER_NAME}$1 [R,L]
# Redirect -security folder to https
RewriteCond %{HTTPS} !=on
RewriteCond %{REQUEST_URI} security
RewriteRule ^(.*) https:--%{SERVER_NAME}$1 [R,L]
# Redirect -webalizer folder to https
RewriteCond %{HTTPS} !=on
RewriteCond %{REQUEST_URI} webalizer
RewriteRule ^(.*) https:--%{SERVER_NAME}$1 [R,L]
</IfModule>
1.a.8. In the file 'C:\xampp\apache\conf\httpd.conf,'
search for the text 'LoadModule rewrite_module modules/mod_rewrite.so'
and check that there is no pound # sign in front of it.
The line should read: LoadModule rewrite_module modules/mod_rewrite.so
and not: #LoadModule rewrite_module modules/mod_rewrite.so
1.a.9. Go to the Windows start menu and search for 'certmgr.msc'
1.a.10. In the CertMgr menu, click on 'Trusted Root Certification Authorities'
1.a.11. Right-click on 'Certificates' listed in the 'Object Type' list, and select 'All Tasks >
Import'
1.a.12. Browser to the folder 'C:\xampp\apache\conf\ssl.crt,' select the file 'server.crt,'
and click 'open'.
1.a.13. Accept default settings when clicking through the file import menu.
1.a.14. Close the CertMgr tool [Click File > Exit]
1.a.15. Start XAMPP server and click 'Start' in the Actions list next to 'Apache'
1.a.16. Check https://localhost/ in a web browser to verify that SSL is set up.
2. Authentication
2.a. Log into Trimble Connect.
2.b. Go to https://app.prod.gteam.com/gteam/app/useraccounts/me/apikey to retrieve your
API key.
2.c. Retrieve an access token to use when making API calls.
Access tokens can be retrieved by sending a post request to the URL:
https://app.prod.gteam.com/gteam/app/1.0/auth
The following PHP sample code performs a POST request to retrieve an API key.
$url = https://app.prod.gteam.com/gteam/app/1.0/auth";
$data = array(
'emailAddress'
'key'
);
=> "youruseraccountemail@domain.com",
=> "Z-hf79kjhty79Hhfj84Dhy3HJYyf6580kHTR6gu8"
$options = array(
'http' => array(
'method' => 'POST',
'content' => json_encode( $data ),
'header'=> "Content-Type: application/json\r\n" . "Accept: application/json\r\n"
)
);
$context = stream_context_create( $options );
$result = file_get_contents( $url, false, $context );
$response = json_decode( $result );
echo $response->token;
The access token will look similar to the following string:
eyJhbGciOiJIUzI1NiJ9.eyJhfi6YHITYsInN1YiI6IlFRckxtak9qUm9ZIiwid
XNlcklkIjoiZUJBdzA3NEIyVmciLCJpc3MiOiInYXBpLmd0ZWFtLmNvb
SciLCJqdGkiOiJxMkk3ZHdEV3JuTSIsInNJZCI6IkhONDhkX2FxVmtN
IiwiaWF0IjoxNDA2NzY3Mzk2fQ.DgxYhi8f4TVviykDBBVQ
The PHP code above, placed within a php file, should be called to retrieve an access token
before proceeding to step 3 below.
The php file can be called with an ajax post, or other method.
See Appendix item 5.b for sample code.
3. Instantiating the Embedded Viewer
3.a. Include the following javascript file:
https://app.prod.gteam.com/gteam/static/gteam/viewer/embed.js
3.b. Specify a DOM node to embed the Trimble Connect viewer.
var ViewerNode = document.getElementById("GTeamViewer");
3.c. Specify the embedded viewer's configuration.
This can be done by using a javascript array as described below:
var viewer_data = { "domNode": node
, "title": "Viewer Title to Display on Web Page"
, "noProperties": false
, "noLeft": false
, "debug": true
, "height": 850
, "width": 1500
, "gteamOrigin" : encodeURIComponent("https://app.prod.gteam.com")
, "projId" : "Dyfw481fE9U"
, "objects" : "M-dWujJNQXA"
, "mashup" : "Dyfw481fE9U"
, "accessToken" : accessTokenString
, "class" : "embeddedViewFrame"
, "onInitialized": function() { optional: place code here } //callback function to run code
on viewer load
};
See Appendix item 5.a for embedded viewer parameter definitions.
3.c.2. Retrieving the Project ID
Log into Trimble Connect, and within the project display the file within the Trimble Connect
viewer.
The extract the Project ID from the page URL
https://app.prod.gteam.com/gteam/app/#project,viewer&id=BYRvifmFaUk&mashup=3d9LXbVD
Cqs&objects=X6Uw9Wd7kz8
project,viewer&id=BYRvifmFaUk
BYRvifmFaUk
3.c.3. Retrieving the Objects ID
https://app.prod.gteam.com/gteam/app/#project,viewer&id=BYRvifmFaUk&mashup=3d9LXbVD
Cqs&objects=X6Uw9Wd7kz8
objects=X6Uw9Wd7kz8
X6Uw9Wd7kz8
3.c.4. Retrieving the Mashup ID
https://app.prod.gteam.com/gteam/app/#project,viewer&id=BYRvifmFaUk&mashup=3d9LXbVD
Cqs&objects=X6Uw9Wd7kz8
mashup=3d9LXbVDCqs
3d9LXbVDCqs
3.d. Create an instance of the Trimble Connect embedded viewer
var viewer = new EmbeddedViewer(viewer_data);
Full example for embed viewer
<html>
<head>
<title>Trimble Connect</title>
</head>
<body>
<div id="TrimbleConnectViewer"></div>
<script type="text/javascript"
src="https://app.prod.gteam.com/gteam/static/gteam/viewer/embed.js"></script>
<script>
var ViewerNode = document.getElementById("TrimbleConnectViewer ");
var viewer_data = { "domNode": ViewerNode
, "title": "Trimble Connect Embedded Viewer"
, "noProperties": false
, "noLeft": true
, "debug": true
, "height": 850
, "width": 1500
, "gteamOrigin" : encodeURIComponent("https://app.prod.gteam.com")
, "projId" : "ProjectId"
, "objects" : "versionId"
, "accessToken" : "token"
, "class" : "embeddedViewFrame"
, "onInitialized": function() {if (window.output) { output.write("API ready"); }}
//callback function to run code on viewer load
};
var viewer = new EmbeddedViewer(viewer_data);
</script>
</body>
</html>
4. API List
The following API calls are available for use with the Embedded Viewer:
API calls that request data will receive the data within a callback function
addToSelection
Description
Append objects to the current selection
API
viewer.addToSelection(str_arr,bl_recrsv);
Input Parameters
Input 1: String array of external object IDs
Input 2: Boolean true/false for retrieval of nested objects within the specified objects
Output
None
getExternalIds
Description
Get the collection of external IDs corresponding to a string array of internal IDs.
API
viewer.getExternalIds(str_arr,callback);
Input Parameters
Input 1: String array of internal object IDs
Input 2: A callback function with 1 argument, e.g. function(stringArrayResult){ }
Output
Callback function containing returned string array
getObjectCount
Description
Get the total number of objects loaded in the viewer
API
viewer.getObjectCount(callback);
Input Parameters
Input: A callback function with 1 argument, e.g. function(integerResult){ }
Output
Callback function containing returned integer
getObjectsRange
Description
Get an array of external IDs for objects within the specified index range
API
viewer.getObjectsRange(int_from,int_to,callback);
Input Parameters
Input 1: The starting index [integer] of the collection of object IDs to retrieve
Input 2: The ending index [integer] of the collection of object IDs to retrieve
Output
Callback function containing a string array of external IDs
getProperties
Description
Get the properties of objects specified in a string array of external IDs
API
viewer.getProperties(str_arr,callback);
Input Parameters
Input 1: A string array of external IDs
Input 2: A callback function with 1 argument, e.g. function(stringArrayResult){ }
Output
Callback function containing a string array of external IDs
getSelected
Description
Get the collection of currently selected objects
API
viewer.getSelected(callback);
Input Parameters
Input: A callback function with 1 argument, e.g. function(stringArrayResult){ }
Output
Callback function containing a string array of external IDs
hide
Description
Hide the specified objects
API
viewer.hide(str_arr);
Input Parameters
Input: A string array of external IDs
Output
None
highlight
Description
Highlight the specified objects
API
viewer.highlight(str_arr,bl_recrsv);
Input Parameters
Input 1: A string array of external IDs
Input 2: Boolean true/false for highlighting of nested objects within the specified objects
Output
None
hideType
Description
Hide all objects of the specified type within the viewer [Walls, Doors, etc]
API
viewer.hideType(str_type);
Input Parameters
Input: String name of object type
Output
None
getInternalIds
Description
Get the collection of internal IDs corresponding to a string array of external IDs
API
viewer.getInternalIds(str_arr,callback);
Input Parameters
Input 1: A string array of external IDs
Input 2: A callback function with 1 argument, e.g. function(stringArrayResult){ }
Output
Callback function containing a string array of internal IDs
removeFromSelection
Description
Remove specified objects from the current selection
API
viewer.removeFromSelection(str_arr,bl_recrsv);
Input Parameters
Input 1: A string array of external IDs
Input 2: Boolean true/false for removing nested objects within the specified objects
Output
None
reset
Description
Reset object visibility, object selection, and camera position
API
viewer.reset();
Input Parameters
Input: None
Output
None
selectByName
Description
Select object by name
API
viewer.selectByName(str_name,bl_recrsv);
Input Parameters
Input 1: The string name of the object to select
Input 2: Boolean true/false for selecting nested objects within the specified object
Output
None
setMaterial
Description
Set the material property in Trimble Connect for the specified objects
API
viewer.setMaterial(str_arr,str_material,bl_recrsv);
Input Parameters
Input 1: A string array of external IDs
Input 2: The string name of the material to set
Input 3: Boolean true/false for applying material to nested objects within the specified object
Output
None
setSelection
Description
Select a specified set of objects, and clear the prior selection if any.
API
viewer.setSelection(str_arr,bl_recrsv);
Input Parameters
Input 1: A string array of external IDs
Input 2: Boolean true/false for selecting nested objects within the specified objects
Output
None
show
Description
Show the specified objects within the viewer
API
viewer.show(str_arr);
Input Parameters
Input 1: A string array of external IDs
Output
None
showType
Description
Show all objects of the specified type within the viewer [Walls, Doors, etc]
API
viewer.showType(str_type);
Input Parameters
Input: String name of object type
Output
None
zoom
Description
Zoom to the specified objects within the viewer
API
viewer.zoom(str_arr);
Input Parameters
Input 1: A string array of external IDs
Output
None
5. Appendix
5.a Glossary
Embedded Viewer Parameters:
title
//viewer title to display on web page
noProperties
//display properties panel
noLeft
//display left panel
debug
//output debug messages
height
//viewer height
width
//viewer width
gteamOrigin
//Trimble Connect home page URL
projId
//Project ID - refer to 2.c.2.
objects
//Objects ID - refer to 2.c.3.
mashup
//Mashup ID - refer to 2.c.4.
accessToken //access token string
class
//object class name
onInitialized
//callback function
External ID
The external ID is the unique ID of each object that is assigned to it by Trimble Connect.
The external ID of each object is unique for each file revision.
The external ID is used to identify objects within a specific revision of a file.
Internal ID
The internal ID is the unique ID of each object that is assigned to it by its authoring
environment.
This ID is usually persists through file revisions for objects that are unmodified.
5.b Javascript php post request code:
The sample code below uses a jquery http://jquery.com/ ajax post to call a php file.
$.ajax({
type: 'POST',
url: 'auth/get_actkn.php',
async: false,
success: function(result){
console.log("Access Token = " + result);
},
error: function(){
}
});
The sample code below uses a dojo http://dojotoolkit.org/ javascript post to call a php file.
define([
"dojo/_base/declare","dojo/request"
], function(declare, request){
return declare(null, {
getAccessToken: function() {
return request.post("auth/get_actkn.php", {
}).then(function(result) {
return result; //the access token is returned here
});
}
});
});