advanced
Swift or Objective-C
Switch from Apple MapKit to the Mapbox iOS SDK
Prerequisite
Familiarity with Xcode and either Swift or Objective-C.

The Mapbox iOS SDK is our vector maps library for iOS. This guide is intended to help developers with Apple MapKit experience quickly move their apps to the Mapbox iOS SDK. Both Swift and Objective-C are supported below.

Heads up! We’re still actively developing the Mapbox iOS SDK and will update this guide as we improve its features.

Getting started

Here’s what you’ll need to get started:

New to Mapbox and MapKit? You might want to start with our First steps with the Mapbox iOS SDK guide.

Initialize a map

In MapKit

Map of the Unite States from Apple MapKit

import MapKit

class ViewController: UIViewController {
    override func viewDidLoad() {
        super.viewDidLoad()

        let mapView = MKMapView(frame: self.view.frame)

        view.addSubview(mapView)
    }
}
#import "ViewController.h"
#import <MapKit/MapKit.h>

@implementation ViewController

- (void)viewDidLoad {
    [super viewDidLoad];

    MKMapView *mapView = [[MKMapView alloc] initWithFrame:self.view.frame];

    [self.view addSubview:mapView];
}

@end

In Mapbox

Map of the United States from the Mapbox iOS SDK

import Mapbox

class ViewController: UIViewController {
    override func viewDidLoad() {
        super.viewDidLoad()

        let mapView = MGLMapView(frame: view.bounds)

        view.addSubview(mapView)
    }
}
#import "ViewController.h"
#import <Mapbox/Mapbox.h>

@implementation ViewController

- (void)viewDidLoad {
    [super viewDidLoad];

    MGLMapView *mapView = [[MGLMapView alloc] initWithFrame:self.view.bounds];

    [self.view addSubview:mapView];
}

@end

In Info.plist, set MGLMapboxAccessToken to your access token.

Change map type/style

In MapKit

Map of Cape Town from Apple MapKit

mapView.mapType = .standard;

// available types:
//   .standard
//   .satellite
//   .hybrid
//   .satelliteFlyover (iOS 9)
//   .hybridFlyover (iOS 9)
mapView.mapType = MKMapTypeStandard;

// available types:
//   MKMapTypeStandard
//   MKMapTypeSatellite
//   MKMapTypeHybrid
//   MKMapTypeSatelliteFlyover (iOS 9)
//   MKMapTypeHybridFlyover (iOS 9)

In Mapbox

The Mapbox iOS SDK comes with a number of included styles that you can add to your map using the process described below. You can add a custom style created in Mapbox Studio with its style URL.

Map of Cape Town from the Mapbox iOS SDK

mapView.styleURL = MGLStyle.lightStyleURL(withVersion:9)

// available styles (see MGLStyle documentation):
//   streetsStyleURL(withVersion:)
//   outdoorsStyleURL(withVersion:)
//   lightStyleURL(withVersion:)
//   darkStyleURL(withVersion:)
//   satelliteStyleURL(withVersion:)
//   satelliteStreetsStyleURL(withVersion:)
mapView.styleURL = [MGLStyle lightStyleURLWithVersion:9];

// available styles (see MGLStyle documentation):
//   -streetsStyleURLWithVersion:
//   -outdoorsStyleURLWithVersion:
//   -lightStyleURLWithVersion
//   -darkStyleURLWithVersion:
//   -satelliteStyleURLWithVersion:
//   -satelliteStreetsStyleURLWithVersion:

Centering and zooming

In MapKit

Map of Washington, D.C. from Apple MapKit

let zoomLevel = 15.0
let center = CLLocationCoordinate2D(latitude: 38.894368, longitude: -77.036487)
let span = MKCoordinateSpan(latitudeDelta: 0, longitudeDelta: (360 / (pow(2, zoomLevel)) * Double(mapView.frame.size.width / 256)))

let region = MKCoordinateRegion(center: center, span: span)

mapView.setRegion(region, animated: true)
double zoomLevel = 15;
CLLocationCoordinate2D centerCoordinate = CLLocationCoordinate2DMake(38.894368, -77.036487);

MKCoordinateRegion region = MKCoordinateRegionMake(centerCoordinate, MKCoordinateSpanMake(0, 360 / (pow(2, zoomLevel) * (mapView.frame.size.width / 256))));

[mapView setRegion:region animated:YES];

In Mapbox

Map of Washington, D.C. from the Mapbox iOS SDK

