Mapbox China plugin for iOS

Current version: v0.0.2

  • Support users in China
  • Shift coordinates to GCJ-02

The Mapbox China Plugin for iOS provides a foundation for using Mapbox China maps. The plugin contains convenience methods for using Mapbox China styles, a transformer that shifts WGS-84 coordinates to GCJ-02, and a custom location manager that provides location updates as GCJ-02 coordinates.

Getting started

To access Mapbox China styles, you will need a special access token. Contact our sales team to start the process of receiving this special access token. You will not be able to access Mapbox China vector tiles without this access token.


Set up the Mapbox China Plugin by installing both the Mapbox Maps SDK for iOS and the Mapbox China Plugin. The Maps SDK can be installed by following the instructions in our installation guide.


Add the following to your Podfile:

pod 'MapboxChinaPlugin'

Then update your project by running pod update in the command line.


Add the following to your Cartfile:

binary "" ~> 0.0.2

Then update your project by running carthage update in Terminal.

Setting up your project

Change the API endpoint

To receive Mapbox China vector tiles, add MGLMapboxAPIBaseURL to your Info.plist as a key, with as its value. This switches the API endpoint for your map's style.

Mapbox China styles

Mapbox currently offers three government-approved map styles: Mapbox China Streets, Dark, and Light. The plugin automatically converts Mapbox Streets, Dark, and Light to their China counterparts, and uses Mapbox China Streets by default.

The plugin provides convenience methods to use to update the map's style URL.

Style NameURL StringConvenience Methods on MGLStyle

Using the Mapbox China Plugin

Add the plugin

The -addToMapView: method adds the China Plugin to an already initialized MGLMapView. This method switches the map's style URL to a China style and configures a location manager that uses GCJ-02 coordinates.

import MapboxChinaPlugin
class ViewController: UIViewController, MGLMapViewDelegate {
override func viewDidLoad() {
let mapView = MGLMapView(frame: view.bounds)
let chinaPlugin = MBXChinaPlugin()
chinaPlugin.add(to: mapView)

Shift coordinates

By default, the Maps SDK uses WGS-84 coordinates. This plugin offers a value transformer which shifts WGS-84 coordinates to GCJ-02, in compliance with Chinese government mapping requirements. Currently, this plugin supports shifting CLLocationCoordinate2D and MGLShape objects. The shift is managed by NSValueTransformer, and MGLConvertToDatumTransformerName, which is an NSValueTransformerName. MGLConvertToDatumTransformerName becomes available either by adding the plugin to the map view, or by initializing MBCNGCJCoordinateTransformer directly.

let transformerName = NSValueTransformerName(rawValue: MGLConvertToDatumTransformerName)
let transformer = ValueTransformer(forName: transformerName)

To shift an annotation, shift the coordinate property of that annotation. This converts a WGS-84 coordinate to a GCJ-02 coordinate. This can also be used to set the center coordinate of the map view.

let unshiftedCoordinate = CLLocationCoordinate2D(latitude: 31.22894, longitude: 121.45434)
// Use the value transformer to shift the coordinate.
guard let transformedValue = transformer.transformedValue(NSValue(mglCoordinate: unshiftedCoordinate)) as? NSValue else { return }
let annotation = MGLPointAnnotation()
// Convert the NSValue back to an CLLocationCoordinate2D. Set the annotation's coordinate property to that shifted value.
let shiftedCoordinate = transformedValue.mglCoordinateValue
annotation.coordinate = shiftedCoordinate
// Set the center coordinate for the map view to the transformed coordinate.
mapView.setCenter(shiftedCoordinate, zoomLevel: 15, animated: false)

This approach also applies to MGLShape and MGLFeature objects, including those created with GeoJSON.

let originalShape = [
CLLocationCoordinate2D(latitude: 31.22869, longitude: 121.4534),
CLLocationCoordinate2D(latitude: 31.22894, longitude: 121.45319),
CLLocationCoordinate2D(latitude: 31.2287, longitude: 121.45279),
CLLocationCoordinate2D(latitude: 31.22844, longitude: 121.45301),
CLLocationCoordinate2D(latitude: 31.22869, longitude: 121.4534)
let shape = MGLPolygon(coordinates: originalShape, count: UInt(originalShape.count))
// Shift the shape's coordinates.
let transformedValue = transformer.transformedValue(shape) as! MGLPolygon


If you have any questions about getting started with Mapbox China Plugin for iOS, please contact us.