Map Types

This document discusses the types of maps you can display using the
Maps JavaScript API. The API uses a MapType
object to hold information about these maps. A MapType
is an interface that defines the display and usage of map tiles and
the translation of coordinate systems from screen coordinates to world
coordinates (on the map). Each MapType must contain a
few methods to handle retrieval and release of tiles, and properties
that define its visual behavior.

The inner workings of map types within the Maps JavaScript API
is an advanced topic. Most developers can simply use the
basic map types noted below. However, you can also modify the presentation of
existing map types using Styled Maps
or define your own map tiles using custom map types.
When providing custom map types, you will need to understand how to modify the map's
Map Type Registry.

Basic Map Types

There are four types of maps available within the Maps JavaScript API.
In addition to the familiar "painted" road map tiles, the
Maps JavaScript API also supports other maps types.

The following map types are available in the Maps JavaScript API:

roadmap displays the default road map view. This
is the default map type.

satellite displays Google Earth satellite
images.

hybrid displays a mixture of normal and satellite
views.

terrain displays a physical map based on terrain
information.

You modify the map type in use by the Map by setting its
mapTypeId property, either within the constructor via setting
its Map options object, or by calling the map's
setMapTypeId() method. The mapTypeID property
defaults to roadmap.

Note that you don't actually set the map's map type directly,
but instead set its mapTypeId to reference a
MapType using an identifier.
The Maps JavaScript API uses a map type registry,
explained below, to manage these references.

45° Imagery

The Maps JavaScript API supports special 45° imagery for
certain locations. This high-resolution imagery provides
perspective views towards each of the cardinal direction
(North, South, East, West). These images are available at higher
zoom levels for supported map types.

The following image shows a 45° perspective view of
the boardwalk in Santa Cruz, CA:

Samples may not be available in your region.

The satellite and
hybrid map types support 45° imagery at
high zoom levels where available. If the user zooms into a location for which
such imagery exists, these map types automatically alter their views in the
following manner:

The satellite or hybrid imagery is replaced with imagery giving a 45°
perspective, centered on the current location. By default, such views are
oriented towards north. If the user zooms out, the default satellite or
hybrid imagery appears again.

The rotate control provides a combination of tilt and rotate options.
If rotateControl is true, a tilt control appears
when 45° imagery is available. The tilt control allows the user to tilt the
imagery to a 45° angle.

When the imagery is tilted, a hook appears, allowing users to
rotate the view 90° in a clockwise direction.

Zooming out from a map type displaying 45° imagery reverts
each of these changes, re-establishing the original map types.

Enabling and Disabling 45° Imagery

You can disable 45° imagery by calling setTilt(0) on the
Map object. To enable 45° imagery for supported map types,
call setTilt(45).

The Map's getTilt() method
will always reflect the current tilt being shown on the map; if you
set a tilt on a map and then later remove that tilt (by zooming the
map out, for example), the map's getTilt() method will
return 0.

Rotating 45° Imagery

The 45° imagery actually consists of a collection of images
for each cardinal direction (North, South, East, West). Once your map
is displaying 45° imagery, you can orient the
imagery towards one of its cardinal directions by calling
setHeading() on the Map object, passing
a number value expressed as degrees from North.

The following example shows an aerial map and auto-rotates
the map every 3 seconds when the button is clicked:

Modifying the Map Type Registry

A map's mapTypeId is a string identifier
that is used to associate a MapType with a
unique value. Each Map object maintains a
MapTypeRegistry which contains the collection of
available MapTypes for that map. This registry
is used to select the types of maps which are available in
the Map's MapType control, for example.

You do not read directly from the map type registry. Instead,
you modify the registry by adding custom map types and associating
them with a string identifier of your choosing. You cannot modify
or alter the basic map types (though you can remove them from the
map by altering the appearance of the map's associated
mapTypeControlOptions).

The following code sets the map to show only
two map types in the map's mapTypeControlOptions
and modifies the registry to add the association with
this identifier to the actual implementation of the
MapType interface.

Note:
In the previous code example, the creation of the custom map type
itself is intentionally omitted. See
Styled Maps or
Custom Map Types below for information
on constructing a map type.

Styled Maps

