Google Maps SDK for iOS

Shapes

The Google Maps SDK for iOS offers some simple ways for you to add shapes to your maps. The following shapes are supported:

  • 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.

You are able to modify the appearance of each shape in a number of ways.

Polylines

Polylines allow you to draw lines on the map. A GMSPolyline object represents an ordered sequence of locations, displayed as a series of line segments. You can set the color of a polyline with GMSStrokeStyle.

To create a polyline, you'll need to specify its path by creating a corresponding GMSMutablePath object with two or more points. Each CLLocationCoordinate2D represents a point on the Earth's surface. Line segments are drawn between points according to the order in which you add them to the path. You can add points to the path with the addCoordinate: or addLatitude:longitude: methods.

GMSMutablePath *path = [GMSMutablePath path];
[path addCoordinate:CLLocationCoordinate2DMake(-33.85, 151.20)];
[path addCoordinate:CLLocationCoordinate2DMake(-33.70, 151.40)];
[path addCoordinate:CLLocationCoordinate2DMake(-33.73, 151.41)];
GMSPolyline *polyline = [GMSPolyline polylineWithPath:path];

Add a polyline

  1. Create a GMSMutablePath object.
  2. Set the points in the path with the addCoordinate: or addLatitude:longitude: methods.
  3. Instantiate a new GMSPolyline object using the path as an argument.
  4. Set other properties, such as strokeWidth and strokeColor, as desired.
  5. Set the map property of the GMSPolyline.
  6. The polyline appears on the map.

The following code snippet adds a rectangle to a map:

GMSMutablePath *path = [GMSMutablePath path];
[path addCoordinate:CLLocationCoordinate2DMake(37.36, -122.0)];
[path addCoordinate:CLLocationCoordinate2DMake(37.45, -122.0)];
[path addCoordinate:CLLocationCoordinate2DMake(37.45, -122.2)];
[path addCoordinate:CLLocationCoordinate2DMake(37.36, -122.2)];
[path addCoordinate:CLLocationCoordinate2DMake(37.36, -122.0)];

GMSPolyline *rectangle = [GMSPolyline polylineWithPath:path];
rectangle.map = mapView_;

A rectangular polyline

Remove a polyline

You can remove a polyline from the map by setting your GMSPolyline's map property to nil. Alternately, you can remove all of the overlays (including polylines and other shapes) currently on the map by calling the GMSMapView clear method.

GMSCameraPosition *camera = [GMSCameraPosition cameraWithLatitude:-33.8683
                                                        longitude:151.2086
                                                             zoom:12];
mapView_ = [GMSMapView mapWithFrame:self.view.bounds camera:camera];
...
[mapView_ clear];

If you wish to make modifications to a polyline after you've added it to the map, ensure that you keep hold of the GMSPolyline object. You can modify the polyline later by making changes to this object.

GMSPolyline *polyline = [GMSPolyline polylineWithPath:path];
polyline.map = mapView_;
...
polyline.strokeColor = [UIColor blackColor];

Customize a polyline

The GMSPolyline object provides several properties to control the appearance of the line. It supports the following options:

strokeWidth
The width of the entire line, in screen points. Defaults to 1. The width does not scale when the map is zoomed.
geodesic
When YES, render this polyline edge as a geodesic. Geodesic segments follow the shortest path along the Earth's surface and may appear as curved lines on a map with a Mercator projection. Non-geodesic segments are drawn as straight lines on the map. Defaults to NO. e
spans
Used to specify the color of one or more segments of a polyline. The spans property is an NSArray of GMSStyleSpan objects. Setting the spans property is the preferred way to change the color of a polyline.
strokeColor
A UIColor object specifying the color of the polyline. Defaults to blueColor. The strokeColor property is ignored if spans is set.

The following snippet adds a thick polyline from Melbourne to Perth, with geodesic interpolation.

GMSMutablePath *path = [GMSMutablePath path];
[path addLatitude:-37.81319 longitude:144.96298];
[path addLatitude:-31.95285 longitude:115.85734];
GMSPolyline *polyline = [GMSPolyline polylineWithPath:path];
polyline.strokeWidth = 10.f;
polyline.geodesic = YES;
polyline.map = mapView_;

To modify a polyline after it has been added to the map, be sure to keep hold of the GMSPolyline object.

GMSPolyline *polyline = [GMSPolyline polylineWithPath:path];
polyline.map = mapView_;
...
polyline.strokeColor = [UIColor blueColor];

