Get iTwin's reality data - Reality Management

Reality Management

Download API definition:

GET https://api.bentley.com/reality-management/reality-data/[?iTwinId][&continuationToken][&$top][&extent][&$orderBy][&$search][&types][&acquisitionDateTime][&createdDateTime][&modifiedDateTime][&lastAccessedDateTime][&ownerId][&dataCenter][&tag]

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

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

The iTwinId 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 iTwinId 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 itwin-platform.

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

Request parameters

iTwinId

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

continuationToken

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

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

extent

Extent of the area to search, delimited by southwest and northeast coordinates. Extent values are specified in this format: SouthwestCorner_Longitude, SouthwestCorner_Latitude, NortheastCorner_Longitude, NortheastCorner_Latitude. 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

$orderBy

Parameter that enable to order reality data in ascending or descending order. Default is ascending.Example : displayName desc

$search

Search reality data

types

Comma separated list of reality data types. Example: "OPC,Terrain3DTiles, OMR, Cesium3DTiles"

acquisitionDateTime

Aquisition datetime range in ISO-8601 compliant time (UTC).
Format: startDateTime/endDateTime
Example: 2021-05-12T20:03:12Z/2022-05-12T20:03:12Z

createdDateTime

Created datetime range in ISO-8601 compliant time (UTC).
Format: startDateTime/endDateTime
Example: 2021-05-12T20:03:12Z/2022-05-12T20:03:12Z

modifiedDateTime

Modified datetime range in ISO-8601 compliant time (UTC).
Format: startDateTime/endDateTime
Example: 2021-05-12T20:03:12Z/2022-05-12T20:03:12Z

lastAccessedDateTime

Last accessed datetime range in ISO-8601 compliant time (UTC).
Format: startDateTime/endDateTime
Example: 2021-05-12T20:03:12Z/2022-05-12T20:03:12Z

ownerId

Guid identifier of the owner. Example: 123e4567-e89b-12d3-a456-426614174000

dataCenter

Data center location. Example: "East US"

tag

Parameter to get reality data with exact matching tags.

Request headers

Prefer

Optional. Selected preferred representation.

Authorization

Yes

OAuth access token with itwin-platform scope

Yes

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

Response

Response 200 OK

json

