Google Maps Android API v2

Shapes

The Google Maps API for Android offers some simple ways for you to add shapes to your maps in order to customize them for your application.

  • A Polyline is a series of connected line segments that can form any shape you want and can be used to mark paths and routes on the map.
  • A Polygon is an enclosed shape that can be used to mark areas on the map.
  • A Circle is a geographically accurate projection of a circle on the Earth's surface drawn on the map.

For all these shapes, you can customize their appearance by altering a number of properties.

Polylines

The Polyline class defines a set of connected line segments on the map. A Polyline object consists of a set of LatLng locations, and creates a series of line segments that connect those locations in an ordered sequence.

To create a Polyline, first create a PolylineOptions object and add points to it. Points represent a point on the earth's surface, and are expressed as a LatLng object. Line segments are drawn between points according to the order in which you add them to the PolylineOptions object. To add points to a PolylineOptions object, call PolylineOptions.add(). Notice that this method takes a variable number of parameters so you are able to add multiple points at a time (you can also call PolylineOptions.addAll(Iterable<LatLng>) if the points are already in a list).

You can then add the polyline to a map by calling GoogleMap.addPolyline(PolylineOptions). The method returns a Polyline object with which you can alter the polyline at a later time.

The following code snippet illustrates how to add a rectangle to a map:

// Instantiates a new Polyline object and adds points to define a rectangle
PolylineOptions rectOptions = new PolylineOptions()
        .add(new LatLng(37.35, -122.0))
        .add(new LatLng(37.45, -122.0))  // North of the previous point, but at the same longitude
        .add(new LatLng(37.45, -122.2))  // Same latitude, and 30km to the west
        .add(new LatLng(37.35, -122.2))  // Same longitude, and 16km to the south
        .add(new LatLng(37.35, -122.0)); // Closes the polyline.

// Get back the mutable Polyline
Polyline polyline = myMap.addPolyline(rectOptions);

To alter the shape of the polyline after it has been added, you can call Polyline.setPoints() and provide a new list of points for the polyline.

You can customize the appearance of the polyline both before adding it to the map and after it has been added to the map. See the section on customizing appearances below for further details.

Polygons

Polygon objects are similar to Polyline objects in that they consist of a series of coordinates in an ordered sequence. However, instead of being open-ended, polygons are designed to define regions within a closed loop with the interior filled in.

You can add a Polygon to the map in the same way as you add a Polyline. First create a PolygonOptions object and add some points to it. These points will form the outline of the polygon. You then add the polygon to the map by calling GoogleMap.addPolygon(PolygonOptions) which will return a Polygon object.

The following code snippet adds a rectangle to a map (note that since we have not defined a fill color, and the default fill color is transparent, this will appear exactly the same as the polyline from the snippet in the previous section):

// Instantiates a new Polygon object and adds points to define a rectangle
PolygonOptions rectOptions = new PolygonOptions()
              .add(new LatLng(37.35, -122.0),
                   new LatLng(37.45, -122.0),
                   new LatLng(37.45, -122.2),
                   new LatLng(37.35, -122.2),
                   new LatLng(37.35, -122.0));

// Get back the mutable Polygon
Polygon polygon = myMap.addPolygon(rectOptions);

To alter the shape of the polygon after it has been added, you can call Polygon.setPoints() and provide a new list of points for the outline of the polygon.

You can customize the appearance of the polygon both before adding it to the map and after it has been added to the map. See the section on customizing appearances below for further details.

Polygon Auto-Completion

The Polygon in the example above consists of five coordinates, but notice that the first and last coordinates are the same location, which defines the loop. In practice, however, since polygons define closed areas, you don't need to define this last coordinate. The API will automatically "close" any polygons by drawing a stroke connecting the last coordinate back to the first coordinate for any given paths.

The below two polygons are equivalent.

Polygon polygon = map.addPolygon(new PolygonOptions()
        .add(new LatLng(0, 0), new LatLng(0, 5), new LatLng(3, 5), new LatLng(0, 0))
        .strokeColor(Color.RED)
        .fillColor(Color.BLUE));

Polygon polygon = map.addPolygon(new PolygonOptions()
         .add(new LatLng(0, 0), new LatLng(0, 5), new LatLng(3, 5))
         .strokeColor(Color.RED)
         .fillColor(Color.BLUE));

Create a hollow Polygon

Multiple paths can be combined in a single Polygon object to create complex shapes, such as filled rings, or "donuts" (where polygonal areas appear inside the polygon as "islands"). Complex shapes are always the composition of multiple, simpler, paths.

Two paths must be defined in the same area. The larger of the two regions defines the fill area, and is a simple polygon with no additional options. Then, pass a second path to the addHole() method. When the second, smaller path is full enclosed by the larger path, it will appear as if a piece of the polygon has been removed. If the hole intersects the outline of the polygon, the polygon will be rendered without any fill.

The below snippet will create a single rectangle, with a smaller rectangular hole.

mMap.addPolygon(new PolygonOptions()
        .add(new LatLng(0, 0), new LatLng(0, 5), new LatLng(3, 5), new LatLng(3, 0), new LatLng(0, 0))
        .addHole(new LatLng(1, 1), new LatLng(1, 2), new LatLng(2, 2), new LatLng(2, 1), new LatLng(1, 1))
        .fillColor(Color.BLUE));

