beginner

Swift or Objective-C

First steps with the Mapbox Maps SDK for iOS

Prerequisite

Familiarity with Xcode and either Swift or Objective-C, and completion of the Mapbox Maps SDK for iOS installation guide.

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.

Getting started

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.

swift

objective-c


import UIKit
import Mapbox
 
class FirstStepsTutorialViewController: UIViewController, MGLMapViewDelegate {
override func viewDidLoad() {
super.viewDidLoad()
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)
mapView.styleURL = MGLStyle.satelliteStyleURL
 
// 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)
 
// Set the map view's delegate
mapView.delegate = self
 
// Allow the map view to display the user's location
mapView.showsUserLocation = true
}
 
func mapView(_ mapView: MGLMapView, annotationCanShowCallout annotation: MGLAnnotation) -> Bool {
// Always allow callouts to popup when annotations are tapped.
return true
}
 
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)
}
}

Change the map style

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.

swift

objective-c


import UIKit
import Mapbox
 
class FirstStepsTutorialViewController: UIViewController, MGLMapViewDelegate {
override func viewDidLoad() {
super.viewDidLoad()
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)
mapView.styleURL = MGLStyle.satelliteStyleURL
 
// 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)
 
// Set the map view's delegate
mapView.delegate = self
 
// Allow the map view to display the user's location
mapView.showsUserLocation = true
}
 
func mapView(_ mapView: MGLMapView, annotationCanShowCallout annotation: MGLAnnotation) -> Bool {
// Always allow callouts to popup when annotations are tapped.
return true
}
 
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)
}
}

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

Add a marker to the map

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.

swift

objective-c


import UIKit
import Mapbox
 
class FirstStepsTutorialViewController: UIViewController, MGLMapViewDelegate {
override func viewDidLoad() {
super.viewDidLoad()
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)
mapView.styleURL = MGLStyle.satelliteStyleURL
 
// 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)
 
// Set the map view's delegate
mapView.delegate = self
 
// Allow the map view to display the user's location
mapView.showsUserLocation = true
}
 
func mapView(_ mapView: MGLMapView, annotationCanShowCallout annotation: MGLAnnotation) -> Bool {
// Always allow callouts to popup when annotations are tapped.
return true
}
 
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)
}
}

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.

Add a callout

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:

swift

objective-c


import UIKit
import Mapbox
 
class FirstStepsTutorialViewController: UIViewController, MGLMapViewDelegate {
override func viewDidLoad() {
super.viewDidLoad()
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)
mapView.styleURL = MGLStyle.satelliteStyleURL
 
// 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)
 
// Set the map view's delegate
mapView.delegate = self
 
// Allow the map view to display the user's location
mapView.showsUserLocation = true
}
 
func mapView(_ mapView: MGLMapView, annotationCanShowCallout annotation: MGLAnnotation) -> Bool {
// Always allow callouts to popup when annotations are tapped.
return true
}
 
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)
}
}

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

Zoom to a marker

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.

swift

objective-c


import UIKit
import Mapbox
 
class FirstStepsTutorialViewController: UIViewController, MGLMapViewDelegate {
override func viewDidLoad() {
super.viewDidLoad()
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)
mapView.styleURL = MGLStyle.satelliteStyleURL
 
// 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)
 
// Set the map view's delegate
mapView.delegate = self
 
// Allow the map view to display the user's location
mapView.showsUserLocation = true
}
 
func mapView(_ mapView: MGLMapView, annotationCanShowCallout annotation: MGLAnnotation) -> Bool {
// Always allow callouts to popup when annotations are tapped.
return true
}
 
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)
}
}

Display the user’s location

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 is the application's location usage description: Shows your location on the map and helps improve OpenStreetMap. Additionally, you may also choose to include the NSLocationAlwaysAndWhenInUseUsageDescription 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. 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.

Note

If your application targets iOS 10 or below, you may also include the `NSLocationAlwaysUsageDescription` key your application. Note that this key is ignored in iOS 11.

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.

swift

objective-c


import UIKit
import Mapbox
 
class FirstStepsTutorialViewController: UIViewController, MGLMapViewDelegate {
override func viewDidLoad() {
super.viewDidLoad()
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)
mapView.styleURL = MGLStyle.satelliteStyleURL
 
// 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)
 
// Set the map view's delegate
mapView.delegate = self
 
// Allow the map view to display the user's location
mapView.showsUserLocation = true
}
 
func mapView(_ mapView: MGLMapView, annotationCanShowCallout annotation: MGLAnnotation) -> Bool {
// Always allow callouts to popup when annotations are tapped.
return true
}
 
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)
}
}

Simulating a location

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!

Finished product

swift

objective-c


import UIKit
import Mapbox
 
class FirstStepsTutorialViewController: UIViewController, MGLMapViewDelegate {
override func viewDidLoad() {
super.viewDidLoad()
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)
mapView.styleURL = MGLStyle.satelliteStyleURL
 
// 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)
 
// Set the map view's delegate
mapView.delegate = self
 
// Allow the map view to display the user's location
mapView.showsUserLocation = true
}
 
func mapView(_ mapView: MGLMapView, annotationCanShowCallout annotation: MGLAnnotation) -> Bool {
// Always allow callouts to popup when annotations are tapped.
return true
}
 
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)
}
}

Next steps

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 GL Native on GitHub to read about the open source project behind the Mapbox Maps SDK for iOS.