let center = CLLocationCoordinate2D(latitude: 38.894368, longitude: -77.036487)
mapView.setCenter(center, zoomLevel: 15, animated: true)
CLLocationCoordinate2D centerCoordinate = CLLocationCoordinate2DMake(38.894368, -77.036487);
[mapView setCenterCoordinate:centerCoordinate zoomLevel:15 animated:YES];

Bounding box fit

In MapKit

It’s a bit verbose to set a bounding box in Mapkit:

Satellite imagery map from Apple MapKit

let sw = CLLocationCoordinate2D(latitude: 45.5087, longitude: -122.6903)
let ne = CLLocationCoordinate2D(latitude: 45.5245, longitude: -122.6503)

let swPoint = MKMapPointForCoordinate(sw)
let nePoint = MKMapPointForCoordinate(ne)

let swRect = MKMapRectMake(swPoint.x, swPoint.y, 0, 0)
let neRect = MKMapRectMake(nePoint.x, nePoint.y, 0, 0)

let mapRect = MKMapRectUnion(swRect, neRect)

mapView.setVisibleMapRect(mapRect, animated: false)
CLLocationCoordinate2D sw = CLLocationCoordinate2DMake(45.5087, -122.69);
CLLocationCoordinate2D ne = CLLocationCoordinate2DMake(45.5245, -122.65);

MKMapPoint swPoint = MKMapPointForCoordinate(sw);
MKMapPoint nePoint = MKMapPointForCoordinate(ne);

MKMapRect swRect = MKMapRectMake(swPoint.x, swPoint.y, 0, 0);
MKMapRect neRect = MKMapRectMake(nePoint.x, nePoint.y, 0, 0);

MKMapRect mapRect = MKMapRectUnion(swRect, neRect);

[mapView setVisibleMapRect:mapRect animated:NO];

In Mapbox

Satellite imagery map from the Mapbox iOS SDK

// Set the map bounds to Portland, Oregon
let bounds = MGLCoordinateBounds(
    sw: CLLocationCoordinate2D(latitude: 45.5087, longitude: -122.69),
    ne: CLLocationCoordinate2D(latitude: 45.5245, longitude: -122.65))

mapView.setVisibleCoordinateBounds(bounds, animated: false)
// Set the map bounds to Portland, Oregon
CLLocationCoordinate2D sw = CLLocationCoordinate2DMake(45.5087, -122.69);
CLLocationCoordinate2D ne = CLLocationCoordinate2DMake(45.5245, -122.65);

[mapView setVisibleCoordinateBounds:MGLCoordinateBoundsMake(sw, ne) animated:NO];

Camera animation

In MapKit

Map of Tokyo International Airport from Apple MapKit

let coordinate = CLLocationCoordinate2DMake(35.5494, 139.77765)

let camera = MKMapCamera(lookingAtCenter: coordinate, fromDistance: 5000, pitch: 40, heading: 90)

mapView.setCamera(camera, animated: true)
CLLocationCoordinate2D coordinate = CLLocationCoordinate2DMake(35.5494, 139.77765);

MKMapCamera *camera = [MKMapCamera cameraLookingAtCenterCoordinate:coordinate
                                                      fromDistance:6000
                                                      pitch:40
                                                      heading:90];

[mapView setCamera:camera animated:YES];

In Mapbox

Map of Tokyo International Airport from the Mapbox iOS SDK

let coordinate = CLLocationCoordinate2D(latitude: 35.5494, longitude: 139.77765)

let camera = MGLMapCamera(lookingAtCenter: coordinate, fromDistance: 5000, pitch: 40, heading: 90)

mapView.fly(to: camera, completionHandler: nil)
CLLocationCoordinate2D coordinate = CLLocationCoordinate2DMake(35.5494, 139.77765);

MGLMapCamera *camera = [MGLMapCamera cameraLookingAtCenterCoordinate:coordinate
                                                        fromDistance:5000
                                                        pitch:40
                                                        heading:90];

[mapView flyToCamera:camera completionHandler:nil];

Show user location

In MapKit

Map of Manhattan with user location dot from Apple MapKit

mapView.userTrackingMode = .follow

// available modes:
//   none
//   follow
//   followWithHeading
mapView.userTrackingMode = MKUserTrackingModeFollow;

// available modes:
//   MKUserTrackingModeNone
//   MKUserTrackingModeFollow
//   MKUserTrackingModeFollowWithHeading

