Get Started
Documentation
Samples

Reality Data

Reality Data

Download API definition:
Create reality data
POST https://api.bentley.com/realitydata/

Creates a reality data.

As shown in the request section below, you must provide a request body.

You MUST provide the displayName, classification and type properties.

Valid values for the classification property are: Terrain, Imagery, Pinned, Model, Undefined. For more details on each value, see Reality Data Properties in documentation.

We recommend specifying a projectId in the request body, as it is used to choose the data center where the reality data is stored (the same as the project). If no projectId can be provided, the default data center of the organization is selected.

After creation, the reality data will be associated to the specified project.

Authentication

Requires Authorization header with valid Bearer token for scope realitydata:modify.

For more documentation on authorization and how to get access token visit OAUTH2 Authorization page.

Authorization

User must be an Organization Administrator for the Organization that owns a given Project or have {permission} permission assigned at the Project level.

An Organization Administrator must have at least one of the following roles assigned in User Management: Account Administrator, Co-Administrator, or CONNECT Services Administrator. For more information about User Management please visit our Bentley Communities Licensing, Cloud, and Web Services wiki page.

Rate limits

All iTwin Platform API operations have a rate limit. For more documentation on that visit Rate limits and quotas page.

Request

Request headers

Name
Required?
Description
Authorization
Yes

OAuth access token with scope realitydata:modify

Accept
No

Setting to application/vnd.bentley.itwin-platform.v1+json is recommended.

Request body

Reality Data (Create)

Name
Type
Required?
Description
projectId
String
No

id of associated project.

realityData
request-body-reality-data
No

Reality data properties.

Response

Response 201 Created

Reality data successfully created

