Overview
The Tile API allows direct access to Google Maps tiles, including map tiles, satellite imagery, terrain imagery, Street View tiles, and various overlay data.
Once you have a whitelisted API key, accessing the Tile API involves the following steps:
- Retrieve a session token, specifying the options for the session.
- Use the session token to request a map tile.
- Retrieve viewport information to obtain details about the tiles being displayed.
If you'd like to request Street View panoramas, see the Street View guide.
API key
Every request to the Tile API must contain an API key
as the value of akey
URL parameter. You may use a generic (unrestricted)
API key. We recommend that you use a browser-restricted API key. This key identifies your
application and ties it to your available quota.
If you have an existing unrestricted key, or a key with browser restrictions, you may use that key.
Follow these steps to get an API key:
- Go to the API page in the Cloud Console.
- Select the project created for you by Google Cloud Support when you purchased the Tile API. The project name will always start with Google Maps Platform Premium Plan Project. If you have not yet purchased access to the API, please contact Sales.
- Click Continue to enable the API and any related services.
- On the Credentials page, get an API key (and set the API key restrictions).
Note: If you have an existing unrestricted key, or a key with browser restrictions, you may use that key. - To prevent quota theft, secure your API key following these best practices.
In the Cloud Console, you can also look up an existing key or view a list of enabled APIs.
For more information on using the Cloud Console, see Google Cloud Console Help.
Session tokens
To request tiles from the API, you must first request a session token. This session token is required for subsequent requests for tile and viewport information.
A session token represents a defined set of display options, so that
individual tile requests do not need to pass display options each time. A
session token can be used across multiple clients. A session token is currently
valid for 2 weeks from its creation time, but this may change without notice.
The expiry
field in the response may be used to check the expiration time of
the token.
Session token request
Creating a session token is done through an HTTP POST request in the following form:
https://www.googleapis.com/tile/v1/createSession?key=YOUR_API_KEY
The request body is a JSON object; for example:
{
"mapType": "satellite",
"language": "ja-JP",
"region": "jp",
"layerTypes": [ "layerRoadmap", "layerStreetview" ],
"overlay": true,
"scale": "scaleFactor1x"
}
Required fields
mapType
: The type of base map. This can be one of the following:
roadmap
: The standard Google Maps painted map tiles.satellite
: Satellite imagery.terrain
: Shaded relief maps of 3D terrain. When selectingterrain
as the map type, you must also include thelayerRoadmap
layer type (described in the Optional fields section below).streetview
: Street View panoramas. See the Street View guide.
language
: A
CLDR language
identifier indicating the language information on the tiles should be
presented in. For example, en-US
or ja-JP
.
region
: A CLDR region identifier representing the physical
location of the user to whom we are showing these tiles. e.g. fr
.
Optional fields
imageFormat
: Either of jpeg
or png
, specifying the file format to
return. Note that JPEG files do not support transparency, so are not
recommended for overlay tiles. If no imageFormat
is specified, the best
format for the tile will be selected automatically.
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 will also reduce the number of labels on the map, to reduce clutter.
Valid values are:
scaleFactor1x
: The default.scaleFactor2x
: Doubles label size and eliminates minor feature labels.scaleFactor4x
: Quadruples label size and eliminates minor feature labels.
Example tiles are below:
scaleFactor1x | scaleFactor2x | scaleFactor4x |
---|---|---|
![]() |
![]() |
![]() |
highDpi
: Specifies whether to return high DPI tiles. If true
, the number
of pixels in each of the x and y dimensions are multiplied by the scale factor
value (ie. 2x or 4x), while the coverage area of the tile is unchanged. This
parameter only works with scale
values of 2x or 4x; it has no effect on 1x
scale tiles.
scaleFactor1x | scaleFactor2x | scaleFactor2x high DPI |
---|---|---|
![]() |
![]() |
![]() |
layerTypes
An array of values representing the layer type(s) to be added
to the map. Supported layers currently are:
layerRoadmap
- Required ifterrain
is specified as the mapType. Can also be optionally overlaid on thesatellite
mapType. Has no effect on roadmap tiles.layerStreetview
- Shows Street View-enabled streets and locations using blue outlines on the map.layerTraffic
- Displays current traffic conditions.
styles
: An array of style objects that define the appearance and detail
level of map features such as roads, parks, and built-up areas, in order to
customize the standard Google base map. The styles
parameter is only valid
if the mapType
is roadmap
. For the full style syntax see the
style reference. You can use the
Maps Platform Styling Wizard to define your colors and
generate valid styler objects.
overlay
: A boolean value defining whether specified layerTypes should be
rendered as a separate overlay, or combined with the base imagery. When
true
, the base map is not displayed.
For example, requesting a satellite
mapType with a layerRoadmap
layer,
and overlay
set to false will result in tiles equivalent to the hybrid
map type used in the Maps JavaScript API (image on left
below). The same map and layer types with overlay
set to true
will result
in a transparent tile with a map overlay, styled appropriately for overlaying
over satellite imagery (image on right below).
"overlay": false | "overlay": true |
---|---|
![]() |
![]() |
An example JSON object is as follows:
{
"mapType": "satellite",
"language": "ja-JP",
"region": "jp",
"layerTypes": [ "layerRoadmap", "layerStreetview" ],
"overlay": true,
"scale": "scaleFactor1x",
"styles": [
{
"stylers": [
{ "hue": "#00ffe6" },
{ "saturation": -20 }
]
},{
"featureType": "road",
"elementType": "geometry",
"stylers": [
{ "lightness": 100 },
{ "visibility": "simplified" }
]
}
]
}
This example provides an overlay suitable for combining with satellite imagery, containing both a roadmap and Street View overlay. It will be rendered in Japanese, with naming conventions and data appropriate for Japan.
channel
: Similar to the
channel
value available in the Maps JavaScript API, you can use the
channel
parameter in your session token, map tile and viewport requests to track
usage across applications using the same session token. You must include this
parameter in the URL string, not in the POST body of session token requests.
To obtain usage reports broken down by channel, contact Google Cloud Support.
apiOptions
: An array of values specifying additional options to apply.
Supported options currently are:
B3MWHUG2MR0DQW
- Opt-in to the updated Google Maps basemap. During the opt-in period, your requests will get the existing style unless this value is specified.B3H9HE845CFHYG
- Opt-out of the updated Google Maps basemap. During the opt-out period, your requests will get the updated style unless this value is specified.
Session token response
An example response is as follows:
{
"session": "IgAAAHGU9jnAU4KOAfwY3Bcd6eH_WxQsyocSBAdUnAr9pnvTTNXtF9c_27RBo94ytEXTDg",
"expiry": "1361828036",
"tileWidth": 256,
"tileHeight": 256,
"imageFormat": "png"
}
The fields are as follows:
session
- A token to be included in subsequent requests.expiry
- A string that contains the time (in seconds since the epoch) at which the token will expire. A session token is currently valid for 2 weeks from its creation time, but this may change without notice.tile(Width|Height)
- The width and height (in pixels) of the tiles which will be returned.imageFormat
- The image format returned. Currently one of "png" or "jpeg".
Map tiles
Once you have a session token, you can make tile requests. Because each session token is tied to the particular request, you don’t need to specify the map options with each tile request.
Tile requests
Tile requests are made via a HTTP GET request.
For example:
https://www.googleapis.com/tile/v1/tiles/z/x/y
?session=session token
&orientation=0 | 90 | 180 | 270
&key=YOUR_API_KEY
where z
is the zoom level, and
x
and y
are the x
and y tile coordinates of the tile you wish to retrieve. Tile coordinates are
described in detail in the guide to map and tile coordinates in the
Maps JavaScript API documentation.
The optional orientation
parameter defines the counter-clockwise rotation of
the tile image in degrees. Orientation is supported for roadmap
tiles, and
for roadmap, satellite, or terrain requests with "overlay": true
.
Acceptable orientation
values are 0 (default), 90, 180, and 270.
When an orientation value is included, the tile coordinate grid is not
rotated; for example, if orientation
is set to 90, the
x
coordinate will still define the left-to-right
position of the tile, which in this case will be from north to south on the map:
Example request
As an example, requesting a single tile containing the whole world would be:
https://www.googleapis.com/tile/v1/tiles/0/0/0?session=session token&key=YOUR_API_KEY
Which is zoom level 0 (where the whole world fits on a single tile), and x and y coordinates (0, 0).
Tile coordinate functions
Tools or simple functions are available in most programming languages to convert from latitude/longitude pairs to tile coordinates at specific zoom levels. For example, in JavaScript:
var TILE_SIZE = 256;
function fromLatLngToPoint(latLng) {
var mercator = -Math.log(Math.tan((0.25 + latLng.lat() / 360) * Math.PI));
return {
x: TILE_SIZE * (latLng.lng() / 360 + 0.5),
y: TILE_SIZE / 2 * (1 + mercator / Math.PI)
};
}
function fromLatLngToTileCoord(latLng, zoom) {
var point = fromLatLngToPoint(latLng);
var scale = Math.pow(2, zoom);
return {
x: Math.floor(point.x * scale / TILE_SIZE),
y: Math.floor(point.y * scale / TILE_SIZE),
z: zoom
};
}
Tile responses
A successful map tile request returns an image of the format and size specified
in the createSession
response:
As with all HTTP responses, it is accompanied by HTTP response headers. Of
particular importance are the values of the cache-control
header:
private
: Indicates that the response is intended for a single user and may not be cached in a shared cache. It may be cached in a private cache.max-age
: Your client must respect themax-age
value that is passed in the response. The value ofmax-age
is expressed in seconds, and may vary depending on the type of resource being requested and/or specific options.must-revalidate
: If the cached resource is stale, you MUST send a new request to the Tile API to request a fresh resource.no-transform
: The returned image may not be modified, including its headers.
These header fields are described in more detail in the HTTP/1.1 protocol documentation.
Viewport information requests
Viewport information requests return important information about the tiles that make up your current viewport. This information currently includes the necessary attribution to be displayed with your map, and maximum zoom levels that aid in building a zoom slider.
The viewport request is an HTTP GET request in the following form:
https://www.googleapis.com/tile/v1/viewport
?session=session token
&zoom=zoom
&north=north&south=south&east=east&west=west
&key=YOUR_API_KEY
Where:
zoom
is the current zoom level of the viewport.north
,south
,east
,west
are the furthest north, south, east, and west points in the viewport expressed in degrees. North and south must be in the range (-90,90), east and west must be in the range (-180, 180). To express bounds crossing the antimeridian, west can be positive (e.g. 170) and east can be negative (e.g. -170).
All parameters are required.
Viewport information responses
The response is of the following form:
{
"copyright": "Map data ©2013 Google",
"maxZoomRect": [
{
"maxZoom": 8,
"south": -90,
"west": -180
"north": 90,
"east": 180
}, ...
]
}
The copyright
field contains an attribution string which must be visible on
the map. The maxZoomRect
field contains an array of bounding rectangles which
overlap with the current viewport and the maximum zoom level available within
each rectangle.
Usage limits
Each tile request counts against your project's quota for the Tile API.
The session token requests and viewport information requests do not consume quota.
Errors
If your request returns an error, the HTTP code is in the 400 or 500 range, and an error object is returned:
{
"error": {
"errors": [
{
"domain": "global",
"reason": "required",
"message": ""\"mapType\" is a required field"",
"location": "mapType"
}
],
"code": 400,
"message": ""
}
}
An error object contains the following fields:
domain
: A broad indication of the error type. Most errors fall into theglobal
domain; other domains includeusageLimits
.reason
: The reason that the API request failed. Your client should use this field when recognizing errors.message
: A human-readable version of thereason
field. The contents of this message may change, so your client should not rely on it being consistent.location
: The exact parameter name of the offending value.code
: The HTTP code associated with this error.
It is possible for the errors
array to contain more than one error.
Error reasons
Some possible errors include:
required
: Your request is missing a URL parameter. The error message will specify the missing parameter.notFound
: Yourx
,y
, orz
values are out of range:- For regular map tiles, the maximum zoom level depends on the particular map tile and map options being requested.
- For regular map types, the x coordinate must be in the range [0, (2^zoom)-1].
- For regular map types, the y coordinate must be in the range [0, (2^(zoom-1))-1].
- For Street View tiles, zoom must be between 0 and 5, inclusive.
- For Street View tiles, the x and y coordinate ranges are the same as
for regular map types, until level 5 zoom. At that point, the maximum
values are
imageHeight
orimagewidth
divided bytileHeight
ortileWidth
.
invalidCredentials
: Thesession
URL parameter is not a valid value. Generate a new value, as described in the Session tokens section of this page.authTokenExpired
: Yoursession
token has expired. A session token is currently valid for 2 weeks from its creation time, but this may change without notice. Generate a new value, as described in the Session tokens section of this page.badRequest
: Your request was not formed correctly. Common reasons include specifying aterrain
map type without including aroadmap
layer; including astyles
array for a non-roadmap map type; or sending lat/lng as well as a panorama ID in a Street View metadata request.quotaExceeded
andrateLimitExceeded
: Your application has exceeded its allowed quota or queries per second.
Exponential backoff
When requests fail, you should ensure that you retry requests with exponential backoff. For example, if a request fails once, retry after a second, if it fails again, retry after two seconds, then four seconds, and so on. This ensures that broken requests or wide scale failures do not flood Google’s servers, as many clients try to retry requests very quickly.