2D Tiles overview

Map Tiles are simply the division of the world into an indexed grid. It lets you access and utilize map data efficiently and dynamically at multiple cartographic scales. Map Tiles API gives you access to multiple thematic geodatasets, including Google-curated:

• Roadmap image tiles based on vector topographic data with Google’s cartographic styling.

• Orthophotography captured by both satellite and airborne cameras that deliver top down (nadir) imagery of the earth.

• Hillshade contour maps.

2D Map Tiles are all georeferenced and aligned to each other. They're selected based on the geographic extent of the viewport and the zoom level. Zoom levels range from zero (to view the world in its entirety) to 22 (to view streets and blocks).

Map themes

You can get map tiles for the following map themes.

Map theme	Description
Roadmap	Roads, buildings, points of interest, and political boundaries
Satellite	Photographic imagery taken from space
Terrain	A contour map that shows natural features such as vegetation

Note: Map tiles can consist of one or more layers. For example, a roadmap layer can be overlaid on top of a satellite map theme. For more information, see Optional fields.

To request map tiles from Map Tiles API, you must first request a session token. The session token tracks the current state of your map and viewport. When you set up your session token, you must set the mapType value to match the map theme that you want. Then, you must include the session token in each of your requests to Map Tiles API.

Viewport information requests

The viewport defines the size of the box that frames the world scene. Viewport information requests return details about the map tiles that make up your current viewport. The reason that you request viewport information is to ensure that you avoid requesting imagery at zoom levels that don't exist.

For example, most cities have imagery at zoom level 22, but not the ocean since it would just end up displaying featureless blue squares.

Note: Included in the response is the attribution that you must display with your map, and the maximum zoom level—so you can build a zoom slider. For more information, see the Map Tiles API Policies.

The viewport request is an HTTPS GET request in the following form.

curl "https://tile.googleapis.com/tile/v1/viewport?session=YOUR_SESSION_TOKEN&key=YOUR_API_KEY&zoom=zoom&north=north&south=south&east=east&west=west"

The request contains the following fields:

zoom

The zoom level of the viewport.

north, south, east, west

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 (for example, 170) and east can be negative (for example, -170). All parameters are required.

Viewport information responses

The viewport response tells you which areas have imagery, and at which zoom levels. A viewport information response has the following form.

{
  "copyright": "Map data ©2023",
  "maxZoomRects": [
    {
      "maxZoom": 19,
      "north": 90,
      "south": -90,
      "east": 180,
      "west": -180
    },
    {
      "maxZoom": 9,
      "north": 90,
      "south": -90,
      "east": 180,
      "west": -180
    },
    {
      "maxZoom": 14,
      "north": 84.375,
      "south": -84.375,
      "east": 180,
      "west": -180
    }, ...
  ]
}

Note: In this example, the maxZoomRects array contains more objects than is shown.

The response body contains the following fields.

copyright

Contains an attribution string that you must display on your map when you display roadmap and satellite tiles. For more information, see the Map Tiles API Policies.

maxZoomRect

Contains an array of bounding rectangles that overlap with the current viewport. Also contains the maximum zoom level available within each rectangle.

Tile coordinate functions

Tools (simple functions) are available in most programming languages to convert from latitude/longitude pairs to tile coordinates at a specific zoom level. Consider the following JavaScript code example that first converts from a latLng to a point, and then from a point to tile coordinates.

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
  };
}