Mapbox GL

From OpenStreetMap Wiki
(Redirected from Node-mapbox-gl-native)
Jump to navigation Jump to search
Mapbox Maps SDK
Mapbox logo 2017.svg
Author: Mapbox
License: Proprietary (v2) and BSD (v1)
Platforms: Android, iOS, Web, macOS, and Qt
Version: Varies by platform
Language: multiple languages
Source code: GL JS, Android, iOS/macOS
Programming languages: AppleScript, C++, Java, JavaScript, Kotlin, Objective-C, and Swift

Embed customizable, interactive vector maps in Web, mobile, and desktop applications

The Mapbox Maps SDK is a suite of proprietary – formerly open-source – libraries developed by Mapbox for embedding customizable slippy maps in Web, mobile, and desktop applications. There is also a library for building server-side or command-line rendering tools. The MapLibre project maintains a fork of the last free and open source versions.

The Mapbox Maps SDK is based on the Mapbox GL renderer, which takes #Mapbox styles, applies them to vector tiles that conform to the Mapbox Vector Tile Specification via TileJSON manifests, and renders them dynamically using OpenGL for high performance. By default, Mapbox GL displays Mapbox Streets vector tiles based on OpenStreetMap data. The developer can choose among several Mapbox-designed styles or design a custom style in the graphical style editor of Mapbox Studio.

On mobile platforms, the Mapbox Telemetry component uses the device's location data to facilitate improvements to OpenStreetMap data.

Mapbox GL also powers the Mapbox Static API, which produces static map images on the server side for situations where interactivity is unnecessary or impractical. Mapbox Studio supports high-resolution printing based on Mapbox GL. The Mapbox Maps SDK for Android and iOS is the basis of the Mapbox Navigation SDK for Android and iOS.


The Mapbox Maps SDK is available as a freely downloadable library on a number of platforms. Version numbers vary by platform. The following libraries are officially supported by Mapbox, except for the macOS SDK. The macOS SDK is community-maintained, although it shares the majority of its code with the Mapbox-developed iOS SDK. The Android, iOS, macOS, Qt, and Node libraries are collectively referred to as “Mapbox GL Native”, since they target native platform technologies via compiled languages.

Library Platform Target languages Latest release
Mapbox GL JS Web JavaScript Download
Mapbox Maps SDK for Android Android Java, Kotlin Look for “android-”
Mapbox Maps SDK for iOS iOS Objective-C, Swift, Interface Builder Look for “ios-”
Mapbox Maps SDK for macOS macOS Objective-C, Swift, Interface Builder, AppleScript Look for “macos-”, maintained by community only
node-mapbox-gl-native Node.js JavaScript Look for “node-”, latest release in 2019[2]

The Qt Location API in Qt 5.9 and the Qt Automotive Suite includes a Mapbox GL geoservices plugin.[3] The Mapbox Maps SDK for Unity and the Mapbox SceneKit SDK are not based on Mapbox GL but nonetheless support many of the same technologies.

Some compatibility libraries for hybrid application toolkits are contributed by Telerik and other members of the Mapbox developer community:

The following plugins embed Mapbox GL JS in virtual reality scene graphs:

The following plugins embed Mapbox GL JS in prototyping environments:

The following plugins embed Mapbox GL JS in analysis environments:

The Mapbox GL–powered Mapbox Static API is available through the following client-side libraries:

  • Mapbox Java SDK (com.mapbox.api.staticmap package) in Java SE and on Android
  • MapboxStatic.swift in Swift, Objective-C, and AppleScript on iOS, macOS, tvOS, and watchOS

Mapbox styles

Main article: Mapbox styles

Mabox GL has its own format for stylesheets, described in the Mapbox Style Specification.

Mapbox styles are available via the Mapbox Styles API. More styles can be found on GitHub.

Mapbox styles may be edited with the proprietary Mapbox Studio or the open source Maputnik.


The Mapbox Maps SDK's feature set varies by platform. In general, rendering features are added to Mapbox GL JS first then ported to the native SDKs, while smartphone-centric features tend to be specific to the native SDKs.

This table was last updated 01:40, 9 November 2018 (UTC).

