Mapbox macOS SDK

Put interactive, scalable world maps into your native Cocoa application with the open-source Mapbox macOS SDK.

  • Mapbox-curated map styles and OpenStreetMap-based vector tiles make it easy to get started.
  • Customize every aspect of the map’s appearance in code or visually using Mapbox Studio.
  • High-performance OpenGL rendering and multitouch gestures keep your users happy.
  • A well-designed, fully documented API helps you stay productive.
  • Develop across multiple platforms, including iOS, using the same styles and similar APIs.

The Mapbox macOS SDK is compatible with macOS 10.10.0 and above for Cocoa applications developed in Objective-C, Swift, Interface Builder, or AppleScript. For hybrid applications, consider Mapbox GL JS.

Installation

  1. Download the latest Mapbox macOS SDK release from GitHub – look for a release that begins with “macos-”. (Alternatively, you can integrate the Mapbox macOS SDK into your application using CocoaPods. If you do use CocoaPods, skip the next step.)

  2. Open the project editor, select your application target, then go to the General tab. Drag Mapbox.framework into the “Embedded Binaries” section. (Don’t drag it into the “Linked Frameworks and Libraries” section; Xcode will add it there automatically.) In the sheet that appears, make sure “Copy items if needed” is checked, then click Finish.

  3. Mapbox vector tiles require a Mapbox account and API access token. In the project editor, select the application target, then go to the Info tab. Under the “Custom macOS Application Target Properties” section, set MGLMapboxAccessToken to your access token. You can obtain an access token from the Mapbox account page.

Usage

In a storyboard or XIB:

  1. Add a view to your view controller or window. (Drag Custom View from the Object library to the View Controller scene on the Interface Builder canvas. In a XIB, drag it instead to the window on the canvas.)
  2. In the Identity inspector, set the view’s custom class to MGLMapView.
  3. MGLMapView needs to be layer-backed:
    • You can make the window layer-backed by selecting the window and checking Full Size Content View in the Attributes inspector. This allows the map view to underlap the title bar and toolbar.
    • Alternatively, if you don’t want the entire window to be layer-backed, you can make just the map view layer-backed by selecting it and checking its entry under the View Effects inspector’s Core Animation Layer section.
  4. Add a map feedback item to your Help menu. (Drag Menu Item from the Object library into Main Menu ‣ Help ‣ Menu.) Title it “Improve This Map” or similar, and connect it to the giveFeedback: action of First Responder.

If you need to manipulate the map view programmatically:

  1. Switch to the Assistant Editor.
  2. Import the Mapbox module.
  3. Connect the map view to a new outlet in your view controller class. (Control-drag from the map view in Interface Builder to a valid location in your view controller implementation.) The resulting outlet declaration should look something like this:
// ViewController.m
@import Mapbox;

@interface ViewController : NSViewController

@property (strong) IBOutlet MGLMapView *mapView;

@end

// ViewController.swift
import Mapbox

class ViewController: NSViewController {
    @IBOutlet var mapView: MGLMapView!
}

-- AppDelegate.applescript
script AppDelegate
    property parent : class "NSObject"
    property theMapView : missing value
end script

Full API documentation is included in this package, within the documentation folder, and online. The Mapbox iOS SDK’s API documentation and online examples apply to the Mapbox macOS SDK with few differences, mostly around unimplemented features like user location tracking.

Mapbox does not officially support the macOS SDK to the same extent as the iOS SDK; however, bug reports and pull requests are certainly welcome.

Changes in version 0.3.0

This version of the Mapbox macOS SDK corresponds to version 3.4.0 of the Mapbox iOS SDK. The two SDKs have very similar feature sets. The main differences are the lack of user location tracking and annotation views. Some APIs have been adapted to macOS conventions, particularly the use of NSPopover for callout views.

Packaging

  • Fixed an issue causing code signing failures and bloating the framework. (#5850)
  • Xcode 7.3 or higher is now required for using this SDK. (#6059)
  • Fixed an issue with symbols not being properly stripped from the dynamic framework when built with make xpackage SYMBOLS=NO. (#6531)
  • 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)
  • 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)
  • Fixed an issue where the style zoom levels were not respected when deciding when to render a layer. (#5811)
  • 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)
  • Attribution views now display the correct attribution for the current style. (#5999)
  • 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 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)
  • Fixed crashes that could occur when loading a malformed stylesheet. (#5736)
  • 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)

Annotations

  • Added showAnnotations:animated: and showAnnotations:edgePadding:animated:, which moves the map viewport to show the specified annotations. (#5749)
  • Added new methods to MGLMultiPoint for changing the vertices along a polyline annotation or the exterior of a polygon annotation. (#6565)
  • Fixed an exception raised when adding a custom annotation model object to MGLMapView. (#7746)
  • Added new APIs to MGLMapView to query for visible annotations. (#6061)
  • Shape, feature, and annotation classes now conform to NSSecureCoding. (#6559)
  • Various method arguments that are represented as C arrays of CLLocationCoordinate2D instances have been marked const to streamline bridging to Swift. (#7215)
  • To make an MGLPolyline or MGLPolygon span the antimeridian, specify coordinates with longitudes greater than 180° or less than −180°. (#6088)
  • Fixed an issue where placing a point annotation on Null Island also placed a duplicate annotation on its antipode. (#3563)
  • 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 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)
  • 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)
  • 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)
  • Fixed an issue where the map view’s center would always be calculated as if the view occupied the entire window. (#6102)
  • Notification names and user info keys are now string enumeration values for ease of use in Swift. (#6794)
  • Fixed a typo in the documentation for the MGLCompassDirectionFormatter class. (#5879)
  • The NSClickGestureRecognizer on MGLMapView that is used for selecting annotations now fails if a click does not select an annotation. (#7246)