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.
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.
show hidden lineslet 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
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
.
show hidden linesmapView.styleURL = MGLStyle.satelliteStyleURLshow hidden lines
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.
show hidden lines// Add a point annotationlet 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.
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:
show hidden linesmapView.delegate = selfshow hidden linesfunc 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!
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.
show hidden linesfunc 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
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 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.
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
.
show hidden lines// Allow the map view to display the user's locationmapView.showsUserLocation = trueshow hidden lines
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 Features ‣ 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
import UIKitimport 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 annotationlet 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 delegatemapView.delegate = self // Allow the map view to display the user's locationmapView.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 Maps SDK for iOS on GitHub to read about the open source project behind the Mapbox Maps SDK for iOS.