Ground Overlays

Ground overlays are overlays on the map that are tied to latitude/longitude coordinates, so they move when you drag or zoom the map.

Introduction

A ground overlay is an image that is fixed to a map. Unlike markers, ground overlays are oriented against the Earth's surface rather than the screen, so rotating, tilting or zooming the map will change the orientation of the image.

To add a ground overlay, create a GMSGroundOverlay object that defines both an icon and a bounds. Failing to specify either will cause the ground overlay to not appear on the map. You can optionally specify additional settings that will affect the positioning of the image on the map. Once you've defined the necessary options, set this object's map property to add the overlay.

Add an overlay

1. Instantiate a new GMSGroundOverlay object
2. Set the icon property to an instance of UIImage.
3. Set the bounds property to an instance of GMSCoordinateBounds. The bounds represent the south west, and north east corners of the image.
4. Set optional properties, such as bearing and zoomLevel, as desired.
5. Set the map property - the image appears on the map.

The below example demonstrates how to add a ground overlay to an existing GMSMapView object.

let southWest = CLLocationCoordinate2D(latitude: 40.712216, longitude: -74.22655)
let northEast = CLLocationCoordinate2D(latitude: 40.773941, longitude: -74.12544)
let overlayBounds = GMSCoordinateBounds(coordinate: southWest, coordinate: northEast)

// Image from http://www.lib.utexas.edu/maps/historical/newark_nj_1922.jpg
let icon = UIImage(named: "newark_nj_1922")

let overlay = GMSGroundOverlay(bounds: overlayBounds, icon: icon)
overlay.bearing = 0
overlay.map = mapView

CLLocationCoordinate2D southWest = CLLocationCoordinate2DMake(40.712216,-74.22655);
CLLocationCoordinate2D northEast = CLLocationCoordinate2DMake(40.773941,-74.12544);
GMSCoordinateBounds *overlayBounds = [[GMSCoordinateBounds alloc] initWithCoordinate:southWest
                                                                        coordinate:northEast];

// Image from http://www.lib.utexas.edu/maps/historical/newark_nj_1922.jpg
UIImage *icon = [UIImage imageNamed:@"newark_nj_1922"];
GMSGroundOverlay *overlay =
    [GMSGroundOverlay groundOverlayWithBounds:overlayBounds icon:icon];
overlay.bearing = 0;
overlay.map = mapView;

Remove an overlay

You can remove a ground overlay from the map by setting your GMSGroundOverlay's map property to nil. Alternately, you can remove all of the overlays (including ground overlays currently on the map by calling the GMSMapView clear method.

let camera = GMSCameraPosition.camera(withLatitude: 40.71,
                                      longitude: -74.22,
                                      zoom:11)
let mapView = GMSMapView.map(withFrame: .zero, camera: camera)
...
mapView.clear()

GMSCameraPosition *camera = [GMSCameraPosition cameraWithLatitude:40.742
                                                        longitude:-74.174
                                                             zoom:6];
mapView = [GMSMapView mapWithFrame:CGRectZero camera:camera];
...
[mapView clear];

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

let overlay = GMSGroundOverlay(position: newark, icon: icon, zoomLevel: 10)
overlay.map = mapView
...
overlay.isTappable = true

GMSGroundOverlay *overlay =
    [GMSGroundOverlay groundOverlayWithPosition:newark
                                           icon:icon
                                      zoomLevel:10];
overlay.map = mapView;
...
overlay.tappable = YES;

Events

You can listen to events that occur on the map, such as when a user taps an overlay. To listen to events, you must implement the GMSMapViewDelegate protocol. See the guide to events and the list of methods on the GMSMapViewDelegate.