The Mapbox Maps SDK for iOS is our vector maps library for iOS. This guide will walk you through the basics of working 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 similar to 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.
import Mapbox
class ViewController: UIViewController {
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)
}
}
#import "ViewController.h"
@import Mapbox;
@interface ViewController ()
@end
@implementation ViewController
- (void)viewDidLoad {
[super viewDidLoad];
MGLMapView *mapView = [[MGLMapView alloc] initWithFrame:self.view.bounds];
mapView.autoresizingMask = UIViewAutoresizingFlexibleWidth | UIViewAutoresizingFlexibleHeight;
[mapView setCenterCoordinate:CLLocationCoordinate2DMake(40.74699, -73.98742)
zoomLevel:9
animated:NO];
[self.view addSubview:mapView];
}
@end
Changing 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.
import Mapbox
class ViewController: UIViewController {
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
}
}
#import "ViewController.h"
@import Mapbox;
@interface ViewController ()
@end
@implementation ViewController
- (void)viewDidLoad {
[super viewDidLoad];
MGLMapView *mapView = [[MGLMapView alloc] initWithFrame:self.view.bounds];
mapView.autoresizingMask = UIViewAutoresizingFlexibleWidth | UIViewAutoresizingFlexibleHeight;
[mapView setCenterCoordinate:CLLocationCoordinate2DMake(40.74699, -73.98742)
zoomLevel:9
animated:NO];
[self.view addSubview:mapView];
mapView.styleURL = [MGLStyle satelliteStreetsStyleURL];
}
@end
Then run your application to see the map’s new style.
Adding a marker to the map
There are a number of 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 in order to place a point annotation on Central Park within New York City.
class ViewController: UIViewController {
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)
}
}
- (void)viewDidLoad {
[super viewDidLoad];
MGLMapView *mapView = [[MGLMapView alloc] initWithFrame:self.view.bounds];
mapView.autoresizingMask = UIViewAutoresizingFlexibleWidth | UIViewAutoresizingFlexibleHeight;
[mapView setCenterCoordinate:CLLocationCoordinate2DMake(40.74699, -73.98742)
zoomLevel:9
animated:NO];
[self.view addSubview:mapView];
mapView.styleURL = [MGLStyle satelliteStreetsStyleURL];
// Add a point annotation
MGLPointAnnotation *annotation = [[MGLPointAnnotation alloc] init];
annotation.coordinate = CLLocationCoordinate2DMake(40.77014, -73.97480);
annotation.title = @"Central Park";
annotation.subtitle = @"The best park in New York City!";
[mapView addAnnotation:annotation];
}
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. Check out MGLAnnotationView and MGLAnnotationImage for more information about working with these types of annotations.
If you’re looking 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, check out our Adding Points to a Map guide.
Adding 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 in order 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 ensures that the map view knows that an annotation should display a callout when tapped. The full implementation of this is shown below:
import Mapbox
// Enable the view controller to conform to the MGLMapViewDelegate protocol
class ViewController: 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
}
func mapView(_ mapView: MGLMapView, annotationCanShowCallout annotation: MGLAnnotation) -> Bool {
// Always allow callouts to popup when annotations are tapped.
return true
}
}
#import "ViewController.h"
@import Mapbox;
// Enable the view controller to conform to the MGLMapViewDelegate protocol
@interface ViewController () <MGLMapViewDelegate>
@end
@implementation ViewController
- (void)viewDidLoad {
[super viewDidLoad];
MGLMapView *mapView = [[MGLMapView alloc] initWithFrame:self.view.bounds];
mapView.autoresizingMask = UIViewAutoresizingFlexibleWidth | UIViewAutoresizingFlexibleHeight;
[mapView setCenterCoordinate:CLLocationCoordinate2DMake(40.74699, -73.98742)
zoomLevel:9
animated:NO];
[self.view addSubview:mapView];
mapView.styleURL = [MGLStyle satelliteStreetsStyleURL];
// Add a point annotation
MGLPointAnnotation *annotation = [[MGLPointAnnotation alloc] init];
annotation.coordinate = CLLocationCoordinate2DMake(40.77014, -73.97480);
annotation.title = @"Central Park";
annotation.subtitle = @"The best park in New York City!";
[mapView addAnnotation:annotation];
// Set the map view's delegate
mapView.delegate = self;
}
- (BOOL)mapView:(MGLMapView *)mapView annotationCanShowCallout:(id<MGLAnnotation>)annotation {
// Always allow callouts to popup when annotations are tapped.
return YES;
}
@end
Run the application, and then try to tap the annotation — it now displays a callout with your annotation’s title and subtitle when tapped!
Zooming 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 represents 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.
import Mapbox
// Enable the view controller to conform to the MGLMapViewDelegate protocol
class ViewController: UIViewController, MGLMapViewDelegate {
override func viewDidLoad() {
super.viewDidLoad()
let mapView = MGLMapView(frame: view.bounds, styleURL: MGLStyle.satelliteStreetsStyleURL())
mapView.autoresizingMask = [.flexibleWidth, .flexibleHeight]
mapView.setCenter(CLLocationCoordinate2D(latitude: 40.74699, longitude: -73.98742), zoomLevel: 9, animated: false)
view.addSubview(mapView)
// 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 to the view controller
mapView.delegate = self
}
// Implement the delegate method that allows annotations to show callouts when tapped
func mapView(_ mapView: MGLMapView, annotationCanShowCallout annotation: MGLAnnotation) -> Bool {
return true
}
// Zoom to the annotation when it is selected
func mapView(_ mapView: MGLMapView, didSelect annotation: MGLAnnotation) {
let camera = MGLMapCamera(lookingAtCenter: annotation.coordinate, fromDistance: 4000, pitch: 0, heading: 0)
mapView.setCamera(camera, animated: true)
}
}
#import "ViewController.h"
@import Mapbox;
// Enable the view controller to conform to the MGLMapViewDelegate protocol
@interface ViewController () <MGLMapViewDelegate>
@end
@implementation ViewController
- (void)viewDidLoad {
[super viewDidLoad];
MGLMapView *mapView = [[MGLMapView alloc] initWithFrame:self.view.bounds
styleURL:[MGLStyle satelliteStreetsStyleURL]];
mapView.autoresizingMask = UIViewAutoresizingFlexibleWidth | UIViewAutoresizingFlexibleHeight;
[mapView setCenterCoordinate:CLLocationCoordinate2DMake(40.74699, -73.98742)
zoomLevel:9
animated:NO];
[self.view addSubview:mapView];
// Add a point annotation
MGLPointAnnotation *annotation = [[MGLPointAnnotation alloc] init];
annotation.coordinate = CLLocationCoordinate2DMake(40.77014, -73.97480);
annotation.title = @"Central Park";
annotation.subtitle = @"The biggest park in New York City!";
[mapView addAnnotation:annotation];
// Set the map view's delegate to the view controller
mapView.delegate = self;
}
// Implement the delegate method that allows annotations to show callouts when tapped
- (BOOL)mapView:(MGLMapView *)mapView annotationCanShowCallout:(id<MGLAnnotation>)annotation {
return YES;
}
// Zoom to the annotation when it is selected
- (void)mapView:(MGLMapView *)mapView didSelectAnnotation:(id<MGLAnnotation>)annotation {
MGLMapCamera *camera = [MGLMapCamera cameraLookingAtCenterCoordinate: annotation.coordinate fromDistance:4000 pitch:0 heading:0];
[mapView setCamera:camera animated:true];
}
@end
Displaying the user’s location
If you haven’t configured location permissions already, you will need to do so in order 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 represents 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.
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.
import Mapbox
class ViewController: UIViewController, MGLMapViewDelegate {
override func 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
}
// Zoom to the annotation when it is selected
func mapView(_ mapView: MGLMapView, didSelect annotation: MGLAnnotation) {
let camera = MGLMapCamera(lookingAtCenter: annotation.coordinate, fromDistance: 4000, pitch: 0, heading: 0)
mapView.fly(to: camera, completionHandler: nil)
}
}
#import "ViewController.h"
@import Mapbox;
// Enable the view controller to conform to the MGLMapViewDelegate protocol
@interface ViewController () <MGLMapViewDelegate>
@end
@implementation ViewController
- (void)viewDidLoad {
[super viewDidLoad];
MGLMapView *mapView = [[MGLMapView alloc] initWithFrame:self.view.bounds];
mapView.autoresizingMask = UIViewAutoresizingFlexibleWidth | UIViewAutoresizingFlexibleHeight;
[mapView setCenterCoordinate:CLLocationCoordinate2DMake(40.74699, -73.98742)
zoomLevel:9
animated:NO];
[self.view addSubview:mapView];
mapView.styleURL = [MGLStyle satelliteStreetsStyleURL];
// Add a point annotation
MGLPointAnnotation *annotation = [[MGLPointAnnotation alloc] init];
annotation.coordinate = CLLocationCoordinate2DMake(40.77014, -73.97480);
annotation.title = @"Central Park";
annotation.subtitle = @"The best 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 = YES;
}
// Zoom to the annotation when it is selected
- (void)mapView:(MGLMapView *)mapView didSelectAnnotation:(id<MGLAnnotation>)annotation {
MGLMapCamera *camera = [MGLMapCamera cameraLookingAtCenterCoordinate: annotation.coordinate fromDistance:4000 pitch:0 heading:0];
[mapView flyToCamera:camera completionHandler:nil];
}
@end
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!
Next steps
You just 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 home page 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.
