Mapbox iOS SDK

The Mapbox iOS SDK is an open-source framework for embedding interactive map views with scalable, customizable vector maps into Cocoa Touch applications on iOS 7.0 and above using Objective-C, Swift, or Interface Builder. It takes stylesheets that conform to the Mapbox Style Specification, applies them to vector tiles that conform to the Mapbox Vector Tile Specification, and renders them using OpenGL.

Mapbox iOS SDK screenshots

For setup information, check out the Mapbox iOS SDK homepage. For detailed usage instructions, read “First steps with the Mapbox iOS SDK” and consult the online examples. A full changelog is also available.

If you have any questions, please contact our support team. We welcome your bug reports and feature requests.

Changes in version 3.4.0

Packaging

  • Xcode 7.3 or above is required for using this SDK. (#6059)
  • Clarified that the -ObjC linker flag is required for linking against the static framework distribution of this SDK. (#6213)
  • The API reference has a sharper look. (#7422)
  • Added documentation for the Info.plist keys used by this SDK. (#6833)

Styles and data

  • A new runtime styling API allows you to adjust the style and content of the base map dynamically. All the options available in Mapbox Studio are now exposed via MGLStyle and subclasses of MGLStyleLayer and MGLSource. (#5727)
  • MGLMapView’s styleURL property can now be set to an absolute file URL. (#6026)
  • When creating an MGLShapeSource, you can now specify options for clustering point features within the shape source. Similarly, GeoJSON sources specified by the stylesheet at design time can specify the cluster, clusterMaxZoom, and clusterRadius attributes. (#5724)
  • Added quadkey support and limited WMS support in raster tile URL templates. (#5628)
  • When creating an MGLTileSource, you can now specify that the tile URLs use TMS coordinates by setting MGLTileSourceOptionTileCoordinateSystem to MGLTileCoordinateSystemTMS. TileJSON files can specify "scheme": "tms". (#2270)
  • Fixed an issue causing abstract MGLMultiPointFeature objects to be returned in feature query results. Now concrete MGLPointCollectionFeature objects are returned. MGLMultiPointFeature is now an alias of MGLPointCollectionFeature. (#6742)
  • Fixed rendering artifacts and missing glyphs that occurred after viewing a large number of CJK characters on the map. (#5908)
  • -[MGLMapView resetPosition] now resets to the current style’s default center coordinates, zoom level, direction, and pitch, if specified. (#6127)
  • Fixed an issue where feature querying sometimes failed to return the expected features when the map was tilted. (#6773)
  • MGLFeature’s attributes and identifier properties are now writable. (#6728)
  • The action sheet that appears when tapping the information button in the bottom-right corner now lists the correct attribution for the current style. (#5999)
  • Added support for MGLSymbolStyleLayer’s textPitchAlignment property and the corresponding style JSON property for improved street label legibility on a tilted map. (#5288)
  • Added support for MGLSymbolStyleLayer’s iconTextFit and iconTextFitPadding properties and the corresponding style JSON properties, allowing the background of a shield to automatically resize to fit the shield’s text. (#5334)
  • Added support for MGLSymbolStyleLayer’s circlePitchScale property and the corresponding style JSON property, allowing circle features in a tilted base map to scale or remain the same size as the viewing distance changes. (#5576)
  • The identifier property of an MGLFeature may now be either a number or string. (#5514)
  • If MGLMapView is unable to obtain or parse a style, it now calls its delegate’s -mapViewDidFailLoadingMap:withError: method. (#6145)
  • Added the -[MGLMapViewDelegate mapView:didFinishLoadingStyle:] delegate method, which offers the earliest opportunity to modify the layout or appearance of the current style before the map view is displayed to the user. (#6636)
  • Fixed crashes that could occur when loading a malformed stylesheet. (#5736)
  • Fixed an issue causing stepwise zoom functions to be misinterpreted. (#6328)
  • A source’s tiles are no longer rendered when the map is outside the source’s supported zoom levels. (#6345)
  • Improved style parsing performance. (#6170)
  • Improved feature querying performance. (#6514)
  • Fixed an issue where shapes that cannot currently be visually represented as annotations were still shown on the map as point annotations. (#6764)

User location

  • The user dot now animates between user locations when user tracking is disabled. (#6215)
  • To customize the appearance of the user location annotation, subclass the newly added MGLUserLocationAnnotationView class and implement -[MGLMapViewDelegate mapView:viewForAnnotation:]. (#5882)
  • -[MGLMapView viewForAnnotation:] now returns the user location annotation view when given the user location annotation. (#6957)
  • Fixed an issue causing the user dot’s accuracy ring to wobble while zooming in and out. (#6019)
  • Heading accuracy indicator sizing has been changed to appear more precise. (#6120)
  • Fixed an issue that caused the map to not update to reflect the centerOffset when the user location was tracked. (#6216)

Annotations

  • Added new methods to MGLMultiPoint for changing the vertices along a polyline annotation or the exterior of a polygon annotation. (#6565)
  • Added new APIs to MGLMapView to query for visible annotations. Combined with -[MGLMapView viewForAnnotation:], these APIs can be used to access all visible annotation views. (6061)
  • Shape, feature, and annotation classes now conform to NSSecureCoding. (#6559)
  • Fixed an issue causing offscreen annotation views to be updated even when they were in the reuse queue. (#5987)
  • Fixed an issue preventing MGLAnnotationView from animating when its coordinate changes. (#6215)
  • Fixed an issue causing the wrong annotation view to be selected when tapping an annotation view with a center offset applied. (#5931)
  • Fixed an issue that assigned annotation views to polyline and polygon annotations. (#5770)
  • Fixed an issue causing the callout view to be dismissed when panning around. (#6676)
  • Per documentation, the first and last coordinates in an MGLPolygon must be identical in order for the polygon to draw correctly. The same is true for an MGLPolygon’s interior polygon. (#5514)
  • To make an MGLPolyline or MGLPolygon span the antimeridian, specify coordinates with longitudes greater than 180° or less than −180°. (#6088)
  • Deprecated -[MGLMapViewDelegate mapView:alphaForShapeAnnotation:] in favor of specifying an alpha component via -[MGLMapViewDelegate mapView:strokeColorForShapeAnnotation:] or -[MGLMapViewDelegate mapView:fillColorForPolygonAnnotation:]. (#6706)
  • Various method arguments that are represented as C arrays of CLLocationCoordinate2D instances have been marked const to streamline bridging to Swift. (#7215)
  • Fixed an issue that caused an annotation view to disappear if it isn’t created using the annotation view reuse queue. (#6485)
  • Fixed an issue that could reset user-added transformations on annotation views. (#6166)
  • Improved the performance of relocating a non-view-backed point annotation by changing its coordinate property. (#5385)
  • Fixed an issue that caused an assertion failure if a MGLShapeCollection (a GeoJSON GeometryCollection) was created with an empty array of shapes. (#7632)
  • Improved the precision of annotations at zoom levels greater than 18. (#5517)

Networking and offline maps

  • Fixed an issue preventing an MGLMapView from loading tiles while an offline pack is downloading. (#6446)
  • Fixed a crash that sometimes occurred when initializing an MGLMapView. (#5932)
  • Fixed a crash that could occur when the device is disconnected while downloading an offline pack. (#6293)
  • Fixed a crash that occurred when encountering a rate-limit error in response to a network request. (#6223)
  • Fixed an issue causing an MGLOfflinePack’s progress to continue to update after calling -suspend. (#6186)
  • Fixed an issue preventing cached annotation images from displaying while the device is offline. (#6358)
  • Added support for an MGLMapboxAPIBaseURL key in an app’s Info.plist in order to customize the base URL used for retrieving map data, styles, and other resources. (#6709)
  • Query parameters are no longer stripped from mapbox: URLs used as resource URLs. (#6182, #6432)
  • Database errors are now logged to the console. (#6291)

Other changes

  • Raster tiles such as those from Mapbox Satellite are now cached, eliminating flashing while panning back and forth. (#7091)
  • Improved the performance of symbol style layers. (#7025)
  • As the user zooms in, tiles from lower zoom levels are scaled up until tiles for higher zoom levels are loaded. (#5143)
  • Notification names and user info keys are now string enumeration values for ease of use in Swift. (#6794)
  • MGLMapDebugOverdrawVisualizationMask no longer has any effect in Release builds of the SDK. This debug mask has been disabled for performance reasons. (#5555)
  • Fixed a typo in the documentation for the MGLCompassDirectionFormatter class. (#5879)
  • The UITapGestureRecognizer on MGLMapView that is used for selecting annotations now fails if a tap does not select an annotation. (#7246)
  • Fixed issues related to the visibility of sources in viewports less than 512 pixels wide or tall. (#7438)