The Mapbox iOS SDK and Mapbox Android SDK are open source tools for adding Mapbox maps to mobile applications. Both SDKs are built on top of Mapbox’s open source OpenGL-based renderer, Mapbox GL Native, and support a full suite of dynamic styling features and interactivity. You can add your custom Mapbox style, search for locations using the Mapbox Geocoding API, or get directions, all without leaving your app. Where possible, the Mapbox iOS and Android SDKs are written to provide straightforward drop-in replacements for common platform-specific maps SDKs. This guide outlines how the Mapbox mobile SDKs work and how Mapbox services can be added to a mobile application.
How the Mapbox mobile SDKs work
The Mapbox iOS and Android SDKs allow you to add interactive maps to your mobile applications, define custom and dynamic style rules, manipulate custom data, and interface with Mapbox web APIs.
At the heart of the Mapbox iOS and Android SDKs is Mapbox GL: a powerful rendering engine that reads raw data and style rules and outputs complete, rendered maps on the device. While traditional server-side rendering is great for creating static map tiles, the resulting tiles cannot be styled once they reach the client. With Mapbox GL, tiles can be rendered directly on the client. This enables you to create dynamic visualizations, add and remove layers on the fly, and adjust your style’s properties based on data or the user’s unique needs.
Layers and runtime styling
Many popular map libraries conform to the “basemap-overlay” paradigm in which a map is composed of two distinct types of layers: the basemap (a complete map that provides the foundation and context for the map) and the overlay (often interactive data that is added on top of the basemap, usually at runtime).
While the basemap-overlay strategy has worked well for a long time, there are a number of drawbacks. Overlays often obscure basemap labels below and large overlay datasets quickly become cumbersome.
Mapbox maps do away with the basemap-overlay strategy and treat everything on the map as a layer that can be independently styled and moved up and down the rendering stack. In this approach to displaying maps, a layer is a styled representation of vector or raster data that is rendered using rules about how certain data should be drawn on the map. This strategy allows data to be added without obscuring contextual features like labels.
Because everything in the map is rendered from vector or raster tiles on the device in realtime, Mapbox maps have no distinction between baselayers and overlay layers. This means that every element of the map can be added, removed, and styled dynamically at runtime, just like overlays in other mapping libraries.
Data-driven styling enables you to change a map style based on data properties. For example, you can change the radius of a circle at an intersection based on the number of pedestrians crossing the intersection, or change the color of a state boundary fill-layer based on the population of each state.
Feature querying and interactivity
One benefit of rendering maps on the device at runtime is that it enables the map user to query any feature in the map, including what would have once been considered the “basemap.” Using feature querying, you can add interactivity to any layer in your map style. For example, you can use feature querying to build an app that allows your users to tap on a park polygon to open a popup that contains information about the park.
The Mapbox iOS and Android SDKs include methods for querying features that have been rendered on the map or features that have not been rendered, but are present in the tiles currently loaded in the map view. Check out the Select a feature using feature querying example to see feature querying in action.
The camera represents the map’s field of view. The viewpoint of the camera in many popular mapping libraries is determined by the map’s centerpoint and zoom level. The Mapbox iOS and Android SDKs also include parameters for adjusting the map’s perspective.
- Centerpoint: in decimal degrees and longitude, latitude order.
- Zoom level: any number between 0 and 22. This can be a fractional number like 1.5 or 6.2.
- Bearing: a map rotation value in degrees. The map will be rotated and details like text labels will react by rotating right-side-up.
- Tilt: also in degrees, a value by which the map will be tilted in perspective.
Applications built with the Mapbox Android SDK or Mapbox iOS SDK can download maps of pre-selected regions for use when the device lacks network connectivity. Offline maps are useful for apps whose users expect to travel through areas with limited data connectivity or who want to save on cellular roaming charges while traveling abroad.
To estimate the number of tiles needed to download a region offline, check out our offline tile count estimator. Please note that this only generates an estimate of the number of tiles needed to load a defined region offline. The size of the download will vary according to the location being downloaded and the style being used in your application.
Our mobile SDKs also automatically cache tiles and other resources that are requested during normal use of the app. These resources are stored in the same database as offline resources, but unlike offline resources, they are limited to 50 MB of space. When this limit is reached, the least-recently used resources that aren’t shared by an offline region will be evicted to make room for newer resources.
If you’re developing a native app with one of the Mapbox mobile SDKs, you are required to provide a telemetry opt-out option within your app for all end users. Your users should be in charge of their own location data and when it is shared.
As a developer, you are responsible for making opting out easy for your users. Visit the Mapbox iOS and Android SDK documentation for more information on how to provide a telemetry opt out:
- Telemetry opt out information for the Mapbox iOS SDK
- Telemetry opt out information for the Mapbox Android SDK
Adding Mapbox to your mobile app
Mapbox provides a variety of tools to help you integrate Mapbox maps and our other web services, like directions, geocoding, and static maps, into your mobile application.
To get started, visit the Mapbox iOS and Android SDK overview pages, which include installation instructions, API documentation, and sample code:
If you would like a more guided introduction to building your first app with Mapbox iOS and Android SDKs, check out our first steps guides:
Mapbox web services
On Android, Mapbox Android Services provides convenient interfaces to many Mapbox web services APIs as well as a handful of useful utilities for performing common geospatial tasks.
On iOS, MapboxGeocoder.swift, MapboxDirections.swift, and MapboxStatic.swift provide interfaces to the Mapbox Geocoding, Directions, and Static APIs.
For installation instructions, API documentation, and code examples, please visit each platform’s respective documentation pages:
Mapbox Navigation SDKs
The Mapbox Navigation SDKs are built on top of the Mapbox Directions API and provide all of the logic necessary to implement a navigation experience in your app. The Mapbox Navigation SDKs include critical features like:
- Drop-in turn-by-turn navigation UI.
- Automotive, cycling, and walking directions.
- Traffic avoidance.
- Maneuver announcements.
- Text instructions.
- Text to speech support.
- Automatic rerouting.
- Snap to route.
To include the Mapbox Navigation SDKs in your application, please visit the respective documentation pages for installation instructions, API reference, and sample code:
While Mapbox does not offer official support for hybrid frameworks, third-parties have created plugins and integrations that allow to you use Mapbox SDKs with a variety of alternative development platforms.
See our hybrid pricing guide for more information on how usage of your app will be billed.
Hybrid integrations of native Mapbox SDKs
- React Native Mapbox GL for React Native applications on iOS and Android.
- Telerik’s Mapbox plugin for Apache Cordova Hybrid applications.
- Telerik’s Mapbox plugin for NativeScript Hybrid applications.
- Xamarin’s Mapbox component for Xamarin Hybrid applications.
The Ionic framework may also be able to use Telerik’s Cordova plugin.
Please contact the maintainers of these integrations directly if you encounter issues or have implementation questions, as we are not able to provide official support for hybrid frameworks.
Development of the Mapbox iOS SDK and Mapbox Android SDK both move quickly and new features are released on a regular basis. Third-party plugins that rely on these native SDKs may break with new versions, lag behind the official releases, and not support all available features.