Change the color of a polyline

Polylines are drawn as a series of segments on the map. You can change the color of individual segments, or the entire line, with the spans property. While this property gives you detailed control over the coloring of a polyline, several conveniences exist that make it easy to apply a single style to the entire line.

The below snippet uses the spanWithColor: method to change the color of the entire line to red.

polyline.spans = @[[GMSStyleSpan spanWithColor:[UIColor redColor]]];

Alternately, if you already have access to a GMSStrokeStyle object, you can use the spanWithStyle: method.

GMSStrokeStyle *solidRed = [GMSStrokeStyle solidColor:[UIColor redColor]];
polyline.spans = @[[GMSStyleSpan spanWithStyle:solidRed]];

Prior to version 1.7 of the Google Maps SDK for iOS, the single property strokeColor was available to set the entire color of a GMSPolyline. The spans property takes precedence over strokeColor.

polyline.strokeColor = [UIColor redColor];

Styles

If your app applies the same stroke color several times, you may find it useful to define a reusable style. Polyline styles are specified using the GMSStrokeStyle object. A stroke style can be either a solid color or a gradient from one color to another color. Once you've created a style, you can apply it to a GMSStyleSpan with the spanWithStyle: method.

// Create two styles: one that is solid blue, and one that is a gradient from red to yellow
GMSStrokeStyle *solidBlue = [GMSStrokeStyle solidColor:[UIColor blueColor]];
GMSStyleSpan *solidBlueSpan = [GMSStyleSpan spanWithStyle:solidBlue];
GMSStrokeStyle *redYellow =
    [GMSStrokeStyle gradientFromColor:[UIColor redColor] toColor:[UIColor yellowColor]];
GMSStyleSpan *redYellowSpan = [GMSStyleSpan spanWithStyle:redYellow];

A span's style will continue until the end of the polyline, or until a new style is set. You can change the color of the entire line by setting the spans property of a polyline to a single GMSStyleSpan The below snippet demonstrates how to apply a gradient across the entire length of the polyline.

GMSPolyline *polyline = [GMSPolyline polylineWithPath:path];
GMSStrokeStyle *redYellow =
    [GMSStrokeStyle gradientFromColor:[UIColor redColor] toColor:[UIColor yellowColor]];
polyline.spans = @[[GMSStyleSpan spanWithStyle:redYellow]];

Change the color of individual line segments

If you'd like to style each segment of your polyline individually, you can do so by creating an NSArray of GMSStyleSpan objects, and passing this to the spans property. By default, each item in the array will set the color of the corresponding line segment. If there are more elements in the array than segments in the line, the extra elements will be ignored. If there are fewer elements in the array, the final GMSStyleSpan will describe the color for the remainder of the line.

You can use blocks of color and/or gradient polylines to indicate changes along your polyline such as elevation or speed. The below snippet sets the color of the first two segments of a polyline to red, and the remainder of the line is a gradient from red to yellow.

GMSPolyline *polyline = [GMSPolyline polylineWithPath:path];
GMSStrokeStyle *solidRed = [GMSStrokeStyle solidColor:[UIColor redColor]];
GMSStrokeStyle *redYellow =
    [GMSStrokeStyle gradientFromColor:[UIColor redColor] toColor:[UIColor yellowColor]];
polyline.spans = @[[GMSStyleSpan spanWithStyle:solidRed],
                   [GMSStyleSpan spanWithStyle:solidRed],
                   [GMSStyleSpan spanWithStyle:redYellow]];

You can use the spanWithStyle:segments: method to set the style for several segments at once. For example, the following code is equivalent to the above. The segment length of the final GMSStyleSpan will always be ignored as the style will be used to describe the remainder of the line.

polyline.spans = @[[GMSStyleSpan spanWithStyle:solidRed segments:2],
                   [GMSStyleSpan spanWithStyle:redYellow segments:10]];

Fractional segments

Segments may also be specified as a fractional value. This will apply the style to the fractional number of segments, potentially causing a split in a single segment. Each GMSStyleSpan begins immediately after the previous one: in the example below, the gray color will begin from ½ through the second segment and continue to ½ through the third segment.

