First steps with the Mapbox Maps SDK for iOS

The Mapbox Maps SDK for iOS is our vector maps library for iOS. This guide will show you how to work with the Maps SDK for iOS, including how to customize your map, add markers with callouts, and display your user’s location on a map.

Before you begin, install the Mapbox Maps SDK for iOS by following our installation guide. You can integrate the Mapbox Maps SDK for iOS using a dependency manager such as Carthage or CocoaPods, or you can install the SDK manually.

After you complete the installation flow, your view controller should look like the one below if you chose the “Add with code” option. If you selected the “Add with Storyboard” option during the installation process, you will need to connect your MGLMapView to an IBOutlet so it is accessible within your view controller to continue with this guide.

show hidden lines
let mapView = MGLMapView(frame: view.bounds)
mapView.autoresizingMask = [.flexibleWidth, .flexibleHeight]
mapView.setCenter(CLLocationCoordinate2D(latitude: 40.74699, longitude: -73.98742), zoomLevel: 9, animated: false)
view.addSubview(mapView)
show hidden lines

To change your map style, set the MGLMapView.styleURL property to a style URL. This style URL can be any one of our beautiful template or designer styles, or you can create your own completely custom style in Mapbox Studio.

The MGLStyle class also provides a set of convenience methods that return the style URLs of default Mapbox styles.

For this guide, you will be using the Mapbox Satellite Streets style. Set the MGLMapView.styleURL property to the URL for this style using the provided convenience method, satelliteStreetsStyleURL.

show hidden lines
mapView.styleURL = MGLStyle.satelliteStyleURL
show hidden lines

Then run your application to see the map's new style.

There are many ways to add a marker, also called an annotation, to your map. MGLPointAnnotation provides the simplest way to add a predefined point style to your map.

Your viewDidLoad method should look like the code below to place a point annotation on Central Park within New York City.

show hidden lines
// Add a point annotation
let annotation = MGLPointAnnotation()
annotation.coordinate = CLLocationCoordinate2D(latitude: 40.77014, longitude: -73.97480)
annotation.title = "Central Park"
annotation.subtitle = "The biggest park in New York City!"
mapView.addAnnotation(annotation)
show hidden lines

Run your application and notice the new point annotation added.

MGLPointAnnotation is the base class of all point annotations and can be additionally configured to use views or static images in place of the default annotation style. Read the documentation for MGLAnnotationView and MGLAnnotationImage for more information about working with these types of annotations.

If you want to add a large number of points to a map, consider using runtime styling, which is another feature of the Mapbox Maps SDK for iOS geared towards creating rich data visualizations. For more information about the different ways to add points to a map and the differences between each approach, read our Markers and annotations guide.

To get the annotation to display a callout when a user taps on it, the view controller will need to conform to the MGLMapViewDelegate protocol to use the delegate methods MGLMapViewDelegate provides.

Once the view controller conforms to the MGLMapViewDelegate protocol and the map view's delegate is set to the view controller itself, you can then implement the -mapView:annotationCanShowCallout: delegate method. This makes sure that the map view knows that an annotation should display a callout when tapped. The full implementation of this is shown below:

show hidden lines
mapView.delegate = self
show hidden lines
func mapView(_ mapView: MGLMapView, annotationCanShowCallout annotation: MGLAnnotation) -> Bool {
// Always allow callouts to popup when annotations are tapped.
return true
}
show hidden lines

Run the application, and then try to tap the annotation — it now displays a callout with your annotation's title and subtitle when tapped!

To center the map on the tapped marker, start by implementing the -mapView:didSelectAnnotation: delegate method. When the delegate method is called, initialize a new MGLMapCamera, which is the map's field of view. After creating the MGLMapCamera, call the -setCamera:animated: method on the MGLMapView to set the map's viewport to the new camera, which will be centered on the annotation's coordinate at a specified distance above ground level.

show hidden lines
func mapView(_ mapView: MGLMapView, didSelect annotation: MGLAnnotation) {
let camera = MGLMapCamera(lookingAtCenter: annotation.coordinate, fromDistance: 4500, pitch: 15, heading: 180)
mapView.fly(to: camera, withDuration: 4,
peakAltitude: 3000, completionHandler: nil)
}
show hidden lines

If you haven't configured location permissions already, you will need to do so to use the device's location services. Before you can draw a user’s location on the map, you must ask for their permission and give a brief explanation of how your application will use their location data.

Configure location permissions by setting the NSLocationWhenInUseUsageDescription key in the Info.plist file. We recommend setting the value to the following string, which will become the application's location usage description: Shows your location on the map and helps improve the map. When a user opens your application for the first time, they will be presented with an alert that asks them if they would like to allow your application to access their location.

Additionally, you may also choose to include the NSLocationAlwaysAndWhenInUseUsageDescription key within your Info.plist file. We recommend providing a different string when using this key to help your users decide which level of permission they wish to grant to your application. For more information about the differences in these permission levels, see Apple’s Choosing the Location Services Authorization to Request document.

Once you have configured your application's location permissions, display the device's current location on the map by setting the showsUserLocation property on the map view to true.

show hidden lines
// Allow the map view to display the user's location
mapView.showsUserLocation = true
show hidden lines

When you run your app in Simulator, you’ll be presented with a dialog box asking for permission to use Location Services. Click Allow.

You won’t see your location on the map until you go to Simulator’s menu bar and select Debug ‣ Location ‣ Custom Location. Enter 40.74699 for latitude, -73.98742 for longitude, and you’re right outside Central Park in New York City!

You built a small app with the Mapbox Maps SDK for iOS! You added a Mapbox map to an iOS application, changed the map style, placed an annotation on your map, and displayed the user’s location on it. Way to go!

As you continue to develop your Mapbox app, we recommend that you read the following:

• Mapbox Maps SDK for iOS homepage for general information about working with the Mapbox Maps SDK for iOS.
• Mapbox Maps SDK for iOS documentation for a complete reference of all classes and methods available.
• Mapbox Maps SDK for iOS code examples to see classes and methods in action.
• Mapbox Maps SDK for iOS on GitHub to read about the open source project behind the Mapbox Maps SDK for iOS.