Feature JS Android iOS macOS Qt node.js
OSM base map yes yes yes yes yes yes
Terrain base map yes yes yes yes yes yes
Satellite base map yes yes yes yes yes yes
Custom styles yes yes yes yes yes yes
High-resolution rendering (Retina) yes yes yes yes yes yes
Continuous zooming yes yes yes yes yes yes
Rotation yes yes yes yes yes yes
Perspective (tilt, pitch) yes yes yes yes yes yes
Axonometric (orthographic, skewed) projection no No yes
Localized labels Optional[a 1] Optional[a 2] yes yes no[a 3] no[a 3]
3D building extrusion yes yes yes yes yes yes
Styleable DEM terrain yes yes yes yes yes yes
Heat maps yes yes yes yes yes yes
Viewport animation yes yes yes yes yes N/A
Multitouch gestures partial yes yes yes yes N/A
Keyboard shortcuts yes yes No yes N/A N/A
Markers (point annotations) yes yes yes yes yes no
Marker views (view-backed annotations) yes Optional[a 4] yes No no no
Marker keyframe animation no Optional[a 4] yes No no N/A
Shape overlays (shape annotations) no yes yes yes yes no
Arbitrary GeoJSON yes yes yes yes yes yes
GeoJSON point clustering yes yes yes yes no yes
Popups (callouts, popovers, info windows) yes yes yes yes no N/A
Tooltips no N/A N/A yes no N/A
Georeferenced images yes yes yes yes yes yes
Embedded video yes No N/A
User location (user dot) yes yes yes No no N/A
Customizable user dot yes yes yes no no N/A
User location tracking (GPS tracking) yes yes yes N/A N/A N/A
Telemetry no Optional Optional no no no
Offline maps no yes yes yes yes no
WMS yes yes yes yes yes yes
TMS yes yes yes yes yes yes
Attribution control yes yes yes yes yes no
Scale control yes Optional[a 5] yes no no no
Localized UI no yes yes yes no N/A
Bidirectional (right-to-left) text Optional yes yes yes yes yes
Complex text shaping Optional[a 6] partial[a 6] partial[a 6] partial[a 6] partial[a 6] partial[a 6]
Vertical CJK text yes yes yes yes yes yes
Data-driven styling (property expressions) yes yes yes yes Partial[a 7][a 8]
Style introspection (runtime styling) yes yes yes yes partial yes
Data introspection (feature eventing, feature querying) yes yes yes yes no partial[a 9]
Screenreader support (accessibility) Optional[a 10] no yes No no N/A
Text scaling (Dynamic Type) no no In progress no no
Static snapshots no yes yes yes no yes
Printing no yes No yes no N/A
IDE integration (code completion, documentation) no yes yes yes yes no
Dash docset no No yes yes no no
  1. Via the Mapbox GL Language plugin.
  2. Via the Localization plugin.
  3. 3.0 3.1 No built-in option, but a specific language can be specified by the style or application using runtime styling.
  4. 4.0 4.1 Via the MarkerView plugin.
  5. Via the ScaleBar plugin.
  6. 6.0 6.1 6.2 6.3 6.4 6.5 Arabic and Hebrew only.
  7. Expressions are not yet supported.
  8. Data-driven styling at runtime is not yet supported.
  9. Queries rendered features only. Source feature querying is not yet implemented.
  10. Via the Mapbox GL Accessibility plugin.

You can track the effort to ensure feature parity between the various platforms:

The GL JS roadmap lists current and upcoming priorities for Mapbox GL JS and, by extension, the other SDKs.


Originally, Mapbox developed raster map libraries: mapbox.js for the Web; the Mapbox iOS SDK, based on Route-Me; MBXMapKit, based on Apple’s MapKit framework, also for iOS; and the Mapbox Android SDK. Over time, Mapbox has deprecated these libraries in favor of vector map libraries.

Mapbox GL JS was introduced in August 2014. An Android port began in January 2014, followed by a preview of an iOS port that June. Mapbox GL for iOS officially launched in May 2015 before being renamed “Mapbox iOS SDK”. The Mapbox Android SDK launched in October 2015. React Native Mapbox GL began in December 2015 as an experimental project.

The Mapbox Qt SDK and Mapbox OS X SDK launched in May 2016; the latter was renamed “Mapbox macOS SDK”. In June 2017, the Mapbox Qt SDK was incorporated into Qt 5.9 and the Qt Automotive Suite as the “Qt Location Mapbox GL plugin”. [1] React Native Mapbox GL relaunched as an official Mapbox product in September 2017. The Android, iOS, macOS, and Qt SDKs were renamed to the “Mapbox Maps SDK” in November and December 2017. React Native Mapbox GL transitioned to community-led development in February 2019. [2]

In November 2019, the Android, iOS, and macOS map SDKs moved to new forked repositories while the cross-platform Mapbox GL Native codebase remained in the original repository. [3].

In December 2020, Mapbox GL JS moved from 3-Clause BSD license to proprietary Mapbox Terms of Service. It may only be used by Mapbox clients. The last release under BSD license, v1.31.1, served as a base MapLibre GL JS, an independent fork. In April 2020, the last versions of Mapbox GL Native (1.6.0, android-9.2.1 and ios-5.9) were released under BSD license. Later versions of Mapbox GL Native core are released in binary form under Mapbox Terms of Service only. The SDKs for iOS and Android themselves are still BSD but depend on the non-free binary. The MapLibre community maintains a fork of the free version called MapLibre GL Native as well[4].


The Mapbox Maps SDK for Android and iOS features Mapbox Telemetry, a component that sends the user's location to Mapbox servers in anonymized, aggregated form. This data is either collected at all times or while the application is in use, depending on the application's configuration. Mapbox uses the collected location data for the purpose of:

  • Helping the Mapbox Data Team target improvements to OpenStreetMap where they're most needed. For example, if a high volume of location data points indicates that drivers consistently avoid turning left at a given intersection, the team can enter a turn restriction into OpenStreetMap with greater confidence.
  • Powering OpenStreetMap-based maps that indicate traffic congestion and OSRM-powered directions that avoid traffic congestion, helping OpenStreetMap-based maps achieve feature parity with maps based on proprietary data sources.

The SDKs for Android and iOS provide an option for privacy-conscious end users to turn off Mapbox Telemetry at any time. More information about Mapbox Telemetry, including how Mapbox uses this data while protecting users' privacy and minimizing battery usage. Mapbox GL JS for usage on the web may only be used with enabled telemetry,[5] which does not include the location tracking found in the mobile SDKs.

Notes and references

  1. mapbox-gl-js 2.0.0 on NPM
  2. Latest release for Node is 5.0.3-alpha from 24 October 2019.
  3. The Mapbox GL geoservices plugin is based on the Maps SDK for Qt. The SDK itself was last updated in March 2018.
  4. MapLibre: Mapbox GL open-source fork, MapTiler blog, 8 January 2021
  5. Mapbox GL JS is licensed under Mapbox Terms of Service whose section 2.1 includes the Service Terms. The Service Terms section 8.1 prohibit modifications interfering how Mapbox Web SDK send data to Mapbox.

External links