In Mapbox

Map of Manhattan with user location dot from the Mapbox iOS SDK

mapView.userTrackingMode = .follow

// available modes:
//   none
//   follow
//   followWithHeading
//   followWithCourse
mapView.userTrackingMode = MGLUserTrackingModeFollow;

// available modes:
//   MGLUserTrackingModeNone
//   MGLUserTrackingModeFollow
//   MGLUserTrackingModeFollowWithHeading
//   MGLUserTrackingModeFollowWithCourse

Add pin/marker annotations

In MapKit

Map of Manhattan with marker annotation from Apple MapKit

class ViewController: UIViewController, MKMapViewDelegate {
    override func viewDidLoad() {
        ...

        mapView.delegate = self;

        let hello = MKPointAnnotation()
        hello.coordinate = CLLocationCoordinate2D(latitude: 40.717041, longitude: -73.988007)
        hello.title = "Hello world!"
        hello.subtitle = "Welcome to my marker"

        mapView.addAnnotation(hello)

    }

    func mapView(_ mapView: MKMapView, viewFor annotation: MKAnnotation) -> MKAnnotationView? {

        let annotationView = MKPinAnnotationView()
        annotationView.pinTintColor = .purple

        return annotationView
    }
}
@interface ViewController () <MKMapViewDelegate>
@end

@implementation ViewController

- (void)viewDidLoad {
    ...

    mapView.delegate = self;

    MKPointAnnotation *hello = [[MKPointAnnotation alloc] init];
    hello.coordinate = CLLocationCoordinate2DMake(40.717041, -73.988007);
    hello.title = @"Hello world!";
    hello.subtitle = @"Welcome to my marker";

    [mapView addAnnotation:hello];
}

- (MKAnnotationView *)mapView:(MKMapView *)mapView viewForAnnotation:(id<MKAnnotation>)annotation {
    // simple and inefficient example

    MKPinAnnotationView *annotationView = [[MKPinAnnotationView alloc] init];
    annotationView.pinColor = MKPinAnnotationColorPurple;

    return annotationView;
}

In Mapbox

Map of Manhattan with marker annotation from the Mapbox iOS SDK

class ViewController: UIViewController, MGLMapViewDelegate {
    override func viewDidLoad() {
        ...

        // Set the delegate property of our map view to self after instantiating it.
        mapView.delegate = self

        // Declare the marker `hello` and set its coordinates, title, and subtitle.
        let hello = MGLPointAnnotation()
        hello.coordinate = CLLocationCoordinate2D(latitude: 40.717041, longitude: -73.988007)
        hello.title = "Hello world!"
        hello.subtitle = "Welcome to my marker"

        // Add marker `hello` to the map.
        mapView.addAnnotation(hello)
    }

    // Return `nil` here to use the default marker.
    func mapView(_ mapView: MGLMapView, viewFor annotation: MGLAnnotation) -> MGLAnnotationView? {
        return nil
    }

    // Allow callout view to appear when an annotation is tapped.
    func mapView(_ mapView: MGLMapView, annotationCanShowCallout annotation: MGLAnnotation) -> Bool {
        return false
    }
}
@interface ViewController () <MGLMapViewDelegate>
@end

@implementation ViewController

- (void)viewDidLoad {
    ...

    // Set the delegate property of our map view to self after instantiating it.
    mapView.delegate = self;

    // Declare the marker `hello` and set its coordinates, title, and subtitle.
    MGLPointAnnotation *hello = [[MGLPointAnnotation alloc] init];
    hello.coordinate = CLLocationCoordinate2DMake(40.717041, -73.988007);
    hello.title = @"Hello world!";
    hello.subtitle = @"Welcome to my marker";

    // Add marker `hello` to the map.
    [mapView addAnnotation:hello];
}

// Return `nil` here to use the default marker.
- (MGLAnnotationView *)mapView:(MGLMapView *)mapView viewForAnnotation:(id <MGLAnnotation>)annotation {
    return nil;
}

// Allow callout view to appear when an annotation is tapped.
- (BOOL)mapView:(MGLMapView *)mapView annotationCanShowCallout:(id <MGLAnnotation>)annotation {
    return YES;
}

@end

Next steps

Congratulations, you’ve mastered the basics of switching from MapKit to the Mapbox iOS SDK. Check out all of our iOS SDK documentation for more features to try.

Have other comparisons between MapKit and Mapbox that you’d like to see? Get in touch!