Annotations

Add annotations to the map using point, line, polygon and circle shapes with the MapView’s AnnotationOrchestrator. Use the AnnotationOrchestrator to create annotation managers based on the type of annotation that you're interested in. Every annotation manager handles a collection of annotations. Once a manager has been created, you can create and add individually styled instances of the corresponding annotation type.

Benefits:

  • Built-in interaction support like tapping on annotations.
  • No external data file necessary.
  • Every annotation can be individually styled.
  • Every annotation layer can be adjusted to be above or below another layer.
  • Same performance benefits as using style layers.

Limitations:

  • No default image available.
  • Inefficient for adding many features to the map.

Markers

A PointAnnotation can display a custom marker image at a developer-specified geographic coordinate. Click the button below to download a zip file containing a custom pin image. Unzip the files and put them in your Xcode project's asset catalog and specify it by name as the point annotation's image.

Download ZIP
// Initialize a point annotation with a geometry ("coordinate" in this case)
var pointAnnotation = PointAnnotation(coordinate: someCoordinate)

// Make the annotation show a red pin
pointAnnotation.image = .init(image: UIImage(named: "red_pin")!, name: "red_pin")
pointAnnotation.iconAnchor = .bottom

// Create the `PointAnnotationManager` which will be responsible for handling this annotation
let pointAnnotationManager = mapView.annotations.makePointAnnotationManager()

// Add the annotation to the manager in order to render it on the map.
pointAnnotationManager.annotations = [pointAnnotation]
example
Add a marker to the map

Use MapView's AnnotationOrchestrator class to add a single red marker pin to the map using the Maps SDK for iOS.

Other shapes

MapView’s AnnotationOrchestrator also supports putting other shapes on the map including circles using CircleAnnotationManager, polylines using PolylineAnnotationManager, and polygons using PolygonAnnotationManager. These annotations work like the point annotations described above, but do not require an image. The options available for each type of annotation varies and you can find a full list in the API reference documentation.

Circle annotation

A circle annotation (CircleAnnotation) places a circle at a point on the map.

// Define a geographic coordinate.
var circleCoordinates = CLLocationCoordinate2DMake(40.7128, -74.0060)

// Create the circle annotation.
var circleAnnotation = CircleAnnotation(coordinate: lineCoordinates)
circleAnnotation.circleColor = StyleColor(.red)

// Create the `CircleAnnotationManager` which will be responsible for handling this annotation
let circleAnnnotationManager = mapView.annotations.makeCircleAnnotationManager()

// Add the annotation to the manager.
circleAnnnotationManager.annotations = [circleAnnotation]

Polyline annotation

A polyline annotation (PolylineAnnotation) connects a list of coordinates on the map with a polyline. The order of the coordinates in the list will determine the order in which to connect the points, in the same way that coordinates are handled in the GeoJSON specification.

// Define two or more geographic coordinates to connect with a line.
// Line from New York City, NY to Washington, D.C.
let lineCoordinates = [
    CLLocationCoordinate2DMake(40.7128, -74.0060),
    CLLocationCoordinate2DMake(38.9072, -77.0369)
]

// Create the line annotation.
var lineAnnotation = PolylineAnnotation(lineCoordinates: lineCoordinates)
lineAnnotation.lineColor = StyleColor(.red)

// Create the `PolylineAnnotationManager` which will be responsible for handling this annotation
let lineAnnnotationManager = mapView.annotations.makePolylineAnnotationManager()

// Add the annotation to the manager.
lineAnnnotationManager.annotations = [lineAnnotation]

Polygon annotation

A polygon annotation (PolygonAnnotation) takes a list of coordinates and will try to connect those coordinates and add the resulting polygonal shape to the map. The order of the coordinates in the list matters and works the same way as in the GeoJSON specification.

// Define three or more geographic coordinates to connect.
let ringCoords = [
    CLLocationCoordinate2DMake(24.5171, -89.8571),
    CLLocationCoordinate2DMake(24.5171, -87.9675),
    CLLocationCoordinate2DMake(26.2441, -87.9675),
    CLLocationCoordinate2DMake(26.2441, -89.8571),
    CLLocationCoordinate2DMake(24.5171, -89.8571)
]
let ring = Ring(coordinates: ringCoords)
let polygon = Polygon(outerRing: ring)

// Create a new polygon annotation using those coordinates.
let polygonAnnotation = PolygonAnnotation(polygon: polygon)

// Create the `PolygonAnnotationManager` which will be responsible for handling this annotation
let polygonAnnotationManager = mapView.annotations.makePolygonAnnotationManager()

// Add the polygon to the map as an annotation.
polygonAnnotationManager.annotations = [polygonAnnotation]

Interactivity

You can choose to receive tap events on annotations that you've added to a manager, by conforming to AnnotationInteractionDelegate (and setting yourself as the delegate on the manager).

class ViewController: UIViewController {
    var mapView: MapView!

    override func viewDidLoad() {
        super.viewDidLoad()

        mapView = MapView(frame: view.bounds)
        mapView.autoresizingMask = [.flexibleWidth, .flexibleHeight]
        view.addSubview(mapView)

        let pointAnnotationManager = mapView.annotations.makePointAnnotationManager()

        // Make self the `AnnotationInteractionDelegate` to get called back on tap events
        pointAnnotationManager.delegate = self

        // Add an annotation
        let coordinate = CLLocationCoordinate2DMake(24, -89)
        var pointAnnotation = PointAnnotation(coordinate: coordinate)
        pointAnnotation.image = .init(image: UIImage(named: "red_pin")!, name: "red_pin")
        pointAnnotationManager.annotations = [pointAnnotation]
    }
}

extension ViewController: AnnotationInteractionDelegate {
    public func annotationManager(_ manager: AnnotationManager, didDetectTappedAnnotations annotations: [Annotation]) {
        print("Annotations tapped: \(annotations)")
    }
}

Removing Annotations

To remove a single annotation from an annotation manager, remove it from the annotations array.

To completely remove an annotation manager, call mapView.annotations.removeAnnotationManager(withId:), passing the ID of the annotation manager that you want to remove. This removes the backing source and layer. The removed annotation manager will not be useful after it is removed.

Annotation managers are removed implicitly if another annotation manager is created with the same ID.