Circles

In addition to a generic Polygon class, the Maps API also includes specific classes for Circles to simplify their construction.

To construct a circle, you must specify the following two properties:

  • center as a LatLng.
  • radius in meters.

A circle is then defined to be the set of all points on the Earth's surface which are radius meters away from the given center. Because of how the Mercator projection used by the Maps API renders a sphere on a flat surface, this will appear as an almost perfect circle on the map when located near the equator, and will appear increasingly non-circular (on the screen) as the circle moves away from the equator.

The following code snippet adds a circle to the map by constructing a CircleOptions object and calling GoogleMap.addCircle(CircleOptions):

// Instantiates a new CircleOptions object and defines the center and radius
CircleOptions circleOptions = new CircleOptions()
    .center(new LatLng(37.4, -122.1))
    .radius(1000)); // In meters

// Get back the mutable Circle
Circle circle = myMap.addCircle(circleOptions);

To alter the shape of the circle after it has been added, you can call Circle.setRadius() or Circle.setCenter() and provide new values.

You can customize the appearance of the circle both before adding it to the map and after it has been added to the map. See the section on customizing appearances below for further details.

Customizing Appearances

You can alter the appearance of a shape both before it has been added to the map (by specifying the desired property on the options object) or after it has been added to the map. Getters are also exposed for all properties so that you can easily access the current state of the shape.

The following snippet adds a thick blue polyline with geodesic segments from Melbourne to Perth. The sections below will explain these properties in more detail.

Polyline line = map.addPolyline(new PolylineOptions()
    .add(new LatLng(-37.81319, 144.96298), new LatLng(-31.95285, 115.85734))
    .width(25)
    .color(Color.BLUE)
    .geodesic(true));

Note: While most of these can be applied to any of the shapes described, some of the properties may not make sense for certain shapes (e.g., a Polyline can't have a fill color because it doesn't have an interior).

Stroke Color

The stroke color is a 32-bit alpha-red-green-blue (ARGB) integer specifying the opacity and color of the stroke of the shape. Set this property on the shape's options object by calling *Options.strokeColor() (or PolylineOptions.color() in the case of a polyline). If unspecified, the default stroke color is black (Color.BLACK).

After the shape has been added to the map, the stroke color may be accessed by calling getStrokeColor() (or getColor() for a polyline) and may be changed by calling setStrokeColor() (setColor() for a polyline).

Fill Color

Fill color only applies to polygons and circles. It does not apply to polylines as they do not have defined interiors. For a polygon, the regions inside its holes are not part of the interior of the polygon and will not be colored in if a fill color is set.

The fill color is a 32-bit alpha-red-green-blue (ARGB) integer specifying the opacity and color of the interior of the shape. Set this property on the shape's options object by calling *Options.fillColor(). If unspecified, the default stroke color is transparent (Color.TRANSPARENT).

After the shape has been added to the map, the fill color may be accessed by calling getFillColor() and may be changed by calling setFillColor().

Stroke Width

The width of the line stroke, as a float in pixels (px). The width does not scale when the map is zoomed (i.e., a shape will have the same stroke width at all zoom levels). Set this property on the shape's option object by calling *Options.strokeWidth() (or PolylineOptions.width() for a polyline). If unspecified, the default stroke with is 10 pixels.

After the shape has been added to the map, the stroke width may be accessed by calling getStrokeWidth() (or getWidth() for a polyline) and may be changed by calling setStrokeWidth() (setWidth() for a polyline).

Geodesic segments

The geodesic setting only applies to polylines and polygons. It does not apply to circles because they are not defined as a collection of segments.

The geodesic setting determines how the line segments between consecutive vertices of the polyline/polygon are drawn. Geodesic segments are those that follow the shortest path along the Earth's surface (a sphere) and often appear as curved lines on a map with a Mercator projection. Non-geodesic segments are drawn as straight lines on the map.

Set this property on the shape's option object by calling *Options.geodesic() where true indicates the segments should be drawn as geodesics and false indicates the segments should be drawn as straight lines. If unspecified, the default is non-geodesic segments (false).

After the shape has been added to the map, the geodesic setting may be accessed by calling isGeodesic() and may be changed by calling setGeodesic().

Z-Index

The z-index specifies the stack order of this shape, relative to other overlays (other shapes, ground overlays and tile overlays) on the map. An overlay with a high z-index is drawn above overlays with lower z-indexes. Two overlays with the same z-index are drawn in an arbitrary order.

Set this property on the shape's options object by calling *Options.zIndex(). If unspecified, the default z-index is 0. After the shape has been added to the map, the z-index may be accessed by calling getZIndex() and may be changed by calling setZIndex().

Visibility

The visibility specifies whether the shape should be drawn on the map, where true indicates it should be drawn and false indicates it should not. It allows you to temporarily not display a shape on the map. To permanently remove shape from the map, call remove() on that shape.

Set this property on the shape's options object by calling *Options.visible(). If unspecified, the default visibility is true. After the shape has been added to the map, the visibility may be accessed by calling isVisible() and may be changed by calling setVisible().

Authentication required

You need to be signed in with Google+ to do that.

Signing you in...

Google Developers needs your permission to do that.