• Get Started
  • Documentation
  • Samples
  • Blog
  • Pricing

    • Reality Management API - Essentials

    Introduction

    This tutorial covers the essential topics for using the Reality Management API. You will learn the following:

    • How to create a reality data.
    • How to upload data files to your reality data.
    • How to query your created reality data.

    You will also see how your reality data looks in an iTwin Viewer application.

    Use sample data

    This tutorial walks you through using the Reality Management API. We recommend using sample names and data while learning the API for this tutorial. The same instructions apply when using the Reality Management API for your production applications.

    Before you begin

    Ensure you meet the following requirements before starting the tutorial:

    • Be familiar with the concept of an iTwin. See the iTwin API Overview for more information.
    • Be familiar with the concept of Reality Data. See the Reality Management API Overview for more information.
    • (Optional) Be familiar with Azure Blob Storage. You can complete this tutorial regardless of your Azure knowledge level.
    • (Optional) An API client tool that allows you to execute HTTP calls. For ease of use, we have added executable code blocks enabling you to make sample requests within the tutorial. API client tools are helpful when testing your real-world applications.

    Set up your tutorial environment

    This section guides you through the pre-requisite steps for the tutorial so you can make sample API requests. It also provides sample data for you to use during the tutorial.

    Authorize your requests

    This tutorial provides an access token enabling you to complete the tutorial without setting up your own authentication.

    Click Authorize to generate the token. Your token is automatically populated in the headers of the sample requests.

    Application permissions

    When using this API to authorize your own application, you need to define the scopes and permissions for your solution. See the Authorization overview for more information. The tutorial uses the following scopes to make reality managment API requests: realitydata:read and realitydata:modify.

    Create an iTwin

    To use the Reality Management API, you must associate your reality data with an iTwin.

    Click Create iTwin.

    The ID of your iTwin is automatically populated in the requests that need it. Make sure save the iTwin ID. Click the Copy button to copy the ID and save it somewhere safe. When using the iTwin ID, make sure to remove the iTwin ID label from the pasted copy.

    Manually create an iTwin
    An iTwin is required when using this API in your own applications. For more information on creating an iTwin, see the Create iTwin reference.
    Get your data files
    You must have reality data files on your computer to follow this tutorial. We have provided some sample files for you to use.
    1. Click Download Data to download the sample reality data files.
      There are a lot of data files.
It may take a few minutes for them to download.
    2. Please unzip the folder Scene.zip after the download completes.
      There are a lot of data files.
It may take a few minutes for them to unzip.
    Generate your own files
    Provide your own reality data files when using the Reality Management API in production applications. Please see the Reality Modeling API for more information.
    Create a reality data
    The Reality Management API enables you to create and manage reality models and data.
A reality model is the real world environment visualized in a reality data viewer and is stored as data files.
Reality data is a place to store your reality model and any information describing that reality model.
    Send a request to the create reality data endpoint:
    POST
    https://api.bentley.com/reality-management/reality-data/
    The example request includes the following properties in its body:
    Parameter
    Required
    Description
    iTwinId
    No
    The iTwin ID is a unique identifier associating your reality data with your iTwin. Reminder: The ID is pre-populated in this tutorial if you clicked the Create an iTwin button during setup.
    displayName
    Yes
    The user friendly name of the reality data.
    type
    Yes
    Indicates the format of your reality data files. Find the list of available types in the types table on the Reality Data Properties page. For the sample files provided, the type is Cesium3DTiles.
    rootDocument
    No
    The path to the root document file. The root document file is a manifest containing extra information about the reality data and is used by the Visualization service to visualize your reality model. See the Root Document section on the Reality Data Properties page for more information. In our sample, the root document file is electrical_substation.json in the Scene folder making the rootDocument value Scene/electrical_substation.json.
    More properties
    This step contains the bare minimum properties required for this tutorial.
Many more properties are available and detailed in the Create reality data reference.
    Create reality data request example
    The ID of your reality data is automatically populated in the following requests that need it.
    Upload your reality model to the reality data’s container
    A reality data provides basic information about your reality model through its properties (such as what is the type/format of the files, where is the root document, etc).
When you created your reality data, a container in the cloud was also created to serve as a home for your reality model.
    This section details how to access and upload reality data files to that container.
    Get your reality data’s container
    The Reality Management API exposes two endpoints you can use to access your reality data’s container.
One endpoint provides read access to the container. The other endpoint provides write access.
However, both endpoints accept the same parameters.
The container is hosted in Azure Blob Storage.
    We want write access so you can upload the reality data files to the container.
For more information on read access, please see the Retrieve read access to reality data container reference.
    For write access, send the request to the write access endpoint.
    GET
    https://api.bentley.com/reality-management/reality-data/{id}/writeaccess?iTwinId={iTwinId}
    The endpoint accepts the following parameters:
    Parameter
    Required
    Description
    id
    Yes
    The ID of your reality data. Reminder: The ID is pre-populated in this tutorial if you completed the Create reality data request example.
    iTwinId
    No
    The ID of your iTwin. It affects the permissions for accessing the container as discussed in the Retrieve write access to reality data container reference. Reminder: The ID is pre-populated in this tutorial if you clicked the Create an iTwin button during setup.
    Retrieve write access to reality data container request example
    The href returned in the response is a SAS URI with write access to the Azure blob hosting your reality data’s container.
    Understanding the SAS URI
    Understanding the SAS URI is not required to use it for the API or tutorial.
