Get global resource graphics - iTwins

iTwins

Download API definition:

This operation is a Technical Preview and is available for testing purposes only. Do not use in production.

GET https://dev-api.bentley.com/itwins/repositories/{repositoryId}/resources/{resourceId}/graphics

Returns a Uri and additional options needed for accessing the graphics content for the specified resource.

type - A string indicating the Content Type of the graphics.

uri - A uri containing the location of the graphics content.

authentication - If needed, this will contain authentication information needed to access the graphics content. The graphics uri may point to another service that requires a different token or authentication method. Valid types: Header, QueryParameter, Basic. If authentication information is returned here then it should be included with each request to get the graphics content. You will need to add a header or query parameter based on the value of the authentication.type field.

provider - The provider name and options that a client might need to display the graphics content. Currently, these options will only be returned for Google graphics content. Specifically, the options will contain additional properties that can be passed to the Cesium Google2DImageryProvider. Google content is currently only available to internal Bentley applications.

Examples

Cesium requires a Bearer token to access the graphics content that is different than the one used to call the iTwin Repositories API. This token is returned in the response so that the client can add the correct Authorization header when making requests to the specified uri.

{
   "graphics": [
      {
         "type": "IMAGERY",
         "uri": "https://assets.ion.cesium.com/us-east-1/asset_depot/3954/Sentinel-2/2021/",
         "authentication": {
             "type": "Header",
             "key": "Authorization",
             "value": "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJqdGkiOiJjYTI4MWMzYy0yMzQyLTQyNWMtOGJjMC0xzIiwiaWF0IjoxNzUwNDU1MjQ2LCJleHAiOjE3NTA0NTg4NDZ9.sG9TnnwExucPrOhNXN1tswqNMK27IdAoiYI2cZuqazE"
         }
      }
   ]
}

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.

Request

Request parameters

repositoryId

Yes

The repository Id

resourceId

Yes

The resourceId

Request headers

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

{
    "graphics": [{
        "type": "IMAGERY",
        "uri": "https://assets.ion.cesium.com/us-east-1/asset_depot/3954/Sentinel-2/2021/",
        "authentication": {
            "type": "Header",
            "key": "Authorization",
            "value": "Bearer eyGhbGI6IkpXVCJ9.eyJqdGkiOiI4MDFiMjU5NC0xMDVjLTRmMzMtYWU5OS01ZGY1NTUzYWIwOGYiLCJpZCI6MjUzMzcyLCJhc3NldElkIjozOTU0LCJhc3NldHMiOnsiMzk1NCI6eyJ0eXBlIjoiSU1BR0VSWSIsInByZWZpeCI6IlNlbnRpbmVsLTIvMjAyMSJ9fSwic3JjIjoiZTM2ODExN2QtNDAwZC00NjJhLWI3ZjItNDFmNjI1OTFiNmQzIiiaWF0IjoxNzQwMTY5NTY0CJleHAiOjE3NDAxNzMxNjR9.AGS9D1dx8e6HoqUIYFZnc9K7v0gMOoTMcOflh4Nk4"
        }
    }]
}

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 404 Not Found

This response indicates that the specified repository was not found.

json

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

Response 422 Unprocessable Entity

Invalid request to get Repository Resources

json

{
    "error": {
        "code": "InvalidiTwinsRequest",
        "message": "Cannot query Repository Resources.",
        "details": [{
            "code": "InvalidValue",
            "message": "repositoryId contains an invalid value.",
            "target": "repositoryId"
        }]
    }
}

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

Repository Authentication Type

This value determines how to process the authentication information returned from the API.

Header

String

QueryParameter

String

Basic

String

json

{
    "type": "string",
    "title": "Repository Authentication Type",
    "description": "This value determines how to process the authentication information returned from the API.",
    "enum": [
        "Header",
        "QueryParameter",
        "Basic"
    ]
}

Graphics

type

ContentType

uri

String

A uri containing the location of the graphics content. This value can be cached but be aware that it might change over time. Some might contain a SAS key that expires after some time.

authentication

One of: ApiKey-Authentication Basic-Authentication

Some repositories require authentication. If authentication details are provided, inspect the authentication.type property to determine the required method. You may need to add a header, query parameter or use basic authentication.

provider

GraphicsProvider

Some repositories may provide additional information that can be used by a CesiumJS provider. The name and options will be provided here.

json

{
    "type": "object",
    "properties": {
        "type": {
            "$ref": "#/components/schemas/ContentType"
        },
        "uri": {
            "type": "string",
            "description": "A uri containing the location of the graphics content. This value can be cached but be aware that it might change over time. Some might contain a SAS key that expires after some time."
        },
        "authentication": {
            "oneOf": [
                {
                    "$ref": "#/components/schemas/ApiKey-Authentication"
                },
                {
                    "$ref": "#/components/schemas/Basic-Authentication"
                }
            ],
            "description": "Some repositories require authentication. If authentication details are provided, inspect the `authentication.type` property to determine the required method. You may need to add a header, query parameter or use basic authentication."
        },
        "provider": {
            "$ref": "#/components/schemas/GraphicsProvider",
            "description": "Some repositories may provide additional information that can be used by a CesiumJS provider. The name and options will be provided here."
        }
    },
    "required": [
        "type",
        "uri"
    ],
    "additionalProperties": false
}

GraphicsProvider

name

String

The name of the provider. Known values include UrlTemplateImageryProvider and Google2DImageryProvider. More will be added as needed.

options