The StyledMapType allows you to customize the presentation of
the standard Google base maps, changing the visual display of such elements
as roads, parks, and built-up areas to reflect a different style than that
used in the default map type.

For more information about the StyledMapType, see the guide to
styled maps.

Custom Map Types

The Maps JavaScript API supports the display
and management of custom map types, allowing you to implement
your own map imagery or tile overlays.

Standard tile sets consisting of images which
collectively constitute full cartographic maps. These tile
sets are also known as base map types. These map types
act and behave like the existing default map types:
roadmap, satellite,
hybrid and terrain. You can add your
custom map type to a Map's mapTypes array to
allow the UI within the Maps JavaScript API to
treat your custom map type as a standard map type (by including it in the MapType
control, for example).

Image tile overlays which display on top of
existing base map types. Generally, these map types are
used to augment an existing map type to display additional
information and are often constrained to specific locations
and/or zoom levels. Note that these tiles may be transparent,
allowing you to add features to existing maps.

Non-image map types, which allow you to manipulate
the display of map information at its most fundamental level.

Each of these options relies on creating a class that
implements the MapType
interface. Additionally, the ImageMapType class provides some built-in
behavior to simplify the creation of imagery map types.

The MapType Interface

Before you create classes which implement MapType,
it is important to understand how Google Maps determines
coordinates and decides which parts of the map to show. You need to
implement similar logic for any base or overlay map types.
Read the guide to map
and tile coordinates.

Custom map types must implement the MapType
interface. This interface specifies certain properties and
methods that allow the API to initiate requests to your map
type(s) when the API determines that it needs to display map
tiles within the current viewport and zoom level. You handle
these requests to decide which tile to load.

Note: You may create your
own class to implement this interface. Alternatively, if you have
compatible imagery you can use the ImageMapType class which already implements
this interface.

Classes implementing the MapType interface
require that you define and populate the following properties:

tileSize (required) specifies the size of the tile
(of type google.maps.Size). Sizes must be rectangular
though they need not be square.

maxZoom (required) specifies the maximum zoom
level at which to display tiles of this map type.

minZoom (optional) specifies the minimum zoom
level at which to display tile of this map type. By default,
this value is 0 indicating that no minimum
zoom level exists.

name (optional) specifies the name for this map
type. This property is only necessary if you want this map type
to be selectable within a MapType control. (See
Adding MapType Controls below.)

alt (optional) specifies the alternate text for this
map type, exhibited as hover text. This property is only necessary
if you want this map type to be selectable within a MapType control.
(See Adding MapType Controls
below.)

Additionally, classes implementing the MapType interface
need to implement the following methods:

getTile() (required) is called whenever the API
determines that the map needs to display new tiles for the given
viewport. The getTile() method must have the following
signature:

getTile(tileCoord:Point,zoom:number,ownerDocument:Document):Node

The API determines whether it needs to call getTile()
based on the MapType's tileSize,
minZoom, and maxZoom
properties and the map's current viewport and zoom level. The handler
for this method should return an HTML element given a passed coordinate,
zoom level, and DOM element on which to append the tile image.

releaseTile() (optional) is called whenever the API
determines that the map needs to remove a tile as it falls out of view.
This method must have the following signature:

releaseTile(tile:Node)

You typically should handle removal of any elements
that were attached to the map tiles upon addition to the map.
For example, if you attached event listeners to map tile
overlays, you should remove them here.

The getTile() method acts as the main controller for
determining which tiles to load within a given viewport.

Base Map Types

Map types which you construct in this manner may either stand
alone or be combined with other map types as overlays. Standalone
map types are known as base map types. You may wish to have the API
treat such custom MapTypes as it would any other existing
base map type (ROADMAP, TERRAIN, etc.). To do
so, add your custom MapType to the Map's
mapTypes property. This property is of type
MapTypeRegistry.

The following code creates a base MapType to display
a map's tile coordinates and draws an outline of the tiles:

Overlay Map Types

Some map types are designed to work on top of existing map
types. Such map types may have transparent layers indicating
points of interest, or showing additional data to the user.

In these cases, you do not want the map type treated as a separate entity but as an overlay.
You can do this by adding the map type to an existing MapType directly using
the Map's overlayMapTypes property. This property contains
an MVCArray of MapTypes. All map types
(base and overlay) are rendered within the
mapPane
layer. Overlay map types will display on top of the base map they
are attached to, in the order in which they appear in the
Map.overlayMapTypes array (overlays with higher index
values are displayed in front of overlays with lower index values).

