Mobile applications

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.

unity screenshot

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.

Client-side rendering

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).

Layers

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.

Runtime styling

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

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.

graduated circle map using data-driven styling

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.

selecting individual states with feature querying

The camera

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.

Offline maps

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.

Offline tile count estimator

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.

Learn more about how to use offline maps for iOS and Android in the respective documentation. For more background on offline maps, check out our Offline maps troubleshooting guide.

Telemetry

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:

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.

Maps

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

To keep the Mapbox iOS and Android SDKs small and fast, we provide separate libraries for interfacing with Mapbox web services like the Mapbox Directions API, Geocoding API, and Static API.

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:

Other frameworks

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

The Ionic framework may also be able to use Telerik’s Cordova plugin.

Hybrid frameworks using Mapbox Javascript APIs

Creating hybrid apps with Mapbox GL JS or Mapbox.js is also possible.

Potential problems

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.

For the best possible experience, use our native SDKs directly. Get started now with our First Steps guides for Android and iOS.