json
Response 401 Unauthorized
This response indicates that request lacks valid authentication credentials. Access token might not been provided, issued by the wrong issuer, does not have required scopes or request headers were malformed.
json
Response 403 Forbidden
This response indicates that user does not have required permissions to create a reality data.
json
Response 422 Unprocessable Entity
Invalid request to create reality data. Please ensure that the request is valid.
json
Response 429 Too many requests
This response indicates that the user has sent too many requests in a given amount of time.
json
Response headers
Name
Description
retry-after
The number of requests exceeds the rate-limit for the client subscription.
Definitions
Reality Data Details
Details for a reality data
TableSchema
Name
Type
Description
id
String
Identifier of the reality data. This identifier is assigned by the service at the creation of the reality data. It is also unique.
displayName
String
The name of the reality data. This property may not contain any control sequence such as a URL or code.
dataset
String
This field can be used to define a loose grouping of reality data. This property may not contain any control sequence such as a URL or code.
group
String
The group can be used to define a second level of grouping. This property may not contain any control sequence such as a URL or code.
description
String
A textual description of the reality data. This property may not contain any control sequence such as a URL or code.
rootDocument
String
Used to indicate the root document of the reality data. The root document can be in a subfolder and is then specified as “Tile_Root.json” or “Folder1/SubFolder1/File.json” for example.
size
Int64
The size of the reality data in Kilobytes.
classification
String
Specific value constrained field that indicates the nature of the reality data. The following values are currently supported: Terrain, Imagery, Pinned, Model, Undefined.
type
String
A key indicating the format of the data. The type property should be a specific indication of the format of the reality data. Given a type, the consuming software should be able to determine if it has the capacity to open the reality data. Although the type field is a free string some specific values are reserved and other values should be selected judiciously. Look at the documentation for an exhaustive list of reserved types.
acquisition
acquisition
Provides information regarding the acquisition, such as dates and acquirer used.
extent
extent
Contains the rectangular area on the Earth which encloses the reality data.
authoring
Boolean
A boolean value that is true if the data is being created. It is false if the data has been completely uploaded.
accessControl
String
A value indicating the access permissions on the reality data. 4 values are possible. Project: data can only be used as part of a project; Organization: any member of the organization can use the data; Private: only the owner can use the data; Public: anyone, even users external to an enterprise can use the data. Note that this field is read-only and can't be provided as a request parameter. If a projectId is provided on the creation of the reality data, the accessControl is set to Project; otherwise accessControl is set to Organization. Other values are there for legacy reasons.
dataCenterLocation
String
Identifies the data center location used to store the reality data.
modifiedDateTime
Date-time
ISO-8601 compliant time (UTC) of last modification of the reality data. E.g. '2017–05–10T13:43:03Z'
lastAccessedDateTime
Date-time
ISO-8601 compliant time (UTC) of last access of the reality data. E.g. '2017–05–10T13:43:03Z'
createdDateTime
Date-time
ISO-8601 compliant time (UTC) of the creation of the reality data. E.g. '2017–05–10T13:43:03Z'
Reality Data Details Response
Reality data details response.
TableSchema
Name
Type
Description
realityData
reality-data-metadata
Reality data details properties.
Acquisition
Details about data acquisition.
TableSchema
Name
Type
Description
startDateTime
Date-time
ISO-8601 compliant time (UTC) that indicates when the data acquisition started. E.g. '2017–05–10T13:43:03Z'
endDateTime
Date-time
ISO-8601 compliant time (UTC) that indicates when the data acquisition ended. E.g. '2017–05–10T13:43:03Z'
acquirer
String
Description of the acquirer.
Extent
Extent of a reality data, delimited by southwest and northeast coordinates.
TableSchema
Name
Type
Description
southwest
coordinate
Extent's southwest coordinate.
northeast
coordinate
Extent's northeast coordinate.
Coordinate
Coordinate used to define an extent.
TableSchema
Name
Type
Description
latitude
Double
Latitude. Latitude ranges between -90 and 90 degrees, inclusive.
longitude
Double
Longitude. Longitude ranges between -180 and 180 degrees, inclusive.
Reality Data (Create)
Request body for reality data creation.
TableSchema
Name
Type
Description
projectId
String
id of associated project.
realityData
request-body-reality-data
Reality data properties.
Reality Data
Reality data details for request body.
TableSchema
Name
Type
Description
displayName
String
Name of the reality data.
classification
String
Specific value constrained field that indicates the nature of the reality data. Allowed values: 'Terrain', 'Imagery', 'Pinned', 'Model', 'Undefined'
type
String
A key indicating the format of the data. Valid values include '3MX', 'PointCloud', RealityMesh3DTiles', … See documentation for an exhaustive list of registered types.
description
String
Description of the reality data.
dataset
String
This field can be used to define a loose grouping of reality data. This property may not contain any control sequence such as a URL or code.
group
String
The group can be used to define a second level of grouping. This property may not contain any control sequence such as a URL or code.
rootDocument
String
Used to indicate the root document of the reality data.
acquisition
acquisition
Details about data acquisition.
extent
extent
The rectangular area on the Earth which encloses the reality data.
authoring
Boolean
A boolean value that is true if the data is being created. It is false if the data has been completely uploaded.
Error Response
Gives details for an error that occurred while handling the request. Note that clients MUST NOT assume that every failed request will produce an object of this schema, or that all of the properties in the response will be non-null, as the error may have prevented this response from being constructed.
TableSchema
Name
Type
Description
error
error-message
Error information.
error-message
Contains error information.
TableSchema
Name
Type
Description
code
String
One of a server-defined set of error codes.
message
String
A human-readable representation of the error.
Error
Contains error information and an optional array of more specific errors.
TableSchema
Name
Type
Description
code
String
One of a server-defined set of error codes.
message
String
A human-readable representation of the error.
target
String
The target of the error.
details
ErrorDetails[]
Optional array of more specific errors.
Error Details
Contains error information.
TableSchema
Name
Type
Description
code
String
One of a server-defined set of error codes.
message
String
A human-readable representation of the error.
target
String
The target of the error.
Error Response
Gives details for an error that occurred while handling the request. Note that clients MUST NOT assume that every failed request will produce an object of this schema, or that all of the properties in the response will be non-null, as the error may have prevented this response from being constructed.
TableSchema
Name
Type
Description
error
Error
Error information.