Get started with RealityData API

Introduction

The RealityData API purpose is to provide users the ability to manage and share reality models. This quick start tutorial is going to help you get started with using the RealityData API, and understand it’s basic workflows.

In this tutorial, we will create and modify a RealityData, associate and dissociate it to a project, modify it, upload and download a reality model attached to the created RealityData, and delete it. Completing this tutorial will give you an understanding of the RealityData API, that you can leverage to manage and share your reality models.

Info

Skill level:

Basic

Duration:

30 minutes

Prerequisites

This tutorial assumes that you already have:

Postman

If you want to test the REST API calls directly, you can use Postman or any other solution capable of sending HTTP requests. If you do it this way, you will require an authorization token for the requests to work. This is covered in the “Get a token” section below.

1. Register an Application

You will need to register an application to use the iTwin Platform APIs. You can use the Register button to automatically create your first single page application (SPA). This will allow you to configure Authorization Code Flow for your SPA application and get the correct access token.

Once generated, you will be shown a few lines of code under the button.

  • IMJS_AUTH_CLIENT_CLIENT_ID - this is the unique identifier for your application. 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. Displayed on application details page as one of Redirect URIs.
  • IMJS_AUTH_CLIENT_LOGOUT_URI - specifies where users can be returned to after logging out. Displayed on application details page as one of Post logout redirect URIs.
  • IMJS_AUTH_CLIENT_SCOPES - list of accesses granted to the application. Displayed on application details page as Scopes.

Or optionally: Register and configure your application manually following instructions in Register and modify an Application tutorial. Make sure that your application is associated with RealityData, along with iModels, Synchronization, Digital Twin Management and Administration and has synchronization:modify realitydata:modify export:read projects:read users:read projects:modify library:read realitydata:read imodels:modify storage:read export:modify synchronization:read imodels:read storage:modify scopes enabled.

Requires you to sign in. Will automatically generate a Single page application (SPA) that is required to complete this tutorial. You will be able to manage your SPA from your My apps page.

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 RealityData
  • Classification 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


HTTP
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
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


JSON
{
    "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,
        "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 to it. The GET https://api.bentley.com/realitydata/{id}/container/?projectId={projectId}&permissions=Write HTTP request will provide you with a SAS URL with write access.

In order to use this resource, you may 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 ContextCapture

Example HTTP Request for Get RealityData Container Operation


HTTP
GET https://api.bentley.com//realitydata/69401bde-6200-4c6c-b783-046f1935e825/container/?projectId=615f57e7-876e-46fc-ab11-79af30cae299&permissions=Write HTTP/1.1
Authorization: Bearer JWT_TOKEN
Accept: application/vnd.bentley.v1+json
Content-Type: application/json

Example Response Headers


HTTP
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


JSON
{
    "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 route to use in order to get your created RealityData. Using this call as is will return all the RealityData that you have access to.

The GET https://api.bentley.com/realitydata/?projectId={projectId} request will return all RealityData under the given Project, provided you have access to it.

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.

Example HTTP Request for Get RealityData Operation


HTTP
GET https://api.bentley.com/realitydata HTTP/1.1
Authorization: Bearer JWT_TOKEN
Accept: application/vnd.bentley.v1+json
Content-Type: application/json

Example Response Headers


HTTP
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


JSON
{
    "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": {},
            "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": {},
            "dataCenterLocation": "North Europe",
            "modifiedDateTime": "2017-05-10T13:43:03Z",
            "lastAccessedDateTime": "2021-08-11T00:00:00Z",
            "createdDateTime": "2017-05-10T13:43:03Z"
        }
      ]
 }

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


HTTP
GET https://api.bentley.com//realitydata/69401bde-6200-4c6c-b783-046f1935e825/container/?projectId=615f57e7-876e-46fc-ab11-79af30cae299&permissions=Write HTTP/1.1
Authorization: Bearer JWT_TOKEN
Accept: application/vnd.bentley.v1+json
Content-Type: application/json

Example Response Headers


HTTP
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


JSON
{
    "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


HTTP
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
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


JSON
{
    "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": {},
        "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}&permissions=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


HTTP
GET https://api.bentley.com//realitydata/69401bde-6200-4c6c-b783-046f1935e825/container/?projectId=615f57e7-876e-46fc-ab11-79af30cae299&permissions=Write HTTP/1.1
Authorization: Bearer JWT_TOKEN
Accept: application/vnd.bentley.v1+json
Content-Type: application/json

Example Response Headers


HTTP
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


JSON
{
    "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


HTTP
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
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


JSON
{
        "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


HTTP
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
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.

If your RealityData is associated to more than one Project, you must first dissociate it from every project, except one. See section 6.2. Note that you must have sufficient rights within the project to delete RealityData.
The RealityData API does not support a 'recycle bin' feature. Deleting a RealityData results in immediate deletion of the reality model and it cannot be recovered.

Example HTTP Request for Delete RealityData Operation


HTTP
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
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.

More Resources that you may like

Complete Reality Data API documentation.
Typescript Client provided by itwin.js to facilitate the use the Reality Data API.
Npm Package containing client wrappers for sending requests to the RealityData API.