Access 2D Tiles - Google Curated Content

Google Curated Content

Download API definition:

Access 2D Tiles

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

POST https://dev-api.bentley.com/curated-content/google/map-tiles/2d

Retrieves information and credentials that allow you to access the tiled content data for visualization and analysis.

Request headers

Authorization

Yes

OAuth access token with itwin-platform scope

Yes

Setting to application/vnd.bentley.google-2d-tiles-styles+json is recommended.

Access2DTilesRequest

mapType

MapType

Yes

language

String

Yes

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.

region

String

Yes

A Common Locale Data Repository region identifier (two uppercase letters) that represents the physical location of the user. For example, US.

imageFormat

String

scale

Scale

highDpi

Boolean

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

LayerTypes

overlay

Boolean

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.

styles

StyleObject[]

An array of JSON style objects that specify the appearance and detail level of map features such as roads, parks, and built-up areas. Styling is used to customize the standard Google base map. The styles parameter is valid only if the map type is roadmap.

Example

json

{
    "mapType": "terrain",
    "language": "en-US",
    "region": "US",
    "imageFormat": "jpeg",
    "scale": "scaleFactor2x",
    "highDpi": true,
    "layerTypes": [
        "layerRoadmap"
    ]
}

Response

Response 200 OK

json

{
    "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)

json

{
    "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.

json

{
    "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.

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

ContentType

The type of content.

3DTILES

String

IMAGERY

String

json

{
    "type": "string",
    "enum": [
        "3DTILES",
        "IMAGERY"
    ],
    "description": "The type of content."
}

Access2DTilesResponse

type

ContentType

viewportBaseUrl

String

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

String

The base url for the tileset requests.

accessToken

String

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

SessionInformation

json

{
    "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

token

String

A session token value that you must include in all of your Map Tiles API requests.

expiry

String

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

Number

The width of the tiles measured in pixels.

tileHeight

Number

The height of the tiles measured in pixels.

imageFormat

String

The image format, which can be either png or jpeg.

json

{
    "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

mapType

MapType

language

String

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.

region

String

A Common Locale Data Repository region identifier (two uppercase letters) that represents the physical location of the user. For example, US.

imageFormat

String

scale

Scale

highDpi

Boolean

layerTypes

LayerTypes

overlay

Boolean

styles

StyleObject[]

json

{
    "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."
        },
        "styles": {
            "type": "array",
            "description": "An array of JSON style objects that specify the appearance and detail level of map features such as roads, parks, and built-up areas. Styling is used to customize the standard Google base map. The `styles` parameter is valid only if the map type is `roadmap`.",
            "items": {
                "$ref": "#/components/schemas/StyleObject"
            }
        }
    },
    "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.

roadmap

String

satellite

String

terrain

String

json

{
    "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.

scaleFactor1x

String

scaleFactor2x

String

scaleFactor4x

String

json

{
    "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.

StyleObject featureType

The features to select for this style modification. Features are geographic characteristics on the map, including roads, parks, bodies of water, and more. If not specified, all features are selected.

all

String

administrative

String

administrative.country

String

administrative.land_parcel

String

administrative.locality

String

administrative.neighborhood

String

administrative.province

String

landscape

String

landscape.man_made

String

landscape.natural

String

landscape.natural.landcover

String

landscape.natural.terrain

String

poi

String

poi.attraction

String

poi.business

String

poi.government

String

poi.medical

String

poi.park

String

poi.place_of_worship

String

poi.school

String

poi.sports_complex

String

road

String

road.arterial

String

road.highway

String

road.highway.controlled_access

String

road.local

String

transit

String

transit.line

String

transit.station

String

transit.station.airport

String

transit.station.bus

String

transit.station.rail

String

water

String

json

{
    "type": "string",
    "enum": [
        "all",
        "administrative",
        "administrative.country",
        "administrative.land_parcel",
        "administrative.locality",
        "administrative.neighborhood",
        "administrative.province",
        "landscape",
        "landscape.man_made",
        "landscape.natural",
        "landscape.natural.landcover",
        "landscape.natural.terrain",
        "poi",
        "poi.attraction",
        "poi.business",
        "poi.government",
        "poi.medical",
        "poi.park",
        "poi.place_of_worship",
        "poi.school",
        "poi.sports_complex",
        "road",
        "road.arterial",
        "road.highway",
        "road.highway.controlled_access",
        "road.local",
        "transit",
        "transit.line",
        "transit.station",
        "transit.station.airport",
        "transit.station.bus",
        "transit.station.rail",
        "water"
    ],
    "description": "The features to select for this style modification. Features are geographic characteristics on the map, including roads, parks, bodies of water, and more. If not specified, all features are selected.",
    "title": "StyleObject featureType"
}

StyleObject elementType

The property of the specified feature to select. Elements are sub-parts of a feature, including labels and geometry. If not specified, all elements of the feature are selected.

all

String

geometry

String

geometry.fill

String

geometry.stroke

String

labels

String

labels.icon

String

labels.text

String

labels.text.fill

String

labels.text.stroke

String

json

{
    "type": "string",
    "enum": [
        "all",
        "geometry",
        "geometry.fill",
        "geometry.stroke",
        "labels",
        "labels.icon",
        "labels.text",
        "labels.text.fill",
        "labels.text.stroke"
    ],
    "description": "The property of the specified feature to select. Elements are sub-parts of a feature, including labels and geometry. If not specified, all elements of the feature are selected.",
    "title": "StyleObject elementType"
}

StyleObject

A JSON style object that specifies the appearance and detail level of map features.

StyleObject featureType

StyleObject-featureType

The features to select for this style modification. Features are geographic characteristics on the map, including roads, parks, bodies of water, and more. If not specified, all features are selected.

StyleObject elementType

StyleObject-elementType

The property of the specified feature to select. Elements are sub-parts of a feature, including labels and geometry. If not specified, all elements of the feature are selected.

stylers

Styler[]

The rules to apply to the selected features and elements. Stylers indicate the color, visibility, and weight of the feature.

json

{
    "type": "object",
    "description": "A JSON style object that specifies the appearance and detail level of map features.",
    "properties": {
        "featureType": {
            "type": "string",
            "enum": [
                "all",
                "administrative",
                "administrative.country",
                "administrative.land_parcel",
                "administrative.locality",
                "administrative.neighborhood",
                "administrative.province",
                "landscape",
                "landscape.man_made",
                "landscape.natural",
                "landscape.natural.landcover",
                "landscape.natural.terrain",
                "poi",
                "poi.attraction",
                "poi.business",
                "poi.government",
                "poi.medical",
                "poi.park",
                "poi.place_of_worship",
                "poi.school",
                "poi.sports_complex",
                "road",
                "road.arterial",
                "road.highway",
                "road.highway.controlled_access",
                "road.local",
                "transit",
                "transit.line",
                "transit.station",
                "transit.station.airport",
                "transit.station.bus",
                "transit.station.rail",
                "water"
            ],
            "description": "The features to select for this style modification. Features are geographic characteristics on the map, including roads, parks, bodies of water, and more. If not specified, all features are selected.",
            "title": "StyleObject featureType",
            "$ref": "#/components/schemas/StyleObject-featureType"
        },
        "elementType": {
            "type": "string",
            "enum": [
                "all",
                "geometry",
                "geometry.fill",
                "geometry.stroke",
                "labels",
                "labels.icon",
                "labels.text",
                "labels.text.fill",
                "labels.text.stroke"
            ],
            "description": "The property of the specified feature to select. Elements are sub-parts of a feature, including labels and geometry. If not specified, all elements of the feature are selected.",
            "title": "StyleObject elementType",
            "$ref": "#/components/schemas/StyleObject-elementType"
        },
        "stylers": {
            "type": "array",
            "description": "The rules to apply to the selected features and elements. Stylers indicate the color, visibility, and weight of the feature.",
            "items": {
                "$ref": "#/components/schemas/Styler"
            },
            "minItems": 1
        }
    },
    "required": [
        "stylers"
    ],
    "additionalProperties": false
}

Styler visibility

Indicates whether and how the element appears on the map. 'simplified' removes some style features from the affected features.

String

off

String

simplified

String

json

{
    "type": "string",
    "enum": [
        "on",
        "off",
        "simplified"
    ],
    "description": "Indicates whether and how the element appears on the map. 'simplified' removes some style features from the affected features.",
    "title": "Styler visibility"
}

Styler

A style rule that can be applied to map features and elements.

hue

String

An RGB hex string of format #RRGGBB that indicates the basic color.

lightness

Number

A floating point value between -100 and 100 that indicates the percentage change in brightness of the element.

saturation

Number

A floating point value between -100 and 100 that indicates the percentage change in intensity of the basic color.

gamma

Number

A floating point value between 0.01 and 10.0 that indicates the amount of gamma correction to apply to the element.

invert_lightness

Boolean

If true, inverts the existing lightness. This is useful for quickly switching to a darker map with white text.

Styler visibility

Styler-visibility

Indicates whether and how the element appears on the map. 'simplified' removes some style features from the affected features.

color

String

An RGB hex string of format #RRGGBB that sets the color of the feature.

weight

Integer

An integer value, greater than or equal to zero, that sets the weight of the feature in pixels.

json

{
    "type": "object",
    "description": "A style rule that can be applied to map features and elements.",
    "properties": {
        "hue": {
            "type": "string",
            "pattern": "^#[0-9A-Fa-f]{6}$",
            "description": "An RGB hex string of format #RRGGBB that indicates the basic color."
        },
        "lightness": {
            "type": "number",
            "minimum": -100,
            "maximum": 100,
            "description": "A floating point value between -100 and 100 that indicates the percentage change in brightness of the element."
        },
        "saturation": {
            "type": "number",
            "minimum": -100,
            "maximum": 100,
            "description": "A floating point value between -100 and 100 that indicates the percentage change in intensity of the basic color."
        },
        "gamma": {
            "type": "number",
            "minimum": 0.01,
            "maximum": 10,
            "description": "A floating point value between 0.01 and 10.0 that indicates the amount of gamma correction to apply to the element."
        },
        "invert_lightness": {
            "type": "boolean",
            "description": "If true, inverts the existing lightness. This is useful for quickly switching to a darker map with white text."
        },
        "visibility": {
            "type": "string",
            "enum": [
                "on",
                "off",
                "simplified"
            ],
            "description": "Indicates whether and how the element appears on the map. 'simplified' removes some style features from the affected features.",
            "title": "Styler visibility",
            "$ref": "#/components/schemas/Styler-visibility"
        },
        "color": {
            "type": "string",
            "pattern": "^#[0-9A-Fa-f]{6}$",
            "description": "An RGB hex string of format #RRGGBB that sets the color of the feature."
        },
        "weight": {
            "type": "integer",
            "minimum": 0,
            "description": "An integer value, greater than or equal to zero, that sets the weight of the feature in pixels."
        }
    },
    "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?