polyline.spans = @[[GMSStyleSpan spanWithStyle:solidRed segments:2.5],
                   [GMSStyleSpan spanWithColor:[UIColor grayColor],
                   [GMSStyleSpan spanWithColor:[UIColor purpleColor] segments:0.75,
                   [GMSStyleSpan spanWithStyle:redYellow]];

Add a repeating color pattern to a polyline

If you'd like to add a pattern to a polyline, you can use the GMSStyleSpans utility method in GMSGeometryUtils. The GMSStyleSpans method accepts two arrays that define a repeating pattern. One array sets the styles that should be repeated, and the other defines the interval of repetition. Used together you can create a pattern that can be applied across any polyline, no matter its length or the number of segments available.

For example, the below code snippet defines a polyline with a black and white alternating pattern. Its lengths are treated as meters along a rhumb line (in Mercator, this is a straight line) as the type is specified as kGMSLengthRhumb.

NSArray *styles = @[[GMSStrokeStyle solidColor:[UIColor whiteColor]],
                    [GMSStrokeStyle solidColor:[UIColor blackColor]]];
NSArray *lengths = @[@100000, @50000];
polyline.spans = GMSStyleSpans(polyline.path, styles, lengths, kGMSLengthRhumb);

Polygons

Polygons are similar to polylines in that they consist of a series of coordinates in an ordered sequence. However, instead of being open-ended, polygons are designed to define solid regions within a closed loop. Polygons are defined in the Google Maps SDK for iOS by the GMSPolygon class.

You can add a GMSPolygon to the map in the same way as you add a GMSPolyline. First, specify its path by creating a corresponding GMSMutablePath object and adding points to it. These points will form the outline of the polygon. Each CLLocationCoordinate2D represents a point on the Earth's surface. Line segments are drawn between points according to the order in which you add them to the path.

Add a polygon

  1. Create a GMSMutablePath object.
  2. Set the points in the path with the addCoordinate: or addLatitude:longitude: methods. These points will form the outline of the polygon.
  3. Instantiate a new GMSPolygon object using the path as an argument.
  4. Set other properties, such as strokeWidth, strokeColor and fillColor, as desired.
  5. Assign the polygon to a GMSMapView object by setting the GMSPolygon.map property.
  6. The polyline appears on the map.

The following code snippet adds a rectangle to a map.

// Create a rectangular path
GMSMutablePath *rect = [GMSMutablePath path];
[rect addCoordinate:CLLocationCoordinate2DMake(37.36, -122.0)];
[rect addCoordinate:CLLocationCoordinate2DMake(37.45, -122.0)];
[rect addCoordinate:CLLocationCoordinate2DMake(37.45, -122.2)];
[rect addCoordinate:CLLocationCoordinate2DMake(37.36, -122.2)];

// Create the polygon, and assign it to the map.
GMSPolygon *polygon = [GMSPolygon polygonWithPath:rect];
polygon.fillColor = [UIColor colorWithRed:0.25 green:0 blue:0 alpha:0.05];
polygon.strokeColor = [UIColor blackColor];
polygon.strokeWidth = 2;
polygon.map = mapView_;

You can customize the appearance of the polygon both before adding it to the map and after it has been added to the map.

Circles

In addition to the generic GMSPolygon class, the Google Maps SDK for iOS also includes GMSCircle, allowing you to easily draw circles on the earth's surface.

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

  • position as a CLLocationCoordinate2D.
  • 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.

Add a circle

The following code snippet adds a circle to the map:

CLLocationCoordinate2D circleCenter = CLLocationCoordinate2DMake(37.35, -122.0);
GMSCircle *circ = [GMSCircle circleWithPosition:circleCenter
                                         radius:1000];
circ.map = mapView;

You can customize the appearance of the circle both before adding it to the map and after it has been added to the map.

Customize a circle

You can specify custom colors and stroke widths by modifying properties of GMSCircle. It supports the following options:

fillColor
A UIColor object specifying the interior color of the circle. Defaults to transparent.
strokeColor
A UIColor object specifying the color of the circle's outline. Defaults to blackColor.
strokeWidth
The thickness of the circle's outline, in screen points. Defaults to 1. The thickness does not scale when the map is zoomed.

The following snippet adds a thick red circle with a semi-transparent red interior.

CLLocationCoordinate2D circleCenter = CLLocationCoordinate2DMake(37.35, -122.0);
GMSCircle *circ = [GMSCircle circleWithPosition:circleCenter
                                         radius:1000];

circ.fillColor = [UIColor colorWithRed:0.25 green:0 blue:0 alpha:0.05];
circ.strokeColor = [UIColor redColor];
circ.strokeWidth = 5;
circ.map = mapView;

Authentication required

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

Signing you in...

Google Developers needs your permission to do that.