Step by step guide on how to use Mapbox on iOS


What is Mapbox?

Have you ever thought about building an application around navigation which allows users to explore places using proper maps? Today we’re going to set up and run “your own Google Maps” using Mapbox (just without Google).

What is Mapbox? It’s a group of services, SDKs and APIs for map building and navigation. We’ll check how to use “Mapbox Maps SDK for iOS” where the core of our interest is the map. Mapbox SDK is a flexible tool which allows you to choose the map data provider. You can let Mapbox do all the work in a subscription mode or provide OpenStreetMap (OSM) data from your server backend and have fully working setup for free. Here we’re going to take a simplistic approach and use Mapbox resource. It’s free to use until you reach a significant number of users (you can check details here).

Mapbox installation

The first steps process is fairly simple. The requirements here are: having Xcode installed on your system, minimum iOS development experience and a Mapbox account. It’s necessary to obtain a permission token to get access to their map source. It’s not needed when you provide map data.

Already have it? Ok, so let’s go!

For those already in the field, here we have some shortcut:


Create a new file in project main folder, name it “podfile” (in terminal simply enter: “touch podfile”) and then add this:

Then run:


Add this to your Cartfile:

Then run:

Standard “Carthage” – specific steps apply.


A dead simple way is just to download “Mapbox.framework” file from:

and follow the instructions there.

Make sure that you have “MGLMapboxAccessToken” entry in an info.plist file, with your personal access token. This authorizes your app to use Mapbox resources. You can find it at site. Just sign in and look for the “Access tokens” section.

Simple example

There are two ways of displaying a simple map example:

The first way:

  • Go to your “Main.storyboard”
  • Change top “View” class type to “MGLMapView
  • Having already selected “View”, set “Style URL” to “mapbox://styles/mapbox/streets-v10

Still, the best way for customizing your map will be doing it from code.

Second way:

Add variable:

inside a view controller of your choice, then just add this code in viewDidLoad:

Remember to add this line of code at top of file: import Mapbox.

Run and check if your map looks something like this:

perfect place for outsourcing

Now we’re ready to move on to more interesting things.

Customizing and styling your map in Mapbox

User position

A first obvious step is to display the user position on our newly created map view.

Add this code at the end of viewDidLoad method and run the project again:

The app crashed and you have got an exception? That’s because we didn’t ask the user for the permission when Mapbox was trying to get GPS position (so you don’t have to setup CLLocationManager and delegates, and all that stuff).

Go to an “Info.plist” file and add “NSLocationWhenInUseUsageDescription” key. For value, use whatever you like. I used “We need your location for displaying it on the map”. Always inform the user if you store location or use it for any other reason. Of course your app can be developed, but when dealing with the real project, it could be rejected during the AppStore review (keep that in mind). We could also use the option which allows access to the user location always, even when the app is in the background (but we won’t need it for our purposes).

When you run your app, you should get a system alert:

Mapbox system alert

After authorisation a pointer on the map will indicate your current location:

user position mapbox a pointer on the map


We often need to show something more than just the user’s position. Mapbox gives the annotation types for that. Annotation is a marker that can be placed on the map.

Add new method and call it at the end of “viewDidLoad”:

Now your map shows point annotation, but what is there “title and “subtitle” for? To see the callout. By default, tapping on the marker does not trigger any action, because first we have to tell Mapbox to do so.

Write this line of code in – yep, you guessed – “viewDidLoad”:

And at end of the file:

The result is a simple pin on the map with callout and some text:

pin on the map


MGLMapView provides some interesting methods, such as conversion from screen-space coordinates to geo coordinates and vice versa.

MGLMapView conversion methods

We can use it, for example, to allow the user to mark his favorite pizza restaurants or other points of interest. This is a pretty simple feature so let’s add this one to viewDidLoad:

And at end of the same file:

Modify “addNewAnnotation” method to take a CLLocationCoordinate2D instance as an argument and run your project. You should see something like this:

Map annotations


Camera in Mapbox is similar to the real world thing. It allows precise customization of users’ viewing position, height and angle. This is the “eye” through which map is visible. MGLMapView has always some default camera set and we used it even without knowing a bit about it. When we pan on the map, we change position of this default camera. Remember this line?

This is just a convenient method for:

We can replace the default camera with our own, which can have very different properties. We can animate between cameras and chain animations with mapView.setCamera method and completion handlers.


I hope that this article has given you a glimpse into what you can do with Mapbox. You have learned how to install and run your first simple map, get user position, fill it with annotations and make a showcase to a user with a smooth animating camera. That’s a solid ground for your own projects.

See you next time and happy coding!