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

There are three ways to install the Mapbox macOS SDK:

Manually

  1. Download the latest Mapbox macOS SDK release from GitHub – look for a release that begins with “macos-”.

  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.

Via Carthage

The Mapbox macOS SDK is a binary-only dependency, so you’ll need Carthage 0.19 or above. In your Cartfile, specify this dependency (plus an optional version requirement):

binary "https://mapbox.github.io/mapbox-gl-native/macos/Mapbox-macOS-SDK.json"

After running carthage update, you’ll find Mapbox.framework in the Carthage/Build/ folder. Follow these instructions to integrate it into your project.

Via CocoaPods

Create a Podfile with the following specification:

platform :osx, '10.10'

target 'TargetNameForYourApp' do
  pod 'Mapbox-iOS-SDK', '~> x.y'
end

where x.y is the current version. In Terminal, run pod install.

Usage

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.

Then, 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.5.0

This version of the Mapbox macOS SDK corresponds to version 3.6.0 of the Mapbox iOS SDK.

Packaging

Styles

  • Added support for 3D extrusion of buildings and other polygonal features via the MGLFillExtrusionStyleLayer class and the fill-extrusion layer type in style JSON. (#8431)
  • MGLMapView and MGLTilePyramidOfflineRegion now default to version 10 of the Mapbox Streets style. Similarly, several style URL class methods of MGLStyle return URLs to version 10 styles. Unversioned variations of these methods are no longer deprecated. MGLStyleDefaultVersion should no longer be used with any style other than Streets. (#6301)
  • Added class methods to MGLStyle that correspond to the new Traffic Day and Traffic Night styles. (#6301)
  • MGLSymbolStyleLayer’s iconImageName, iconScale, textFontSize, textOffset, and textRotation properties can now be set to a source or composite function. (#8544, #8590, #8592, #8593)
  • Fixed an issue where setting the MGLVectorStyleLayer.predicate property failed to take effect if the relevant source was not in use by a visible layer at the time. (#8653)
  • Fixed an issue preventing programmatically added style layers from appearing in already cached tiles. (#8954)
  • Fixed an issue causing a composite function’s highest zoom level stop to be misinterpreted. (#8613, #8790)
  • Fixed an issue where re-adding a layer that had been previously removed from a style would reset its paint properties. Moved initializers for MGLTileSource, MGLStyleLayer, and MGLForegroundStyleLayer to their concrete subclasses; because these classes were already intended for initialization only via concrete subclasses, this should have no developer impact. (#8626)
  • Fixed a crash that occurred when removing a source that was still being used by one or more style layers. Since this is a programming error, a warning is logged to the console instead. (#9129)
  • Feature querying results now account for any changes to a feature’s size caused by a source or composite style function. (#8665)
  • Fixed the behavior of composite functions that specify fractional zoom level stops. (#9289)
  • Letter spacing is now disabled in Arabic text so that ligatures are drawn correctly. (#9062)
  • Improved the performance of styles using source and composite style functions. (#9185, #9257)

Annotations

  • The default marker image has been made slightly larger and now matches the version in the Mapbox iOS SDK. (#9370)
  • The MGLPolyline.coordinate and MGLPolygon.coordinate properties now return the midpoint and centroid, respectively, instead of the first coordinate. (#8713)

User interaction

  • Fixed an issue causing the map to go blank during a flight animation that travels a very short distance. (#9199)
  • Fixed an issue causing the mouse cursor to jump after Shift- or Option-dragging the map. (#9390)
  • The Improve This Map button in the attribution action sheet now leads to a feedback tool that matches MGLMapView’s rotation and pitch. -[MGLAttributionInfo feedbackURLAtCenterCoordinate:zoomLevel:] no longer respects the feedback URL specified in TileJSON. (#9078)

Other changes

  • Fixed a crash when calling MGLMultiPolygon.coordinate #8713
  • Fixed an issue causing attribution button text to appear blue instead of black. (#8701)
  • Fixed a crash or console spew when MGLMapView is initialized with a frame smaller than 64 points wide by 64 points tall. (#8562)
  • The error passed into -[MGLMapViewDelegate mapViewDidFailLoadingMap:withError:] now includes a more specific description and failure reason. (#8418)
  • Improved CPU and battery performance while animating a tilted map’s camera in an area with many labels. (#9031)
  • Fixed an issue rendering polylines that contain duplicate vertices. (#8808)
  • Added struct boxing to MGLCoordinateSpan, MGLCoordinateBounds, MGLOfflinePackProgress, and MGLTransition. (#9343)