One of: UrlTemplateImageryProviderOptions Google2DImageryProviderOptions

Additional options for the provider. The properties contained in options will depend on the provider name.

json

{
    "type": "object",
    "properties": {
        "name": {
            "type": "string",
            "description": "The name of the provider. Known values include [UrlTemplateImageryProvider](https://cesium.com/learn/cesiumjs/ref-doc/UrlTemplateImageryProvider.html) and [Google2DImageryProvider](https://cesium.com/learn/cesiumjs/ref-doc/Google2DImageryProvider.html#.ConstructorOptions). More will be added as needed."
        },
        "options": {
            "oneOf": [
                {
                    "$ref": "#/components/schemas/UrlTemplateImageryProviderOptions"
                },
                {
                    "$ref": "#/components/schemas/Google2DImageryProviderOptions"
                }
            ],
            "description": "Additional options for the provider. The properties contained in options will depend on the provider name."
        }
    },
    "additionalProperties": false
}

UrlTemplateImageryProviderOptions

bounds

Number[]

Bounding box as [west, south, east, north] in degrees. Use to create the Rectangle needed in the UrlTemplateImageryProvider constructor.

tilingScheme

String

The tiling scheme used (e.g., 'WebMercatorTilingScheme').

credit

String

Attribution or credit for the imagery provider.

json

{
    "type": "object",
    "properties": {
        "bounds": {
            "type": "array",
            "description": "Bounding box as [west, south, east, north] in degrees. Use to create the [Rectangle](https://cesium.com/learn/cesiumjs/ref-doc/Rectangle.html) needed in the UrlTemplateImageryProvider constructor.",
            "items": {
                "type": "number",
                "format": "double"
            },
            "minItems": 4,
            "maxItems": 4
        },
        "tilingScheme": {
            "type": "string",
            "description": "The tiling scheme used (e.g., 'WebMercatorTilingScheme')."
        },
        "credit": {
            "type": "string",
            "description": "Attribution or credit for the imagery provider."
        }
    },
    "additionalProperties": false
}

Google2DImageryProviderOptions

mapType

String

The type of map to display (e.g., 'terrain', 'satellite', 'roadmap').

url

String

The base URL for the Google Maps API.

session

String

The session token returned by the Google Maps API.

tileWidth

Integer

The width of each tile in pixels.

tileHeight

Integer

The height of each tile in pixels.

imageFormat

String

The image format for the tiles (e.g., 'png', 'jpeg').

json

{
    "type": "object",
    "properties": {
        "mapType": {
            "type": "string",
            "description": "The type of map to display (e.g., 'terrain', 'satellite', 'roadmap')."
        },
        "url": {
            "type": "string",
            "description": "The base URL for the Google Maps API."
        },
        "session": {
            "type": "string",
            "description": "The session token returned by the Google Maps API."
        },
        "tileWidth": {
            "type": "integer",
            "description": "The width of each tile in pixels."
        },
        "tileHeight": {
            "type": "integer",
            "description": "The height of each tile in pixels."
        },
        "imageFormat": {
            "type": "string",
            "description": "The image format for the tiles (e.g., 'png', 'jpeg')."
        }
    },
    "additionalProperties": false
}

ContentType

The type of graphics content.

3DTILES

String

GLTF

String

IMAGERY

String

TERRAIN

String

KML

String

CZML

String

GEOJSON

String

OAPIF+GEOJSON

String

json

{
    "type": "string",
    "enum": [
        "3DTILES",
        "GLTF",
        "IMAGERY",
        "TERRAIN",
        "KML",
        "CZML",
        "GEOJSON",
        "OAPIF+GEOJSON"
    ],
    "description": "The type of graphics content."
}

GraphicsArrayResponse

graphics

Graphics[]

List of graphics items for the resource.

json

{
    "type": "object",
    "properties": {
        "graphics": {
            "type": "array",
            "description": "List of graphics items for the resource.",
            "items": {
                "$ref": "#/components/schemas/Graphics"
            }
        }
    },
    "required": [
        "graphics"
    ],
    "additionalProperties": false
}

ApiKey-Authentication

Contains the information needed to authenticate to the specified API using an api key.

type

RepositoryAuthType

key

String

The key to use for Header or QueryParameter auth types.

value

String

The value to use for Header or QueryParameter auth types.

json

{
    "type": "object",
    "description": "Contains the information needed to authenticate to the specified API using an api key. ",
    "properties": {
        "type": {
            "$ref": "#/components/schemas/RepositoryAuthType"
        },
        "key": {
            "type": "string",
            "description": "The key to use for Header or QueryParameter auth types."
        },
        "value": {
            "type": "string",
            "description": "The value to use for Header or QueryParameter auth types."
        }
    },
    "required": [
        "type",
        "key",
        "value"
    ],
    "additionalProperties": false
}

Basic-Authentication

Contains the information needed to authenticate to the specified API using Basic authentication.

type

RepositoryAuthType

username

String

The username to use for Basic auth type.

password

String

The password to use for Basic auth type.

json

{
    "type": "object",
    "description": "Contains the information needed to authenticate to the specified API using Basic authentication.",
    "properties": {
        "type": {
            "$ref": "#/components/schemas/RepositoryAuthType"
        },
        "username": {
            "type": "string",
            "description": "The username to use for Basic auth type."
        },
        "password": {
            "type": "string",
            "description": "The password to use for Basic auth type."
        }
    },
    "required": [
        "type",
        "username",
        "password"
    ],
    "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

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

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?