Google Maps Tile API

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:

  1. Retrieve a session token, specifying the options for the session.
  2. Use the session token to request a map tile.
  3. 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:

  1. Go to the Google Cloud Platform Console.
  2. 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.
  3. Click Continue to enable the API and any related services.
  4. 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.
  5. To prevent quota theft, secure your API key following these best practices.

In the Google Cloud Platform Console, you can also look up an existing key or view a list of enabled APIs.

For more information on using the Google Cloud Platform Console, see Google Cloud Platform 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 selecting terrain as the map type, you must also include the layerRoadmap 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 if terrain is specified as the mapType. Can also be optionally overlaid on the satellite 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 the max-age value that is passed in the response. The value of max-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 the global domain; other domains include usageLimits.
  • reason: The reason that the API request failed. Your client should use this field when recognizing errors.
  • message: A human-readable version of the reason 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: Your x, y, or z 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 or imagewidth divided by tileHeight or tileWidth.

  • invalidCredentials: The session URL parameter is not a valid value. Generate a new value, as described in the Session tokens section of this page.

  • authTokenExpired: Your session 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 a terrain map type without including a roadmap layer; including a styles array for a non-roadmap map type; or sending lat/lng as well as a panorama ID in a Street View metadata request.

  • quotaExceeded and rateLimitExceeded: 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.