Get started with RealityData API

Introduction
The RealityData API provides you the ability to manage and share reality models. This tutorial will help you get started using the RealityData API.
This tutorial will guide you through:
- Creating, modifying and deleting RealityData.
- Associating and dissociating a RealityData to a Project.
- Uploading and downloading reality models to RealityData.
Prerequisites
- A reality model, such as a
.3mx
file. - Project created.
- To learn more, see the create and query projects guide.
- To learn more, see the create and query projects guide.
1. Register an Application
You will need to register an application to use the iTwin Platform APIs. For this tutorial, a Desktop/Mobile Application is recommended. You can use the Register button to automatically create your first Desktop/Mobile application. This allows you to configure Authorization Code Flow for your Desktop/Mobile application and get the correct access token.
Once generated, a few lines of code is displayed under the button.
- IMJS_AUTH_CLIENT_CLIENT_ID - the unique identifier for your application. It is displayed on application details page as Client ID.
- IMJS_AUTH_CLIENT_REDIRECT_URI - specifies where users are redirected after they have chosen whether or not to authenticate your app. It is displayed on application details page as one of Redirect URIs.
- IMJS_AUTH_CLIENT_LOGOUT_URI - specifies where to return users after logging out. It is displayed on the application details page as one of Post logout redirect URIs.
- IMJS_AUTH_CLIENT_SCOPES - list of accesses granted to the application. It is displayed on the application details page as Scopes.
Or optionally: Register and configure your application manually following instructions in Register and modify an Application tutorial. Select the Digital Twin Management and Visualization API associations and verify that the following scopes are present under Allowed scopes :
realitydata:read realitydata:modify
2. Get a Token
To make request to the API, a user token is needed. There are several ways to get it. You can consult the Authorization API documentation here, and you can use a sample powershell script here to use in your app.
3. Create a RealityData
While using the RealityData API, you will mainly work with RealityData
objects. The class defines properties that describe the content of the
reality data and provides an access point to the data stored in a blob container, using Microsoft Azure Storage technologies.
RealityData
properties represent the descriptive data related to a reality data. In addition to this, reality data content is stored as files and folders within a blob container uniquely associated to this reality data.
Individual files and folders follow, from the root of the reality data, a normal file tree structure.
Use a POST https://api.bentley.com/realitydata
HTTP request to create a RealityData
.
Currently, the required properties for creating a RealityData
are:
DisplayName
: Name of the RealityDataClassification
e.g. “Model”Type
e.g. “3mx”
Upon successfully creating a RealityData
, the id
property will be generated, and it is used as it’s unique identifier.
Example HTTP Request for POST RealityData Operation
POST https://api.bentley.com/realitydata HTTP/1.1 Authorization: Bearer JWT_TOKEN Accept: application/vnd.bentley.v1+json Content-Type: application/json { "projectId": "d8414d06-560e-49da-81a5-f7204fa4457b", "realityData": { "displayName": "Name of the reality data to create", "classification": "Model", "type": "3mx", "description": "Description of the reality data", "dataset": "Dataset", "group": "GroupId", "rootDocument": "Models/Scene/myModel.3mx", "acquisition": { "startDateTime": "2021-05-12T20:03:12Z", "endDateTime": "2021-05-15T05:07:18Z", "acquirer": "Data Acquisition Inc." }, "extent": { "southWest": { "latitude": 40.0206, "longitude": -75.6355 }, "northEast": { "latitude": 40.0356, "longitude": -75.6059 } }, "authoring": false } } }
Example Response Headers
HTTP/1.1 201 Created Content-Length: 112 Request-Context: appId=cid-v1:7a353d36-9a8b-423e-965e-9d7f51324584 x-correlation-id: 2b59e2ac-3e89-42bf-9678-2717b395c5bf X-ITwinPlatform-Media-Type: bentley.itwin-platform.v1 X-ITwinPlatform-Region: East US Date: Mon, 04 Oct 2021 20:51:49 GMT
Example Response Body
{ "realityData": { "id": "95d8dccd-d89e-4287-bb5f-3219acbc71ae", "displayName": "Name of the reality data to create", "dataset": "Dataset", "group": "GroupId", "description": "Description of reality data", "rootDocument": "Models/Scene/myModel.3mx", "size": 0, "classification": "Model", "type": "3mx", "acquisition": { "startDateTime": "2021-05-12T20:03:12Z", "endDateTime": "2021-05-15T05:07:18Z", "acquirer": "Data Acquisition Inc." }, "extent": { "southWest": { "latitude": 40.0206, "longitude": -75.6355 }, "northEast": { "latitude": 40.0356, "longitude": -75.6059 } }, "authoring": false, "accessControl": "Project", "dataCenterLocation": "North Europe", "modifiedDateTime": "2021-04-09T19:03:12Z", "lastAccessedDateTime": "2021-04-09T00:00:00Z", "createdDateTime": "2021-02-22T20:03:40Z" } }
Once your realityData is created, you may attach a reality model. The GET https://api.bentley.com/realitydata/{id}/container/?projectId={projectId}&access=Write
HTTP request will provide you with a SAS URL with write access.
In order to use this resource, consult the Microsoft Documentation
Alternatively, if you do not have a reality model yet and want to generate your own reality model, you may be interested in Reality Modeling
In order to visualize your Reality Model later on by using an iTwin Viewer, the created RealityData must have a valid
rootDocument
value.
Example HTTP Request for Get RealityData Container Operation
GET https://api.bentley.com//realitydata/69401bde-6200-4c6c-b783-046f1935e825/container/?projectId=615f57e7-876e-46fc-ab11-79af30cae299&access=Write HTTP/1.1 Authorization: Bearer JWT_TOKEN Accept: application/vnd.bentley.v1+json Content-Type: application/json
Example Response Headers
HTTP/1.1 200 OK Cache-Control: must-revalidate, no-cache, private Pragma: no-cache Transfer-Encoding: chunked Content-Type: application/json Content-Encoding: gzip ETag: "KtH8hBTTkTuyVh8/AjJ/wdYPRZ4=" Vary: Accept-Encoding Request-Context: appId=cid-v1:7a353d36-9a8b-423e-965e-9d7f51324584 Strict-Transport-Security: max-age=63072000 Mas-Server: Bentley-WSG/4.0.13,Bentley-WebAPI/2.9 X-Correlation-ID: dfab9114-7a6c-4cfe-bed0-c03720278dd9 Mas-Request-Id: dfab9114-7a6c-4cfe-bed0-c03720278dd9 Set-Cookie: {...} X-ITwinPlatform-Media-Type: bentley.itwin-platform.v1 X-ITwinPlatform-Region: East US Date: Mon, 04 Oct 2021 20:56:34 GMT
Example Response Body
{ "container": { "type": "AzureBlobSasUrl", "permissions": "Write", "_links": { "containerUrl": { "href": "https://realityblobdeveussa01.blob.core.windows.net/69401bde-6200-4c6c-b783-046f1935e825?sv=2020-08-04&se=2021-09-09T07%3A45%3A15Z&sr=c&sp=rl&sig=FiYaKr5m%2FPlev%2FwsOIpopyyCbJC3lbRKwhA3be2SQh8%3D" } } } }
4. Get RealityData
There are a few ways to query your RealityData. Depending on the app you are developing, one might be more useful than another. You may want to get a single RealityData or multiple ones.
Once you have created RealityData, the GET https://api.bentley.com/realitydata
request will be the route to use in order to get your created RealityData. Using this call as is will return the first 100 RealityData that you have access to, relatively to your organization’s access rights.
The GET https://api.bentley.com/realitydata/?projectId={projectId}
request will return the first 100 RealityData under the given project, relatively to the project’s access rights. provided you have access to it. A continuation token is provided for further querying.
The GET https://api.bentley.com/realitydata/{id}
request will only return the RealityData with the given identifier, provided that you have access to it.
Optional parameters are available to customize RealityData requests :
projectId
: project IdentifiercontinuationToken
to get more RealityData on the current query$top
to query a number of realityData to get in each pageextent
to query RealityData in a definite area to search.
You may refer to the RealityData API Documentation for more information on parameters described above.
When querying multiple RealiyData, the Prefer: return=representation
header will instruct the API to return all properties on every realityData. Otherwise, only minimal information
will be returned, such as id
, displayName
and type
.
Example HTTP Request for Get RealityData Operation
GET https://api.bentley.com/realitydata?projectId=ec002f93-f0c1-4ab3-a407-351848eba233&$top=2 HTTP/1.1 Authorization: Bearer JWT_TOKEN Accept: application/vnd.bentley.v1+json Prefer: return=representation Content-Type: application/json
Example Response Headers
HTTP/1.1 200 OK Cache-Control: must-revalidate, no-cache, private Pragma: no-cache Transfer-Encoding: chunked Content-Type: application/json Content-Encoding: gzip ETag: "HwjuhwwP78X3/dL8Efxr36UHJPc=" Vary: Accept-Encoding Request-Context: appId=cid-v1:7a353d36-9a8b-423e-965e-9d7f51324584 Strict-Transport-Security: max-age=63072000 Mas-Server: Bentley-WSG/4.0.13,Bentley-WebAPI/2.9 X-Correlation-ID: c6c00c24-e37e-4b30-a070-bd7e8b6090b2 Mas-Request-Id: c6c00c24-e37e-4b30-a070-bd7e8b6090b2 Set-Cookie: {...} X-ITwinPlatform-Media-Type: bentley.itwin-platform.v1 X-ITwinPlatform-Region: East US Date: Mon, 04 Oct 2021 21:01:28 GMT
Example Response Body
{ "realityData": [ { "id": "4cc193e4-07a7-4ec8-8750-93c68b34cb11", "displayName": "A random RealityData Display Name", "dataset": "Dataset", "group": "xxx", "description": "Lorem ipsum...", "rootDocument": "Graz/Scene/Graz.3mx", "size": 444055, "classification": "Model", "type": "3mx", "extent": { "southWest": { "latitude": 50.1171, "longitude": -122.9543 }, "northEast": { "latitude": 50.1172, "longitude": -122.9543 } }, "acquisition": {}, "accessControl": "Project", "dataCenterLocation": "North Europe", "modifiedDateTime": "2017-05-10T13:43:03Z", "lastAccessedDateTime": "2021-08-11T00:00:00Z", "createdDateTime": "2017-05-10T13:43:03Z" }, { "id": "a649f5f9-4c2d-4b2d-8ac0-0ba38d53727c", "displayName": "A second RealityData's Display Name", "dataset": "Dataset", "group": "xxx", "description": "Lorem ipsum...", "rootDocument": "Graz/Scene/Graz.3mx", "size": 739560, "classification": "Model", "type": "3mx", "extent": { "southWest": { "latitude": 50.1171, "longitude": -122.9543 }, "northEast": { "latitude": 50.1172, "longitude": -122.9543 } }, "acquisition": {}, "accessControl": "Project", "dataCenterLocation": "North Europe", "modifiedDateTime": "2017-05-10T13:43:03Z", "lastAccessedDateTime": "2021-08-11T00:00:00Z", "createdDateTime": "2017-05-10T13:43:03Z" } ], "_links": { "next": { "href": "https://api.bentley.com/realitydata?projectId=ec002f93-f0c1-4ab3-a407-351848eba233&continuationToken=eyJ0b3AiOjUwMCwic2tpcCI6NTAwfQ" } } }
The GET https://api.bentley.com/realitydata/{id}/container/?projectId={projectId}&permissions=Read
request will provide you with a SAS URL with read access.
This will let you download the content of your RealityData.
You may want to consult this iTwinjs sample for a quick example to display your reality model.
Example HTTP Request for Get RealityData Container Operation
GET https://api.bentley.com//realitydata/69401bde-6200-4c6c-b783-046f1935e825/container/?projectId=615f57e7-876e-46fc-ab11-79af30cae299&access=Write HTTP/1.1 Authorization: Bearer JWT_TOKEN Accept: application/vnd.bentley.v1+json Content-Type: application/json
Example Response Headers
HTTP/1.1 200 OK Cache-Control: must-revalidate, no-cache, private Pragma: no-cache Transfer-Encoding: chunked Content-Type: application/json Content-Encoding: gzip ETag: "33/0jngG83tl3Zu9AbB+KRdpL34=" Vary: Accept-Encoding Request-Context: appId=cid-v1:7a353d36-9a8b-423e-965e-9d7f51324584 Strict-Transport-Security: max-age=63072000 Mas-Server: Bentley-WSG/4.0.13,Bentley-WebAPI/2.9 X-Correlation-ID: 81cc9899-faac-4d84-9149-6bcc26460e1d Mas-Request-Id: 81cc9899-faac-4d84-9149-6bcc26460e1d Set-Cookie: {...} X-ITwinPlatform-Media-Type: bentley.itwin-platform.v1 X-ITwinPlatform-Region: East US Date: Mon, 04 Oct 2021 21:04:45 GMT
Example Response Body
{ "container": { "type": "AzureBlobSasUrl", "permissions": "Read", "_links": { "containerUrl": { "href": "https://realityblobdeveussa01.blob.core.windows.net/69401bde-6200-4c6c-b783-046f1935e825?sv=2020-08-04&se=2021-09-09T07%3A45%3A15Z&sr=c&sp=rl&sig=FiYaKr5m%2FPlev%2FwsOIpopyyCbJC3lbRKwhA3be2SQh8%3D" } } } }
5. Modify RealityData
RealityData
properties may be modified at will, provided you have sufficient permissions within the Project you are using or if you are the owner of the RealityData
.
Use a PATCH https://api.bentley.com/realitydata/{id}
HTTP request to modify an existing RealityData
.
Refer to the RealityData Properties page of the documentation for the detailed list of properties you can use and modify.
Example HTTP Request for PATCH RealityData Operation
PATCH https://api.bentley.com/realitydata/69401bde-6200-4c6c-b783-046f1935e825 HTTP/1.1 Authorization: Bearer JWT_TOKEN Accept: application/vnd.bentley.v1+json Content-Type: application/json { "projectId" : "615f57e7-876e-46fc-ab11-79af30cae299", "realityData": { "id": "69401bde-6200-4c6c-b783-046f1935e825", "displayName": "Modified displayname", "dataset": "Dataset", "group": "xxx", "description": "Lorem ipsum 2...", "classification": "Model", "type": "3mx" } } }
Example Response Headers
HTTP/1.1 200 OK Cache-Control: must-revalidate, no-cache, private Pragma: no-cache Transfer-Encoding: chunked Content-Type: application/json Content-Encoding: gzip Vary: Accept-Encoding Request-Context: appId=cid-v1:7a353d36-9a8b-423e-965e-9d7f51324584 Strict-Transport-Security: max-age=63072000 Mas-Server: Bentley-WSG/4.0.13,Bentley-WebAPI/2.9 X-Correlation-ID: 7c55d6fd-173d-4af5-a9cc-b488077442ae Mas-Request-Id: 7c55d6fd-173d-4af5-a9cc-b488077442ae Set-Cookie: {...} X-ITwinPlatform-Media-Type: bentley.itwin-platform.v1 X-ITwinPlatform-Region: East US Date: Mon, 04 Oct 2021 21:40:30 GMT
Example Response Body
{ "realityData": { "id": "69401bde-6200-4c6c-b783-046f1935e825", "displayName": "Modified displayname", "dataset": "Dataset", "group": "xxx", "description": "Lorem ipsum 2...", "size": 0, "classification": "Model", "type": "3mx", "authoring": false, "extent": { "southWest": { "latitude": 50.1171, "longitude": -122.9543 }, "northEast": { "latitude": 50.1172, "longitude": -122.9543 } }, "acquisition": {}, "accessControl": "Project", "dataCenterLocation": "North Europe", "modifiedDateTime": "2021-09-08T18:00:47Z", "lastAccessedDateTime": "2021-09-08T14:32:14Z", "createdDateTime": "2021-09-08T14:32:14Z" } }
You can refer to section 3.1 of this guide as it is the same operation, the GET https://api.bentley.com/realitydata/{id}/container/?projectId={projectId}&access=Write
request will provide you with a SAS URL with write access. From there, you may change the content of the reality model.
Example HTTP Request for Get RealityData Container Operation
GET https://api.bentley.com//realitydata/69401bde-6200-4c6c-b783-046f1935e825/container/?projectId=615f57e7-876e-46fc-ab11-79af30cae299&access=Write HTTP/1.1 Authorization: Bearer JWT_TOKEN Accept: application/vnd.bentley.v1+json Content-Type: application/json
Example Response Headers
HTTP/1.1 200 OK Cache-Control: must-revalidate, no-cache, private Pragma: no-cache Transfer-Encoding: chunked Content-Type: application/json Content-Encoding: gzip ETag: "33/0jngG83tl3Zu9AbB+KRdpL34=" Vary: Accept-Encoding Request-Context: appId=cid-v1:7a353d36-9a8b-423e-965e-9d7f51324584 Strict-Transport-Security: max-age=63072000 Mas-Server: Bentley-WSG/4.0.13,Bentley-WebAPI/2.9 X-Correlation-ID: 81cc9899-faac-4d84-9149-6bcc26460e1d Mas-Request-Id: 81cc9899-faac-4d84-9149-6bcc26460e1d Set-Cookie: {...} X-ITwinPlatform-Media-Type: bentley.itwin-platform.v1 X-ITwinPlatform-Region: East US Date: Mon, 04 Oct 2021 21:04:45 GMT
Example Response Body
{ "container": { "type": "AzureBlobSasUrl", "permissions": "Write", "_links": { "containerUrl": { "href": "https://realityblobdeveussa01.blob.core.windows.net/69401bde-6200-4c6c-b783-046f1935e825?sv=2020-08-04&se=2021-09-09T07%3A45%3A15Z&sr=c&sp=rl&sig=FiYaKr5m%2FPlev%2FwsOIpopyyCbJC3lbRKwhA3be2SQh8%3D" } } } }
6. Manage RealityData Relations to Multiple Projects
Depending on the purpose of your reality model, you may find useful to have your reality model, therefore it’s RealityData
, to be available across multiple projects.
The RealityData
API leverages the strengths of the Projects API to make your model available to others.
Two actions are possible:
- Associating a RealityData to a Project
- Dissociating a RealityData to a Project
The PUT https://api.bentley.com/realitydata/{id}/projects/{projectId}
http request will add an association to the desired project, illustrated by projectAssociation
.
Example HTTP Request for Associate RealityData Operation
PUT https://api.bentley.com/realitydata/69401bde-6200-4c6c-b783-046f1935e825/projects/615f57e7-876e-46fc-ab11-79af30cae299 HTTP/1.1 Authorization: Bearer JWT_TOKEN Accept: application/vnd.bentley.v1+json Content-Type: application/json
Example Response Headers
HTTP/1.1 201 Created Content-Length: 112 Request-Context: appId=cid-v1:7a353d36-9a8b-423e-965e-9d7f51324584 x-correlation-id: 2b59e2ac-3e89-42bf-9678-2717b395c5bf X-ITwinPlatform-Media-Type: bentley.itwin-platform.v1 X-ITwinPlatform-Region: East US Date: Mon, 04 Oct 2021 20:51:49 GMT
Example Response Body
{ "projectAssociation": { "id": "69401bde-6200-4c6c-b783-046f1935e825", "projectId": "615f57e7-876e-46fc-ab11-79af30cae299" } }
The DELETE https://api.bentley.com/realitydata/{id}/projects/{projectId}
http request will remove an association from the desired project.
Example HTTP Request for Dissociate RealityData Operation
DELETE https://api.bentley.com/realitydata/69401bde-6200-4c6c-b783-046f1935e825/projects/615f57e7-876e-46fc-ab11-79af30cae299 HTTP/1.1 Authorization: Bearer JWT_TOKEN Accept: application/vnd.bentley.v1+json Content-Type: application/json
Example Response Headers
HTTP/1.1 204 No Content Content-Length: 0 Request-Context: appId=cid-v1:7a353d36-9a8b-423e-965e-9d7f51324584 x-correlation-id: 07b4d6c4-6f05-492c-9b59-3bc382d4de76 X-ITwinPlatform-Media-Type: bentley.itwin-platform.v1 X-ITwinPlatform-Region: East US Date: Tue, 05 Oct 2021 14:57:12 GMT
7. Delete RealityData
Once your RealityData is no longer needed, you may delete it with the DELETE https://api.bentley.com/realitydata/{id}
HTTP request. Upon receiving a 204 No Content
response,
which indicates a successful deletion, the RealityData
resource along with it’s reality model will be deleted. There is no need to manually delete the reality model
by using GET container http requests with the Write permission.
Example HTTP Request for Delete RealityData Operation
DELETE https://api.bentley.com/realitydata/69401bde-6200-4c6c-b783-046f1935e825 HTTP/1.1 Authorization: Bearer JWT_TOKEN Accept: application/vnd.bentley.v1+json Content-Type: application/json
Example Response Headers
HTTP/1.1 204 No Content Content-Length: 0 Request-Context: appId=cid-v1:7a353d36-9a8b-423e-965e-9d7f51324584 x-correlation-id: 8c9990c0-c305-42b3-bd44-db295c80dfbd X-ITwinPlatform-Media-Type: bentley.itwin-platform.v1 X-ITwinPlatform-Region: East US Date: Tue, 05 Oct 2021 14:59:32 GMT
Continue learning
Congratulations for completing the RealityData API tutorial! You now have the necessary knowledge to use the RealityData API. To go further and use the RealityData API to its full potential, you can have a look at the following related tutorials.