Retrieves information and credentials that allow you to access the tiled content data for visualization and analysis.
Request headers
OAuth access token with itwin-platform
scope
Setting to application/vnd.bentley.return-full-session-info+json
is recommended.
Request body
Access2DTilesRequest
An IETF language tag that specifies the language used to display information on the tiles. For example, en-US specifies the English language as spoken in the United States.
A Common Locale Data Repository region identifier (two uppercase letters) that represents the physical location of the user. For example, US
.
Specifies whether to return high-resolution tiles. If the scale-factor is increased, highDpi is used to increase the size of the tile. Normally, increasing the scale factor enlarges the resulting tile into an image of the same size, which lowers quality. With highDpi, the resulting size is also increased, preserving quality. DPI stands for Dots per Inch, and High DPI means the tile renders using more dots per inch than normal. If true, then the number of pixels in each of the x and y dimensions is multiplied by the scale factor (that is , scaleFactor2x
or scaleFactor4x
). The coverage area of the tile remains unchanged. This parameter works only with scale values of scaleFactor2x
or scaleFactor4x
. It has no effect on scaleFactor1x
scale tiles.
A boolean value that specifies whether layerTypes
should be rendered as a separate overlay, or combined with the base imagery. When true
, the base map isn't displayed. If you haven't defined any layerTypes
, then this value is ignored.
Example
{ "mapType": "terrain", "language": "en-US", "region": "US", "imageFormat": "jpeg", "scale": "scaleFactor2x", "highDpi": true, "layerTypes": [ "layerRoadmap" ] }
Response 200 OK
OK
{ "type": "IMAGERY", "viewportBaseUrl": "https://tile.googleapis.com/tile/v1/viewport", "tileBaseUrl": "https://tile.googleapis.com/v1/2dtiles", "accessToken": "ya29.c.c0ASRK0Gb9O...5I0c5-", "session": { "token": "AJV....HyTiZNQ", "expiry": "1747320703", "tileWidth": 256, "imageFormat": "png", "tileHeight": 256 } }
Response 400 Bad Request
The 400 (Bad Request) status code indicates that the request cannot be processed by the server due to a client error (e.g. malformed request syntax)
{ "error": { "code": "InvalidGoogleCuratedContentRequest", "message": "Request body is invalid.", "details": [{ "code": "InvalidRequestBody", "message": "Invalid request body.", "target": "mapType" }] } }
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.
{ "error": { "code": "HeaderNotFound", "message": "Header Authorization was not found in the request. Access denied." } }
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.
{ "error": { "code": "RateLimitExceeded", "message": "The client sent more requests than allowed by this API for the current tier of the client." } }
Response headers
Number of seconds to wait until client is allowed to make more requests.
ContentType
The type of content.
{ "type": "string", "enum": [ "3DTILES", "IMAGERY" ], "description": "The type of content." }
Access2DTilesResponse
The base url for the viewport requests. The viewport defines the size of the box that frames the world scene. This request also returns the attribution string that you must display on your map when you display roadmap and satellite tiles.
The base url for the tileset requests.
The token to be included with each tile request, using Bearer format. This token is different than the access token used throughout the rest of the REST API. It provides access to the content for approximately one hour. To continue using the content after the allotted time, simple re-request the endpoint for a new token.
{ "type": "object", "properties": { "type": { "$ref": "#/components/schemas/ContentType" }, "viewportBaseUrl": { "type": "string", "description": "The base url for the viewport requests. The viewport defines the size of the box that frames the world scene. This request also returns the attribution string that you must display on your map when you display roadmap and satellite tiles. " }, "tileBaseUrl": { "type": "string", "description": "The base url for the tileset requests." }, "accessToken": { "type": "string", "description": "The token to be included with each tile request, using Bearer format. This token is different than the access token used throughout the rest of the REST API. It provides access to the content for approximately one hour. To continue using the content after the allotted time, simple re-request the endpoint for a new token." }, "session": { "$ref": "#/components/schemas/SessionInformation" } }, "additionalProperties": false }
SessionInformation
A session token value that you must include in all of your Map Tiles API requests.
A string that contains the time (in seconds since the epoch) at which the token expires. A session token is valid for two weeks from its creation time, but this policy might change without notice.
The width of the tiles measured in pixels.
The height of the tiles measured in pixels.
The image format, which can be either png
or jpeg
.
{ "type": "object", "properties": { "token": { "type": "string", "description": "A session token value that you must include in all of your Map Tiles API requests." }, "expiry": { "type": "string", "description": "A string that contains the time (in seconds since the epoch) at which the token expires. A session token is valid for two weeks from its creation time, but this policy might change without notice." }, "tileWidth": { "type": "number", "description": "The width of the tiles measured in pixels." }, "tileHeight": { "type": "number", "description": "The height of the tiles measured in pixels." }, "imageFormat": { "type": "string", "description": "The image format, which can be either `png` or `jpeg`." } }, "additionalProperties": false }
Access2DTilesRequest
An IETF language tag that specifies the language used to display information on the tiles. For example, en-US specifies the English language as spoken in the United States.
A Common Locale Data Repository region identifier (two uppercase letters) that represents the physical location of the user. For example, US
.
Specifies whether to return high-resolution tiles. If the scale-factor is increased, highDpi is used to increase the size of the tile. Normally, increasing the scale factor enlarges the resulting tile into an image of the same size, which lowers quality. With highDpi, the resulting size is also increased, preserving quality. DPI stands for Dots per Inch, and High DPI means the tile renders using more dots per inch than normal. If true, then the number of pixels in each of the x and y dimensions is multiplied by the scale factor (that is , scaleFactor2x
or scaleFactor4x
). The coverage area of the tile remains unchanged. This parameter works only with scale values of scaleFactor2x
or scaleFactor4x
. It has no effect on scaleFactor1x
scale tiles.
A boolean value that specifies whether layerTypes
should be rendered as a separate overlay, or combined with the base imagery. When true
, the base map isn't displayed. If you haven't defined any layerTypes
, then this value is ignored.
{ "type": "object", "properties": { "mapType": { "$ref": "#/components/schemas/MapType" }, "language": { "type": "string", "description": "An [IETF language tag](https://en.wikipedia.org/wiki/IETF_language_tag) that specifies the language used to display information on the tiles. For example, en-US specifies the English language as spoken in the United States." }, "region": { "type": "string", "description": "A [Common Locale Data Repository](https://cldr.unicode.org/) region identifier (two uppercase letters) that represents the physical location of the user. For example, `US`." }, "imageFormat": { "type": "string", "description": "" }, "scale": { "$ref": "#/components/schemas/Scale" }, "highDpi": { "type": "boolean", "description": "Specifies whether to return high-resolution tiles. If the scale-factor is increased, highDpi is used to increase the size of the tile. Normally, increasing the scale factor enlarges the resulting tile into an image of the same size, which lowers quality. With highDpi, the resulting size is also increased, preserving quality. DPI stands for Dots per Inch, and High DPI means the tile renders using more dots per inch than normal. If true, then the number of pixels in each of the x and y dimensions is multiplied by the scale factor (that is , `scaleFactor2x` or `scaleFactor4x`). The coverage area of the tile remains unchanged. This parameter works only with scale values of `scaleFactor2x` or `scaleFactor4x`. It has no effect on `scaleFactor1x` scale tiles." }, "layerTypes": { "$ref": "#/components/schemas/LayerTypes" }, "overlay": { "type": "boolean", "description": "A boolean value that specifies whether `layerTypes` should be rendered as a separate overlay, or combined with the base imagery. When `true`, the base map isn't displayed. If you haven't defined any `layerTypes`, then this value is ignored." } }, "required": [ "mapType", "language", "region" ], "additionalProperties": false }
MapType
The type of base map. roadmap
is the standard Google Maps painted on map tiles. satellite
is satellite imagery. terrain
is Terrain imagery. When selecting terrain as the map type, you must also include the layerRoadmap
layer type.
{ "type": "string", "enum": [ "roadmap", "satellite", "terrain" ], "description": "The type of base map. `roadmap` is the standard Google Maps painted on map tiles. `satellite` is satellite imagery. `terrain` is Terrain imagery. When selecting terrain as the map type, you must also include the `layerRoadmap` layer type." }
Scale
Scales-up the size of map elements (such as road labels), while retaining the tile size and coverage area of the default tile. Increasing the scale also reduces the number of labels on the map, which reduces clutter. The default scale is scaleFactor1x
.
{ "type": "string", "enum": [ "scaleFactor1x", "scaleFactor2x", "scaleFactor4x" ], "description": "Scales-up the size of map elements (such as road labels), while retaining the tile size and coverage area of the default tile. Increasing the scale also reduces the number of labels on the map, which reduces clutter. The default scale is `scaleFactor1x`." }
LayerTypes
An array of values that specifies the layer types added to the map.
DetailedError
Contains error information and an array of more specific errors.
One of a server-defined set of error codes.
A human-readable representation of the error.
The target of the error.
{ "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.
{ "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.
One of a server-defined set of error codes.
A human-readable representation of the error.
The target of the error.
{ "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.
{ "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?