The following example is identical to the previous one
except that we've created a tile overlay MapType
on top of the ROADMAP map type:

Image Map Types

Implementing a MapType to act as a base map
type can be a time-consuming and laborious task. The API
provides a special class that implements the MapType
interface for the most common map types: map types that consist
of tiles made up of single image files.

This class, the ImageMapType class,
is constructed using an ImageMapTypeOptions
object specification defining the following required
properties:

tileSize (required) specifies the size of the tile
(of type google.maps.Size). Sizes must be rectangular
though they need not be square.

getTileUrl (required) specifies the function,
usually provided as an inline function literal, to handle
selection of the proper image tile based on supplied
world coordinates and zoom level.

The following code implements a basic ImageMapType
using Google's moon tiles. The example makes use of a normalization
function to ensure that tiles repeat along the x-axis, but not along the
y-axis of your map.

Projections

The Earth is a three-dimensional sphere (approximately), while a
map is a flat two-dimensional surface. The map that you see within
the Maps JavaScript API, like any flat map of the Earth, is a
projection of that sphere onto a flat surface. In its simplest
terms, a projection can be defined as a mapping of
latitude/longitude values into coordinates on the projection's map.

Projections in the Maps JavaScript API must implement the
Projection interface. A Projection
implementation must provide not only a mapping from one coordinate
system to another, but a bi-directional mapping. That is, you must
define how to translate from Earth coordinates (LatLng objects)
to the Projection class's
world
coordinate system, and vice versa. Google Maps uses
the Mercator projection to create its maps
from geographic data and convert events on the map into
geographic coordinates. You can obtain this projection by
calling getProjection() on the Map
(or any of the standard base MapType types.) For most uses,
this standard Projection will suffice, but you may also
define and use your own custom projections.

Implementing a Projection

When implementing a custom projection, you will need to define
a few things:

The formulae for mapping latitude and longitude coordinates into
a Cartesian plane and vice versa. (The Projection interface
only supports transformations into rectilinear coordinates.)

The base tile size. All tiles must be rectangular.

The "world size" of a map using the base tile set at zoom level 0.
Note that for maps consisting of one tile at zoom 0, the world size
and base tile size are identical.

Coordinate Transformations in
Projections

Each projection provides two methods which translate between these two
coordinate systems, allowing you to convert between geographic and
world coordinates:

The Projection.fromLatLngToPoint() method converts a
LatLng value into a world coordinate. This method is used
to position overlays on the map (and to position the map itself).

The Projection.fromPointToLatLng() method converts
a world coordinate into a LatLng value. This
method is used to convert events such as clicks that happen on the
map into geographic coordinates.

Google Maps assumes that projections are rectilinear.

Generally, you may use a projection for two cases: to create a
map of the world, or to create a map of a local area. In the former case,
you should ensure that your projection is also rectilinear and normal
at all longitudes. Some projections (especially conic projections)
may be "locally normal" (i.e. point north) but deviate from true north;
for example, the further the map is positioned relative to some
reference longitude. You may use such a projection locally, but be
aware that the projection is necessarily imprecise and transformation
errors will become increasingly apparently the further away from
the reference longitude you deviate.

Map Tile Selection in Projections

Projections are not only useful for determining the positions of
locations or overlays, but for positioning the map tiles themselves.
The Maps JavaScript API renders base maps using a MapType
interface, which must declare both a projection property for
identifying the map's projection and a getTile()
method for retrieving map tiles based on
tile
coordinate values. Tile coordinates are based on
both your basic tile size (which must be rectangular) and the "world
size" of your map, which is the pixel size of your map world
at zoom level 0. (For maps consisting of one tile at zoom 0, the tile
size and world size are identical.)

You define the base tile size within your MapType's
tileSize property. You define the world size implicitly
within your projection's fromLatLngToPoint()
and fromPointToLatLng() methods.

Since image selection depends on these passed values, it is useful
to name images that can be selected programmatically given those
passed values, such as
map_zoom_tileX_tileY.png.

The following example defines an ImageMapType
using the
Gall-Peters projection: