Table of contents
Reality Data
Download API definition:
This API is deprecated. Please upgrade to the current version of this API as soon as possible.
GET https://api.bentley.com/realitydata/[?projectId][&continuationToken][&$top][&extent]

Retrieves a list of reality data instances belonging to the specified project.

The retrieved instances are those for which you have the required access rights, relative to the specified project.

The projectId is optional. If you don't provide it, the retrieved reality data instances will be relative to general access rights provided by your organization. These rights are usually more restrictive, so we recommend using the projectId parameter for exhaustive results.

Notes

The Prefer header can be used to specify how much result metadata is desired by the client. The Prefer request header field is used to indicate that particular server behaviors are preferred by the client but are not required for successful completion of the request.

This operation supports "return=representation" and "return=minimal" preferences.

The "return=representation" preference indicates that the client prefers that the server include an entity representing the current state of the resource in the response to a successful request, i.e., all properties are included in the response. The "return=minimal" preference indicates that the client wishes the server to return only a minimal response to a successful request. This is the default preference if Prefer header is not specified.

Authentication

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

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 must have access to context.

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 parameters

Name
Required?
Description
projectId
No

Id of project. The operation gets all reality data in this project.

continuationToken
No

Parameter that enables continuing to the next page of the previous paged query. This must be passed exactly as it is in the response body's _links.next property. If this is specified and $top is omitted, the next page will be the same size as the previous page.

$top
No

The number of reality data to get in each page. Max 500, but 100 is the default if this parameter is not included.

extent
No

Extent of the area to search, delimited by southwest and northeast coordinates. Extent values are specified in this format: SouthwestCornerLongitude, SouthwestCornerLatitude, NortheastCornerLongitude, NortheastCornerLatitude. E.g. to get all reality data in an area around Exton, PA, provide the following extent parameter: extent=-75.637679,40.032871,-75.633647,40.032771

Request headers

Name
Required?
Description
Prefer
No

Optional. Selected preferred representation.

Authorization
Yes

OAuth access token with scope realitydata:read

Accept
No

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

Response 200 OK

OK

json
{
    "realityData": [{
        "id": "95d8dccd-d89e-4287-bb5f-3219acbc71ae",
        "displayName": "Name of reality data",
        "type": "3mx",
        "_links": {
            "self": {
                "href": "https://api.bentley.com/realitydata/95d8dccd-d89e-4287-bb5f-3219acbc71ae?projectId=0d4e1f7b-1a4c-0000-0000-1643d04e3954"
            }
        }
    }],
    "_links": {
        "next": {
            "href": "https://api.bentley.com/realitydata?projectId=0d4e1f7b-1a4c-0000-0000-1643d04e3954&continuationToken=eyJ0b3AiOjEwMCwic2tpcCI6MTAwfQ"
        }
    }
}

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
{
    "error": {
        "code": "HeaderNotFound",
        "message": "Header Authorization was not found in the request. Access denied."
    }
}

Response 422 Unprocessable Entity

Invalid request to get reality data. Please ensure that the request is valid.

json
{
    "error": {
        "code": "InvalidGetRealityDataRequest",
        "message": "Unknown error. Please ensure that the request is valid."
    }
}

Response 429 Too many requests

This response indicates that the user has sent too many requests in a given amount of time.

json
{
    "error": {
        "code": "TooManyRequests",
        "message": "More requests were received than the subscription rate-limit allows."
    }
}

Response headers

Name
Description
retry-after

The number of requests exceeds the rate-limit for the client subscription.

Reality Data Details

Details for a reality data

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

Provides information regarding the acquisition, such as dates and acquirer used.

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

Details for a reality data (summary)

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.

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.

Reality Data Details Link

Name
Type
Description
self

The link to get the reality data details.

Reality Data Details

Array of reality data (summary)

Name
Type
Description

Reality Data Details

Array of reality data

Name
Type
Description

Next Page Link

URL for getting the next page of data, if applicable.

Name
Type
Description
next

link

Name
Type
Description
href
String

Acquisition

Details about data acquisition.

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.

Name
Type
Description
southwest

Extent's southwest coordinate.

northeast

Extent's northeast coordinate.

Coordinate

Coordinate used to define an extent.

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.

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.

Name
Type
Description
error

Error information.

error-message

Contains error information.

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.

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, null

The target of the error.

details
ErrorDetails[], null

Optional array of more specific errors.

Error Details

Contains error information.

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, null

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.

Name
Type
Description
error

Error information.