You can learn more about Azure Storage SAS URI’s from Microsoft’s SAS token documentation.
    Upload your files to the container
    Microsoft has several workflows available for uploading data to an Azure blob.
Exhaustively exploring these options is beyond this scope of this tutorial.
However, we will point you to a couple of workflows that will allow you to upload the previously downloaded Scene folder with as little friction as possible.
    Uploading the files via the command line
    AzCopy is a command line tool that you can use to upload files to your storage account.
This is our recommended way to upload your files for the tutorial.
    To upload your reality data files, follow these steps:
    1. Ensure you have clicked the Download Data button and unzipped the downloaded Scene folder.
    2. Download AzCopy.
    3. Run AzCopy via the command line.
azcopy copy "{path_to_downloaded_Scene_folder}" "{SAS_URI_from_the_previous_response}" --recursive
    Microsoft has an example in the Use a SAS token section of their Get started with AzCopy page.
Be sure to at least read the Run AzCopy link. It points out restrictions on where you can run AzCopy.
    Uploading the files graphically
    Microsoft has a desktop application called Azure Storage Explorer that you can download to have a
graphical experience of dragging and dropping your reality data files into your blob container.
    To upload your reality data files using Azure Storage Explorer, follow these steps:
    1. Ensure you have clicked the Download Data button and unzipped the downloaded Scene folder.
    2. Download the application by going to Microsoft’s Azure Storage Explorer website and selecting your operating system.
    3. Once you have the application downloaded and open, you can follow Microsoft’s instructions in the
Attach to an individual resource
and Shared access signature (SAS) URL
sections of their Get started with Storage Explorer page.
The resource you want to connect to should be “Blob container” (or something similarly named).
    4. After following Microsoft’s instructions and connecting, drag and drop the
Scene folder into the container.
    Programmatic options
    The above two options are easiest for uploading your reality model quickly.
However, if you are attempting to programmatically upload a reality model in your application, we recommend using Microsoft’s Azure Blob Storage client libraries. Microsoft has Azure Blob Storage client libraries for .NET, Java, Python, JavaScript, C++, and Go.
If you are using a language that does not have a client library, check out the raw Azure Blob Storage REST API.
    Query your created reality data
    The Reality Management API exposes two endpoints you can use to query your reality data.
    Query reality data associated with an iTwin
    This endpoint returns the first 100 reality data associated with the iTwin specified in the request.
It only returns reality data that you have access to, relative to your organization’s access rights.
    To query all reality data associated with your iTwin, send a request to the get iTwin’s reality data endpoint.
    GET
    https://api.bentley.com/reality-management/reality-data/?iTwinId={iTwinId}
    The example request includes the following parameters:
    Parameter
    Required
    Description
    iTwinId
    No
    The ID of your iTwin. If you do not provide your iTwin ID, then the request instead returns the first 100 reality data that you have access to across all iTwins. Reminder: The ID is pre-populated in this tutorial if you clicked the Create an iTwin button during setup.
    More properties
    This step contains the bare minimum parameters required for this tutorial.
More parameters are available and detailed in the documentation for the Get iTwin’s reality data endpoint.
    Get iTwin’s reality data request example
    At this point, only the reality data you created during this tutorial should be listed.
    Query a specific reality data
    This endpoint takes a reality data ID and returns that specific reality data.
    To query a specific reality data, send a request to the get reality data metadata endpoint.
    GET
    https://api.bentley.com/reality-management/reality-data/{id}?iTwinId={iTwinId}
    The example request accepts the following parameters:
    Parameter
    Required
    Description
    id
    Yes
    The ID of your reality data. Reminder: The ID is pre-populated in this tutorial if you completed the Create reality data request example.
    iTwinId
    No
    The ID of your iTwin. It affects the permissions for querying the reality data as discussed in the Get reality data metadata reference. Reminder: The ID is pre-populated in this tutorial if you clicked the Create an iTwin button during setup.
    Get reality data metadata request example
    Visualize your newly uploaded reality data
    After creating a reality data and uploading your reality model to its container, you can now visualize your reality data in an iTwin Viewer.
    Click View Reality Data to see the reality model you created in a Viewer.
    Viewer Errors
    The reality data viewer will attempt to display helpful error messages if it detects a potential mistake.
To resolve some of the errors, please check the following:
    1. Ensure that you have completed all steps of the tutorial before clicking the View Reality Data button.
    2. Verify that the rootDocument path specified during the Create a reality data step is still valid based on the structure of the files you uploaded during the Upload your reality model to the reality data’s container step.
    The official Reality Data sample provides an example on attaching and visualizing reality data in an iTwin Viewer.
Check out that sample, our iTwin.js documentation, the @itwin/reality-data-client package, and the reality-capture web application for how to visualize your reality data in your own application.
    Reality Data Location
    If you are building your own iTwin Viewer application, it is helpful to know the location of your reality data. The sample reality data has the following coordinates (with longitude and latitude in degrees and height in meters):
    • Longitude: 4.668735091306921°
    • Latitude: 45.265122669456325°
    • Height: 456.72571760937933 meters
    What you’ve learned
    In this tutorial, you should have learned:
    This tutorial provided the background knowledge required for you to:
    More resources that you may like
    Reality Management API
    The reference documentation for the reality management API. Allows you to manage your reality data and is covered in this tutorial.
    Reality Modeling API
    The reference documentation for the reality modeling API. Allows you to turn images and point clouds into reality meshes, orthophotos and others.
    Reality Analysis API
    The reference documentation for the reality analysis API. Allows you to run AI/ML on photos, maps, meshes or point clouds.