{
    "realityData": [{
        "id": "95d8dccd-d89e-4287-bb5f-3219acbc71ae",
        "displayName": "Name of reality data",
        "type": "3mx"
    }],
    "_links": {
        "next": {
            "href": "https://api.bentley.com/reality-management/reality-data?iTwinId=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 403 Forbidden

This response indicates that user does not have required permissions to get reality data's from iTwin.

json

{
    "error": {
        "code": "InsufficientPermissions",
        "message": "The user has insufficient permissions for the requested operation."
    }
}

Response 404 Not Found

This response indicates that the iTwin was not found.

json

{
    "error": {
        "code": "iTwinNotFound",
        "message": "Requested iTwin is not available."
    }
}

Response 422 Unprocessable Entity

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

json

{
    "error": {
        "code": "InvalidRealityDataRequest",
        "message": "Invalid RealityData request.",
        "details": [{
            "code": "InvalidParameter",
            "message": "The field Top must be between 1 and 1000.",
            "target": "$Top"
        }]
    }
}

Response 429 Too many requests

This response indicates that the client sent more requests than allowed by this API for the current tier of the client.

json

{
    "error": {
        "code": "RateLimitExceeded",
        "message": "The client sent more requests than allowed by this API for the current tier of the client."
    }
}

Response headers

retry-after

Number of seconds to wait until client is allowed to make more requests.

Definitions

Acquisition

Details about data acquisition.

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.

json

{
    "title": "Acquisition",
    "type": "object",
    "description": "Details about data acquisition.",
    "properties": {
        "startDateTime": {
            "type": "string",
            "format": "date-time",
            "description": "ISO-8601 compliant time (UTC) that indicates when the data acquisition started. E.g. '2017-05-10T13:43:03Z'"
        },
        "endDateTime": {
            "type": "string",
            "format": "date-time",
            "description": "ISO-8601 compliant time (UTC) that indicates when the data acquisition ended. E.g. '2017-05-10T13:43:03Z'"
        },
        "acquirer": {
            "type": "string",
            "description": "Description of the acquirer."
        }
    },
    "additionalProperties": false
}

Extent

Extent of a reality data, delimited by southwest and northeast coordinates.

southWest

coordinate

Extent's southwest coordinate.

northEast

coordinate

Extent's northeast coordinate.

json

{
    "title": "Extent",
    "type": "object",
    "description": "Extent of a reality data, delimited by southwest and northeast coordinates.",
    "properties": {
        "southWest": {
            "$ref": "#/components/schemas/coordinate",
            "description": "Extent's southwest coordinate."
        },
        "northEast": {
            "$ref": "#/components/schemas/coordinate",
            "description": "Extent's northeast coordinate."
        }
    },
    "additionalProperties": false
}

Coordinate

Coordinate used to define an extent.

latitude

Double

Latitude. Latitude ranges between -90 and 90 degrees, inclusive.

longitude

Double

Longitude. Longitude ranges between -180 and 180 degrees, inclusive.

json

{
    "title": "Coordinate",
    "type": "object",
    "description": "Coordinate used to define an extent.",
    "properties": {
        "latitude": {
            "type": "number",
            "format": "double",
            "minimum": -90,
            "maximum": 90,
            "description": "Latitude. Latitude ranges between -90 and 90 degrees, inclusive."
        },
        "longitude": {
            "type": "number",
            "format": "double",
            "minimum": -180,
            "maximum": 180,
            "description": "Longitude. Longitude ranges between -180 and 180 degrees, inclusive."
        }
    },
    "additionalProperties": false
}

link

href

String

json

{
    "type": "object",
    "properties": {
        "href": {
            "type": "string"
        }
    },
    "additionalProperties": false
}

Reality Data Details

Details for a reality data (summary)

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 reality data types.

json

{
    "title": "Reality Data Details",
    "type": "object",
    "description": "Details for a reality data (summary)",
    "properties": {
        "id": {
            "type": "string",
            "description": "Identifier of the reality data. This identifier is assigned by the service at the creation of the reality data. It is also unique."
        },
        "displayName": {
            "type": "string",
            "description": "The name of the reality data. This property may not contain any control sequence such as a URL or code."
        },
        "type": {
            "type": "string",
            "description": "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 [reality data types](/apis/reality-management/rm-rd-details/#types)."
        }
    },
    "additionalProperties": false
}

Reality Data Details

Array of reality data (summary)

realityData

reality-data-metadata-summary[]

_links

next-page-link, null

json

{
    "title": "Reality Data Details",
    "type": "object",
    "description": "Array of reality data (summary)",
    "properties": {
        "realityData": {
            "type": "array",
            "items": {
                "$ref": "#/components/schemas/reality-data-metadata-summary"
            }
        },
        "_links": {
            "$ref": "#/components/schemas/next-page-link",
            "nullable": true
        }
    },
    "additionalProperties": false
}

Reality Data Details

Array of reality data

realityData

reality-data-metadata[]

_links

next-page-link, null

json

{
    "title": "Reality Data Details",
    "type": "object",
    "description": "Array of reality data",
    "properties": {
        "realityData": {
            "type": "array",
            "items": {
                "$ref": "#/components/schemas/reality-data-metadata"
            }
        },
        "_links": {
            "$ref": "#/components/schemas/next-page-link",
            "nullable": true
        }
    },
    "additionalProperties": false
}

Next Page Link

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

link

json

{
    "title": "Next Page Link",
    "type": "object",
    "description": "URL for getting the next page of data, if applicable.",
    "properties": {
        "next": {
            "$ref": "#/components/schemas/link"
        }
    },
    "additionalProperties": false
}

tag

A string identifier.

Reality Data Details

Details for a reality data

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.

tags

tag[]

Any string identifier which you can assign to reality data to identify it.

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

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.

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'

ownerId

String

Identifier of the owner of the reality data.

json

{
    "title": "Reality Data Details",
    "type": "object",
    "description": "Details for a reality data",
    "properties": {
        "id": {
            "type": "string",
            "description": "Identifier of the reality data. This identifier is assigned by the service at the creation of the reality data. It is also unique."
        },
        "displayName": {
            "type": "string",
            "description": "The name of the reality data. This property may not contain any control sequence such as a URL or code."
        },
        "dataset": {
            "type": "string",
            "description": "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": {
            "type": "string",
            "description": "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": {
            "type": "string",
            "description": "A textual description of the reality data. This property may not contain any control sequence such as a URL or code."
        },
        "tags": {
            "type": "array",
            "description": "Any string identifier which you can assign to reality data to identify it.",
            "items": {
                "$ref": "#/components/schemas/tag"
            }
        },
        "rootDocument": {
            "type": "string",
            "description": "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": {
            "type": "integer",
            "format": "int64",
            "description": "The size of the reality data in Kilobytes."
        },
        "classification": {
            "type": "string",
            "description": "Specific value constrained field that indicates the nature of the reality data. The following values are currently supported: Terrain, Imagery, Pinned, Model, Undefined."
        },
        "type": {
            "type": "string",
            "description": "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 [reality data types](/apis/reality-management/rm-rd-details/#types)."
        },
        "acquisition": {
            "$ref": "#/components/schemas/acquisition",
            "description": "Provides information regarding the acquisition, such as dates and acquirer used."
        },
        "extent": {
            "$ref": "#/components/schemas/extent",
            "description": "Contains the rectangular area on the Earth which encloses the reality data."
        },
        "authoring": {
            "type": "boolean",
            "description": "A boolean value that is true if the data is being created. It is false if the data has been completely uploaded."
        },
        "dataCenterLocation": {
            "type": "string",
            "description": "Identifies the data center location used to store the reality data."
        },
        "modifiedDateTime": {
            "type": "string",
            "format": "date-time",
            "description": "ISO-8601 compliant time (UTC) of last modification of the reality data. E.g. '2017–05–10T13:43:03Z'"
        },
        "lastAccessedDateTime": {
            "type": "string",
            "format": "date-time",
            "description": "ISO-8601 compliant time (UTC) of last access of the reality data. E.g. '2017–05–10T13:43:03Z'"
        },
        "createdDateTime": {
            "type": "string",
            "format": "date-time",
            "description": "ISO-8601 compliant time (UTC) of the creation of the reality data. E.g. '2017–05–10T13:43:03Z'"
        },
        "ownerId": {
            "type": "string",
            "description": "Identifier of the owner of the reality data."
        }
    },
    "additionalProperties": false
}

DetailedError

Contains error information and an array of more specific errors.

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

Error[]

Optional array of more specific errors.

json

{
    "type": "object",
    "description": "Contains error information and an array of more specific errors.",
    "properties": {
        "code": {
            "type": "string",
            "description": "One of a server-defined set of error codes."
        },
        "message": {
            "type": "string",
            "description": "A human-readable representation of the error."
        },
        "target": {
            "type": "string",
            "description": "The target of the error.",
            "nullable": true
        },
        "details": {
            "type": "array",
            "description": "Optional array of more specific errors.",
            "items": {
                "$ref": "#/components/schemas/Error"
            }
        }
    },
    "required": [
        "code",
        "message",
        "details"
    ],
    "additionalProperties": true
}

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

error

DetailedError

Error Detailed information.

json

{
    "type": "object",
    "title": "Detailed Error Response",
    "description": "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.",
    "properties": {
        "error": {
            "description": "Error Detailed information.",
            "$ref": "#/components/schemas/DetailedError"
        }
    },
    "required": [
        "error"
    ],
    "additionalProperties": false
}

Error

Contains error information.

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.

json

{
    "type": "object",
    "description": "Contains error information.",
    "properties": {
        "code": {
            "type": "string",
            "description": "One of a server-defined set of error codes."
        },
        "message": {
            "type": "string",
            "description": "A human-readable representation of the error."
        },
        "target": {
            "type": "string",
            "description": "The target of the error.",
            "nullable": true
        }
    },
    "required": [
        "code",
        "message"
    ],
    "additionalProperties": true
}

Error Response

error

Error

Error information.

json

{
    "type": "object",
    "title": "Error Response",
    "description": "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.",
    "properties": {
        "error": {
            "description": "Error information.",
            "$ref": "#/components/schemas/Error"
        }
    },
    "required": [
        "error"
    ],
    "additionalProperties": false
}

Was this page helpful?